金大哥 - memory-mcp MCP 详情

article

README

🚀 内存MCP服务

内存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会话，对话将自动保存并可被召回。

✨ 主要特性

会话开始 ──► 创建片段 ──► 监控进程（后台运行）
                                       │
用户消息 ──► 保存消息 ──► 召回相关记忆 ──► 注入上下文
                                       │
Claude回复 ──► 保存回复内容           │
                                       │
会话结束 ──► 关闭信号 ──► 存档片段 + 生成摘要

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

💻 使用示例

自动模式（配置钩子后）

配置钩子后，一切操作自动完成。Claude在对话时会将过往会话的相关历史作为上下文。

手动模式

你也可以在Claude Code中直接调用内存工具：

# 开始一个新片段
memory_start_episode("登录功能开发", ["auth"])

# 记录一个决策
memory_add_entity("Decision", "使用JWT + Redis", "用于分布式部署")

# 搜索历史
memory_recall("登录实现")

# 关闭片段
memory_close_episode("完成JWT登录功能")

📚 详细文档

钩子参考

| 钩子 | 功能 | 执行时间 | |------|-------------|--------| | SessionStart | 创建一个新片段 | 约50ms | | UserPromptSubmit | 保存用户消息并检索相关记忆 | 约1 - 2s | | Stop | 保存助手回复 | 约1s | | SessionEnd | 发出片段关闭信号 | 约50ms |

工具参考

| 工具 | 描述 | |------|-------------| | memory_start_episode | 开始一个新片段 | | memory_close_episode | 关闭并存档当前片段 | | memory_get_current_episode | 获取当前活动片段 | | memory_add_entity | 添加一个知识实体 | | memory_confirm_entity | 确认一个检测到的实体候选 | | memory_reject_candidate | 拒绝一个错误检测 | | memory_deprecate_entity | 将一个实体标记为过时 | | memory_get_pending | 列出待处理的实体候选 | | memory_recall | 跨片段和实体进行语义搜索 | | memory_search_by_type | 按类型搜索实体 | | memory_get_episode_detail | 获取完整的片段详情 | | memory_list_episodes | 按时间顺序列出所有片段 | | memory_stats | 获取系统统计信息 | | memory_encoder_status | 检查向量编码器状态 | | memory_cache_message | 手动缓存一条消息 | | memory_clear_cache | 清除消息缓存 | | memory_cleanup_messages | 清理旧的缓存消息 |

实体类型

| 类型 | 级别 | 描述 | |------|-------|-------------| | Decision | 项目 | 本项目的技术决策 | | Architecture | 项目 | 架构设计 | | File | 项目 | 重要文件描述 | | Preference | 用户 | 个人偏好（跨项目共享） | | Concept | 用户 | 通用概念 | | Habit | 用户 | 工作习惯 |

存储位置

用户级：~/.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

然后使用虚拟环境中的Python配置MCP服务器：

# 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

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

memory-mcp