Reference MCP 完全指南：用一套协议打通 Claude Code、Codex 和 Cursor 的会话记忆
如果你同时使用多个 AI 编码工具，一定遇到过这个场景：在 Claude Code 中刚刚调试完一个复杂问题，切换到 Codex CLI 想继续时，发现它完全不记得你们在 Claude 中讨论的内容。你不得不把前面的上下文再复述一遍——或者更糟，根本找不到那段重要的对话记录。
这不是你的问题，而是当前 AI 编码工具生态的结构性缺陷：每个工具的会话历史都默认为独立存储，彼此之间完全不透明。Claude Code 的会话放在 ~/.claude/projects/ 下的 JSONL 文件中，Codex 的会话在 ~/.codex/sessions/，Cursor 和 VS Code 又各有各的储存路径。它们之间没有天然的沟通渠道。
Reference MCP 正是为了解决这个痛点而生的开源项目。它是一个轻量级的 MCP（Model Context Protocol）服务器，用一个 uvx 命令就能注册到所有主流 AI 编码工具中，让它们共享会话记忆。
痛点：为什么多工具用户需要跨工具记忆
今天大量开发者同时使用多个 AI 编码工具来应对不同的开发场景：
| 工具 | 适用场景 |
|---|---|
| Claude Code | 复杂架构分析、长上下文推理 |
| Codex CLI | 快速原型、代码生成实验 |
| Cursor | 编辑器内日常编码、多文件重构 |
| VS Code + MCP | 自定义工作流集成 |
每个工具各自维护独立的会话历史。当一个 Agent 需要引用另一个 Agent 的工作成果时，要么手动复制粘贴，要么凭记忆重述。在多 Agent 协作日趋频繁的今天，这种信息孤岛已经成为生产力瓶颈。
Reference 的架构设计
Reference MCP 的核心思路非常简单：用一个统一的 MCP 服务器读取所有工具的会话文件，对外暴露一套标准的搜索和回忆接口。
四层架构
Claude Code ─┐ Codex CLI ─┤ Cursor ─┤──→ Reference MCP Server ──→ Adapters ──→ 会话文件 + 记忆文件 VS Code ─┘
- 适配器层（Adapters）：为每个工具声明会话文件和记忆文件的路径，以及对应的解析器。内置支持 Claude Code 和 Codex CLI，其他工具通过 TOML 配置添加。
- 解析器层（Parsers）：将各工具的 JSONL 格式统一转换为标准化的 Message 对象（包含来源、角色、文本、时间戳、会话和项目信息）。
- 搜索引擎层（Search）：使用纯 Python BM25 算法进行离线搜索，支持精确短语匹配、最近时间和项目的加权排序。缓存按文件修改时间自动失效。
- MCP 接口层（Server）：通过 MCP 协议暴露 6 个工具接口，供所有注册的 Agent 调用。
核心 MCP 工具
| 工具名 | 功能说明 |
|---|---|
recall | 一站式最佳匹配检索，同时搜索会话记录和记忆文件 |
search_sessions | 全文本搜索所有会话记录，支持按工具、项目、角色、时间过滤 |
search_memory | 搜索 CLAUDE.md、AGENTS.md、memory/*.md 等记忆文件 |
list_sessions | 列出最近的会话（按时间降序） |
get_session | 获取单个会话的完整清洗文本 |
list_sources | 显示已配置的工具及其文件数量 |
快速部署：三步打通跨工具记忆
第一步：安装依赖
Reference MCP 依赖 Python 的 uv 工具链。如果还没有安装 uv：
curl -LsSf https://astral.sh/uv/install.sh | sh
第二步：诊断可用会话
uvx --from git+https://github.com/Kuberwastaken/reference reference-mcp doctor
doctor 命令会扫描你的系统，列出它能访问到的每个工具的会话文件数和记忆文件数。如果你之前用过得 Claude Code 和 Codex CLI，这里应该能看到对应的数据。
第三步：注册到各工具
Claude Code
claude mcp add reference -- uvx --from git+https://github.com/Kuberwastaken/reference reference-mcp
Codex CLI — 编辑 ~/.codex/config.toml，加入以下配置：
[mcp_servers.reference] command = "uvx" args = ["--from", "git+https://github.com/Kuberwastaken/reference", "reference-mcp"]
Cursor — 编辑 ~/.cursor/mcp.json：
{
"mcpServers": {
"reference": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Kuberwastaken/reference", "reference-mcp"]
}
}
}
VS Code — 编辑 .vscode/mcp.json：
{
"servers": {
"reference": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Kuberwastaken/reference", "reference-mcp"]
}
}
}
注册完成后，你只需要在任意工具中提问「帮我搜索之前在 Codex 中关于 Gemini grounding 的讨论」或「我上周在 Claude 中做的评分模型决策是什么」，Reference 就能跨工具检索到对应的会话记录。
扩展能力：支持更多工具
Reference 支持通过 TOML 配置文件添加自定义工具。在 ~/.config/reference-mcp/reference.toml 中定义：
[[tool]] name = "cursor" session_globs = ["~/.cursor/chats/**/*.jsonl"] session_format = "generic" memory_globs = ["~/.cursor/rules/**/*.md"]
添加一个新工具后，它在所有其他工具中立即可见——Claude Code 可以搜索 Cursor 的历史，反之亦然。
隐私与安全
Reference 是完全本地优先的工具，只读不写。它不会修改你的任何会话文件，所有数据在本地通过 stdio 传输，不会上传到任何远程服务。你的会话中可能包含 API Key、源代码和业务逻辑，这些内容始终保留在本地。建议只在信任的 Agent 中注册 Reference。
总结
Reference MCP 用一个轻量级的 MCP 服务器解决了 AI 编码工具生态中的「记忆孤岛」问题。对日常使用多个编码 Agent 的开发者来说，它消除了跨工具协作中最令人沮丧的上下文丢失体验。6 个 MCP 工具覆盖了从简单回忆到复杂搜索的完整需求，配置只需一个 uvx 命令，适合任何规模的多工具工作流。
相关链接： – Reference GitHub 仓库 – MCP 协议 – uv 包管理器