🧠 AI Memory MCP

Persistent session memory for AI assistants — store, search and retrieve conversation summaries via the Model Context Protocol.

Python MCP License: MIT Tests

What is this?

AI assistants forget everything between sessions. AI Memory MCP solves that by giving your AI a structured long-term memory:

📝 Save session summaries with status, tags, modules and file paths
🔍 Search by keyword, full-text (FTS5), or semantic vector similarity
🔄 Restore context at the start of each session with one tool call
📊 Generate weekly reports from completed tasks automatically
🏷️ Multi-project / multi-branch support out of the box

Works with Claude Desktop, Cursor, VS Code, Windsurf, and any MCP-compatible client.

Quick Start

1 — Install

# From PyPI (recommended)
pip install ai-memory-mcp

# With vector search support (adds ~500 MB for embedding model)
pip install "ai-memory-mcp[vector]"

# From source
git clone https://github.com/zhanpu89/ai-memory-mcp
cd ai-memory-mcp
pip install -e .

2 — Configure your AI client

Pick the config snippet for your tool and add it to its MCP settings file:

{
  "mcpServers": {
    "ai-memory": {
      "command": "ai-memory-mcp"
    }
  }
}

{
  "mcpServers": {
    "ai-memory": {
      "command": "ai-memory-mcp"
    }
  }
}

{
  "servers": {
    "ai-memory": {
      "type": "stdio",
      "command": "ai-memory-mcp"
    }
  }
}

{
  "mcpServers": {
    "ai-memory": {
      "command": "ai-memory-mcp"
    }
  }
}

Start the server:

ai-memory-mcp --http
# or: python service.py start

Then point your client at:

{
  "mcpServers": {
    "ai-memory": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

All config snippets are available in integrations/.

3 — Use it

At the start of every session, tell your AI:

Load my memory for project "my-project"

The AI will call init_session and restore your previous context automatically.

Features

Feature	Details
Storage	SQLite — zero external services, single file
Full-text search	SQLite FTS5 — fast, no extra deps
Semantic search	ChromaDB + `all-MiniLM-L6-v2` (optional)
Multi-project	Filter by `project_name` + `branch_name`
Task lifecycle	`pending → in_progress → completed / blocked / abandoned`
Key decisions	Attach architectural decisions to sessions
Weekly reports	Auto-generated Markdown report
Transport	stdio (local) or streamable-HTTP (remote)
Docker	Single-container deployment included

Architecture

┌─────────────────────────────────────────────────┐
│               AI Client (Claude / Cursor …)      │
│                    MCP Protocol                  │
└──────────────────────┬──────────────────────────┘
                       │ stdio / HTTP
┌──────────────────────▼──────────────────────────┐
│              AiMemoryMcpServer (FastMCP)         │
│                                                  │
│  ┌──────────────┐    ┌──────────────────────┐   │
│  │  SQLite DB   │    │  ChromaDB (optional) │   │
│  │  FTS5 index  │    │  Sentence-Transformers│  │
│  └──────────────┘    └──────────────────────┘   │
└─────────────────────────────────────────────────┘

Data lives in ~/.ai-memory/ — completely separate from your project files.

Tool Reference

→ See TOOLS.md for the full schema of all 10 tools.

Tool	Description
`save_summary`	Persist a new session summary
`update_summary`	Update status / content
`add_decision`	Record a key technical decision
`search_summaries`	Keyword / FTS5 / vector search
`search_summaries_fts`	Dedicated FTS5 full-text search
`get_summary_by_id`	Exact lookup by session ID
`list_recent_sessions`	List latest sessions
`init_session`	Restore context at session start
`weekly_review`	Generate Markdown weekly report
`maintenance`	Rebuild index, VACUUM, persist vectors

Configuration

All settings are optional — sensible defaults work out of the box.

Env var	Default	Description
`AI_MEMORY_DB_PATH`	`~/.ai-memory/ai_memory.db`	SQLite database path
`AI_MEMORY_MODEL_PATH`	`~/.ai-memory/models`	Embedding model cache
`AI_MEMORY_HOST`	`127.0.0.1`	HTTP server bind address
`AI_MEMORY_PORT`	`8000`	HTTP server port

Create ~/.ai-memory/.env to persist settings:

AI_MEMORY_DB_PATH=/custom/path/ai_memory.db
AI_MEMORY_PORT=9000

Docker

Optimized for China: Uses Tsinghua pip mirror + HuggingFace mirror for fast downloads.

# Option 1: Core-only (lightweight, ~200 MB image)
docker compose up -d

# Option 2: Full (with vector search)
# Step 1: Pre-download model to avoid large image
python3 scripts/download_model_for_docker.py --output ./models

# Step 2: Build with vector support (~700 MB image + 500 MB external model)
docker compose build --build-arg INSTALL_VECTOR=true
docker compose up -d

# View logs
docker compose logs -f

The MCP endpoint will be available at http://localhost:8000/mcp.

📖 Full deployment guide: See DOCKER.md for:

Image size optimization strategies
Chinese mirror configuration
Model pre-downloading
Production deployment examples

Development

# Clone and install in editable mode with dev extras
git clone https://github.com/zhanpu89/ai-memory-mcp
cd ai-memory-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/mcp_server --cov-report=term-missing

# Start in HTTP mode for manual testing
ai-memory-mcp --http

Project Structure

ai-memory-mcp/
├── src/mcp_server/
│   ├── __init__.py
│   └── server.py          # All 10 MCP tools + server class
├── tests/
│   ├── unit/              # 24 unit tests
│   └── integration/
├── scripts/
│   ├── download_model.py  # Manual model download
│   ├── migrate_db.py      # Database migration helper
│   └── migrate_vector.py  # Vector store migration
├── integrations/          # Ready-to-use MCP client configs
│   ├── claude_desktop_config.json
│   ├── cursor_mcp.json
│   ├── vscode_mcp.json
│   ├── windsurf_mcp.json
│   └── http_mode_config.json
├── TOOLS.md               # Full tool schema reference
├── INSTALL.md             # Detailed installation guide
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml

Testing

24 passed in 7s

pytest tests/unit/test_mcp_server.py -v

All 24 unit tests cover: save/update/search/FTS/vector/decisions/maintenance/init/review/schema.

Requirements

Python 3.10+
mcp >= 1.6.0
python-dotenv >= 1.0.0

Optional (vector search):

chromadb >= 0.6.0
sentence-transformers >= 3.0.0