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

Related MCP server: engram

Database Schema

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

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:

npm install

3. Build the TypeScript code:

npm run build

Usage

MCP Mode (Stdio Transport)

To run as an MCP server using stdio transport:

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

HTTP Server Mode

To run as a standalone HTTP server:

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:

{
  "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:

{
  "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:

{
  "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