🧠 AI Memory MCP

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

---

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:

<details> <summary><b>Claude Desktop</b> — <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>

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

</details>

<details> <summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>

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

</details>

<details> <summary><b>VS Code (GitHub Copilot)</b> — <code>.vscode/mcp.json</code></summary>

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

</details>

<details> <summary><b>Windsurf</b> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>

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

</details>

<details> <summary><b>HTTP mode</b> (remote / Docker / team)</summary>

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

</details>

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

---

License

MIT © AI Memory Team