memory-mcp

Memory MCP Service

English | 中文

一款适用于 Claude Code 的持久化记忆 MCP 服务。它会自动保存对话，并在不同会话中检索相关历史记录。

功能说明： 每次与 Claude Code 对话时，系统都会保存对话上下文（决策、偏好和重要讨论），并在未来的会话中自动回忆相关内容，让 Claude 始终掌握所需的背景信息。

快速开始

前置条件

安装 uv（Python 包运行器）：

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

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

需要 Python 3.10 - 3.13（chromadb 与 Python 3.14+ 不兼容）。

1. 初始化（仅首次需要）

下载向量模型（约 400MB，仅需下载一次）：

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

2. 将 MCP 服务添加到 Claude Code

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

3. 配置钩子（推荐）

配置钩子可实现完全自动保存消息。不配置钩子时，你需要手动调用记忆工具。

将以下内容添加到 ~/.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. 验证

claude mcp list

你应该会看到 memory-mcp: ... - ✓ Connected。

完成！启动新的 Claude Code 会话后，你的对话将自动保存并在之后被回忆。

工作原理

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

• 片段：每个对话会话都是一个“片段”，并会自动生成摘要
• 实体：从对话中提取的关键信息（决策、偏好、概念）
• 双层存储：用户级（跨项目共享）+ 项目级（每个项目隔离）
• 语义搜索：基于向量的检索，可查找相关的过往上下文

使用方法

自动模式（使用钩子）

配置钩子后，所有操作都会自动完成。Claude 会将过往会话中的相关历史记录作为上下文。

手动模式

你也可以在 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")

钩子参考

工具参考

实体类型

存储位置

• 用户级：~/.claude-memory/
• 项目级：{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

作者

陈佳俊 (Jiajun Chen) —— 常驻中国杭州的前端工程师。 GitHub @chenxiaofie · [email protected]

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

许可证

MIT License - 详情请参阅 LICENSE 文件。