Ai Memory

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

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

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

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.

Configuration

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

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

License

MIT © AI Memory Team