Memory MCP

🚀 Memory MCP Service

A persistent memory MCP service for Claude Code. It automatically saves conversations and retrieves relevant history across sessions, providing Claude with the necessary background information for seamless interactions.

🚀 Quick Start

Prerequisites

Install uv (Python package runner):

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Requires Python 3.10 - 3.13 (chromadb is not compatible with Python 3.14+).

1. Initialize (First Time Only)

Download the vector model (~400MB, one-time):

uvx --from chenxiaofie-memory-mcp memory-mcp-init

2. Add MCP Server to Claude Code

claude mcp add memory-mcp -s user -- uvx --from chenxiaofie-memory-mcp memory-mcp

3. Configure Hooks (Recommended)

Hooks enable fully automatic message saving. Without hooks, you need to manually call memory tools. Add the following to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-session-start" }]
    }],
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-auto-save" }]
    }],
    "Stop": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-save-response" }]
    }],
    "SessionEnd": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-session-end" }]
    }]
  }
}

4. Verify

claude mcp list

You should see memory-mcp: ... - ✓ Connected.

That's it! Start a new Claude Code session and your conversations will be automatically saved and recalled.

✨ Features

• Episodes: Each conversation session is an "episode" with auto-generated summaries.
• Entities: Key knowledge extracted from conversations (decisions, preferences, concepts).
• Dual-layer storage: User-level (shared across projects) + Project-level (isolated per project).
• Semantic search: Vector-based retrieval finds relevant past context.

💻 Usage Examples

Automatic Mode (With Hooks)

Once hooks are configured, everything is automatic. Claude will see relevant history from past sessions as context.

Manual Mode

You can also call memory tools directly in Claude Code:

# Start a new episode
memory_start_episode("Login Feature Development", ["auth"])

# Record a decision
memory_add_entity("Decision", "Use JWT + Redis", "For distributed deployment")

# Search history
memory_recall("login implementation")

# Close episode
memory_close_episode("Completed JWT login feature")

📚 Documentation

Hooks Reference

Tools Reference

Entity Types

Storage Locations

• User-level: ~/.claude-memory/
• Project-level: {project-root}/.claude/memory/

git clone https://github.com/chenxiaofie/memory-mcp.git
cd memory-mcp
# Windows:
install.bat
# Mac/Linux:
chmod +x install.sh && ./install.sh

# Windows:
claude mcp add memory-mcp -s user -- "C:\path\to\memory-mcp\venv310\Scripts\python.exe" -m memory_mcp.server

# Mac/Linux:
claude mcp add memory-mcp -s user -- /path/to/memory-mcp/venv310/bin/python -m memory_mcp.server

📄 License

MIT License - see LICENSE file for details.