# Memory Server - MCP Server for Persistent Memory Management

A TypeScript-based Model Context Protocol (MCP) server that provides persistent memory management using SQLite database. This server exposes both MCP tools and RESTful API endpoints for storing and retrieving conversational context with metadata.

## Features

- **SQLite Database Integration**: Persistent storage with automatic schema creation and indexing
- **MCP Protocol Compliance**: Full support for MCP tool registration and execution
- **RESTful API**: HTTP endpoints for programmatic access
- **TypeScript**: Full type safety and modern async/await patterns
- **Logging**: Comprehensive logging with configurable levels
- **Error Handling**: Robust error handling and input validation
- **Database Connection Pooling**: Optimized database performance
- **Modular Architecture**: Clean separation of concerns

## Database Schema

The server automatically creates a SQLite database with the following schema:

```sql
CREATE TABLE memory (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  content TEXT NOT NULL,
  timestamp TEXT NOT NULL,
  session_id TEXT NOT NULL,
  content_hash TEXT NOT NULL UNIQUE,
  metadata TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Indexes for performance optimization
CREATE INDEX idx_session_id ON memory(session_id);
CREATE INDEX idx_timestamp ON memory(timestamp);
CREATE INDEX idx_content_hash ON memory(content_hash);
CREATE INDEX idx_created_at ON memory(created_at);
```

## Installation

1. Clone or create the project directory
2. Install dependencies:

```bash
npm install
```

3. Build the TypeScript code:

```bash
npm run build
```

## Usage

### MCP Mode (Stdio Transport)

To run as an MCP server using stdio transport:

```bash
npm start -- --mcp
# or
MCP_MODE=true npm start
```

### HTTP Server Mode

To run as a standalone HTTP server:

```bash
npm start
```

The server will start on `http://localhost:3000` by default.

## Environment Variables

- `PORT`: HTTP server port (default: 3000)
- `HOST`: HTTP server host (default: localhost)
- `DB_PATH`: SQLite database file path (default: ./data/memory.db)
- `DB_MAX_CONNECTIONS`: Maximum database connections (default: 10)
- `LOG_LEVEL`: Logging level (debug, info, warn, error) (default: info)
- `CORS_ORIGIN`: Comma-separated list of allowed CORS origins
- `MCP_MODE`: Set to 'true' to run in MCP mode
- `NODE_ENV`: Environment (development, production)

## MCP Tools

The server provides the following MCP tools:

### save_memory

Saves content to memory with metadata.

**Parameters:**
- `content` (string, required): The content to save
- `session_id` (string, required): Session identifier for grouping
- `metadata` (object, optional): Additional metadata

**Example:**
```json
{
  "content": "User prefers dark mode and uses TypeScript",
  "session_id": "user-123-session-1",
  "metadata": {
    "category": "preferences",
    "importance": "high"
  }
}
```

### read_memory

Retrieves stored memories with optional filtering.

**Parameters:**
- `session_id` (string, optional): Filter by session ID
- `start_date` (string, optional): Filter from date (ISO format)
- `end_date` (string, optional): Filter until date (ISO format)
- `limit` (number, optional): Maximum records to return (1-1000)
- `offset` (number, optional): Records to skip for pagination

### get_memory_count

Gets the total count of memory records.

**Parameters:**
- `session_id` (string, optional): Count for specific session

### delete_memory

Deletes a specific memory record.

**Parameters:**
- `id` (number, required): ID of the memory record to delete

## REST API Endpoints

### POST /api/memory/save

Save a new memory record.

**Request Body:**
```json
{
  "content": "Content to save",
  "session_id": "session-identifier",
  "metadata": {
    "key": "value"
  }
}
```

### GET /api/memory/read

Read memory records with optional query parameters:
- `session_id`: Filter by session
- `start_date`: Filter from date
- `end_date`: Filter until date
- `limit`: Maximum records
- `offset`: Pagination offset

### GET /api/memory/count

Get memory count with optional `session_id` query parameter.

### DELETE /api/memory/:id

Delete a specific memory record by ID.

### GET /api/memory/health

Health check endpoint.

## MCP Server Configuration

To use this server with an MCP client, add it to your MCP settings:

```json
{
  "mcpServers": {
    "memory-server": {
      "command": "node",
      "args": ["path/to/memory-server/build/index.js", "--mcp"],
      "env": {
        "DB_PATH": "path/to/memory.db",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

## Development

### Scripts

- `npm run build`: Compile TypeScript to JavaScript
- `npm run dev`: Watch mode for development
- `npm start`: Start the server

### Project Structure

```
memory-server/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── database.ts       # SQLite database operations
│   ├── api.ts           # REST API routes
│   ├── mcp-tools.ts     # MCP tool handlers
│   ├── logger.ts        # Logging utility
│   └── types.ts         # TypeScript interfaces
├── build/               # Compiled JavaScript (generated)
├── data/               # Database files (generated)
├── package.json
├── tsconfig.json
└── README.md
```

## Error Handling

The server includes comprehensive error handling:

- Input validation for all endpoints and tools
- Database connection error handling
- Graceful shutdown on SIGTERM/SIGINT
- Detailed error logging
- Proper HTTP status codes

## Performance Optimization

- Database indexes on frequently queried columns
- Connection pooling for database operations
- Efficient query patterns
- Content hashing to prevent duplicates
- Configurable limits and pagination

## Security Considerations

- Input validation and sanitization
- CORS configuration
- Content hash verification
- SQL injection prevention through parameterized queries
- Error message sanitization in production

## License

MIT License