Memory Mcp

Memory MCP Service

[PyPI version] [Python] [License: MIT]

English | 中文

A persistent memory MCP service for Claude Code. Automatically saves conversations and retrieves relevant history across sessions.

What it does: Every time you chat with Claude Code, your conversation context (decisions, preferences, key discussions) is saved and automatically recalled in future sessions — so Claude always has the background it needs. [Memory recall demo - retrieving past session history]

Quick Start

Prerequisites

Install uv (Python package runner):

# Windowspowershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Mac/Linuxcurl -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.

How It Works

Session Start ──► Create Episode ──► Monitor Process (background)                                          │User Message  ──► Save Message ──► Recall Related Memories ──► Inject Context                                          │Claude Reply  ──► Save Response           │                                          │Session End   ──► Close Signal ──► Archive Episode + Generate Summary

• 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

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 episodememory_start_episode("Login Feature Development", ["auth"])
# Record a decisionmemory_add_entity("Decision", "Use JWT + Redis", "For distributed deployment")
# Search historymemory_recall("login implementation")
# Close episodememory_close_episode("Completed JWT login feature")

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.gitcd 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

Author

陈佳俊 (Jiajun Chen) — front-end engineer based in Hangzhou, China. GitHub @chenxiaofie · [email protected]

本项目由陈佳俊（GitHub: chenxiaofie）开发并维护。

License

MIT License - see LICENSE file for details.