打造AI编码工具共享记忆中枢：Claude、Codex、Cursor统一决策

如果你同时用 Claude Code、OpenAI Codex 和 Cursor 写代码，迟早会遇到这样的场面：上午用 Claude Code 定下来缓存层用某个方案，下午切到 Cursor 问同一个问题，它像完全没参与过一样重新讨论；再过两天 Codex 又给出了第三个版本，项目里开始出现三套风格并存的代码。我一开始以为是模型智商有差异，后来发现根子在于每个工具的记忆是互相隔离的。它们虽然都在看同一个仓库，但仓库里并没有存放“我们为什么会这样设计”的信息，只有代码本身。于是我做了一个本地优先的开源协作中枢：一个独立的记忆仓库，Claude、Codex、Cursor 都从里面读取同一套事实与决策，也把每次会话产生的新结论写回去。跑了几周之后，工具之间那种“失忆感”基本消失了。

这篇文章写给谁？如果你只有一台编辑器，只有一个 AI 编码工具，那直接用默认的 CLAUDE.md 或 AGENTS.md 就够了，不需要折腾。但只要你同时用两三个工具，或者和你一起写代码的人用不同工具，或者你希望能把 AI 之前的判断沉淀成项目资产，那这套本地优先的中枢方案就非常适合。它不是某个大厂的全家桶，而是由 MCP、Markdown 文件和一个 SQLite 索引拼起来的轻量架构，代码量很小，完全开源，你可以按自己的需求改。

1. 为什么要给三个 AI 编码工具搭一个共享记忆层

1.1 三个工具各自的“记忆”机制

先说点背景。Claude Code、OpenAI Codex、Cursor 这三个工具的记忆机制完全不一样，这也是它们互相“不认识”的根本原因。

Claude Code 最核心的记忆载体是项目根目录下的 CLAUDE.md。每次启动时，它会自动读这个文件当作系统级背景信息。你还可以在对话里用@路径或#记忆直接引用某个文档。除此之外，它在本地~/.claude/projects/下存了会话历史，但这些历史不会被 Cursor 或 Codex 读取。

Codex CLI 这边，新版主推的是 AGENTS.md。这个文件放在仓库根目录，类似 CLAUDE.md 的角色，写的是项目约定、构建命令、架构约束等。Codex 的会话记录也存在本地，但同样不会和其他工具互通。

Cursor 的做法又不一样。它的规则放在.cursor/rules/目录里，支持.mdc文件并通过 glob 匹配生效。比如某个文件只在编辑src/api下代码时加载，另一个文件在你打开docs目录时生效。Cursor 还会用代码索引和当前打开的标签页来做上下文，所以它“看到”的东西和前两个工具有很大重叠，但“记住”的偏好完全是另一套。

问题很清楚：三个工具都能看代码仓库，但仓库只是代码快照，不是“记忆”。代码里有最终结果，却没有为什么要这么写的推理过程。架构选型、避坑记录、代码风格偏好、命令习惯，这些才是记忆，而它们目前散落在三个互相隔离的上下文里。

1.2 最典型的碎片化场景

我举个例子。上个月我重构一个内部工具的数据加载逻辑。上午用 Claude Code 分析后，决定用生产者消费者队列来限制并发，并且在 CLAUDE.md 里记了一句“并发相关改动参考>memory-hub/ ├── MEMORY.md # 总索引，控制在 100 行以内 ├── architecture/ │ └──>## 数据加载并发方案 - 状态：已定稿 - 决策：使用生产者消费者队列，禁止新增无界异步并发 - 背景：详见 architecture/data-loader.md - 涉及文件：src/loader/*

这样做的好处是，Claude Code 和 Codex 在启动时通过 CLAUDE.md/AGENTS.md 只加载这段摘要，不会把一整个架构文档塞进上下文。如果需要更多细节，再让模型主动去读对应的完整 Markdown 文件。

2.3 记忆类型划分

我把写进 memory-hub 的内容分成四类，分类清晰之后，回写和检索都省心不少。

• 事实型：项目技术栈、目录结构、环境变量说明、构建命令。这类内容基本不变化，适合放在 MEMORY.md 里。
• 决策型：某个技术选型为什么是 A 而不是 B，当时比较过哪些方案，最终取舍标准是什么。这类是记忆中枢最核心的资产。
• 流程型：发布流程、Code Review 要求、测试执行规范。适合写成 runbook，让任何工具触发时都能按部就班执行。
• 阻坑型：某类问题反复出现，以及标准的排查步骤。这类记录价值最高，但最容易被忽略。我会在回写规则里特别强调，遇到 bug 修复后必须补一条笔记。

记忆分类的核心原则是：轻量的进 MEMORY.md，重细节的单独成文件，索引里留路径。所有文件都必须能在 5 分钟内读明白，不能变成第二个代码库。

2.4 本地优先带来的额外能力

本地文件加 Git 仓库的组合，让我获得了几个预想之外的好处。

一是支持多人协作。我的同事用 Cursor，我用 Claude Code，我们共享同一个 memory-hub 仓库。每次他让 Cursor 记录某个 API 变更，我这边 Claude 一启动就能看到。团队里大家的“口径”慢慢统一了。

二是天然支持回滚。有一次 Cursor 的规则写得太激进，要求所有新代码都必须用某个库，结果它自己也到处乱用。我看了 git diff，发现不对，直接回滚到上一个版本，三秒搞定。这种事情在云端知识库里做起来绝对没那么顺手。

三是离线可用。我在高铁上写代码时经常没网，云端记忆基本就是废的。本地 memory-hub 用 SQLite 和本地文件，没有任何外部依赖，断网时三个工具的“记忆”依然在。这一点很现实，我之前的云端方案就是在一次离线场景里被优化掉的。

3. 从零搭建一个可用的共享记忆中枢

3.1 初始化项目结构与 Git 仓库

先建目录，再初始化 Git。

mkdir memory-hub && cd memory-hub git init mkdir -p architecture decisions conventions runbooks sessions scripts touch MEMORY.md

这里我给两点建议。第一，memory-hub 要用独立仓库，不要塞进主项目的仓库里。因为它变更频率高，塞在主仓库里会让主仓库的 commit 噪音很大；而且有些记忆可能涉及敏感逻辑，独立仓库方便你单独设置权限。第二，.gitignore要把sessions/和index.sqlite排除掉。sessions 只是过程记录，没必要提交；索引可以根据 Markdown 文件随时重建，提交了反而容易冲突。

3.2 编写第一版 MEMORY.md

MEMORY.md 不用一开始就写全，先写一个能回答“项目是什么、用什么技术栈、有哪些固定约定”的版本，后续再逐步补充。

# 项目记忆索引 ## 项目概览 - 产品：内部工单处理平台 - 技术栈：TypeScript / React / Node.js / PostgreSQL - 运行方式：pnpm dev，本地依赖 docker compose 里的 pg ## 目录约定 - src/api：后端路由层，严禁直接写 SQL - src/services：业务逻辑层，事务必须在这里控制 - src/types：共享类型定义 ## 固定决策 - 后端统一返回 `{ code, data, message }` 结构 - 所有外发邮件通过消息队列发送，禁止在请求线程里直接调 SMTP - 缓存优先使用 Redis，避免自建内存缓存 ## 常用命令 - 启动：pnpm dev - 测试：pnpm test --runInBand - 规范检查：pnpm lint

然后把这段内容软链接给 Codex 的 AGENTS.md 和 Claude 的 CLAUDE.md 用，至少保证这几个工具都先能读到项目事实。

3.3 通过 MCP Server 让 Claude Code 和 Cursor 共用同一份记忆

MCP 是这套中枢里最关键的适配器。我写了一个简单的 Python MCP Server，核心就四个工具函数：读取某个主题、搜索关键词、追加决策、更新状态。

# mcp_server.py from pathlib import Path from mcp.server.fastmcp import FastMCP HUB_PATH = Path(__file__).resolve().parent mcp = FastMCP("memory-hub") def _safe_topic(topic: str) -> Path: # 防止路径穿越，只允许访问 memory-hub 内的文件 target = (HUB_PATH / topic).resolve() if not str(target).startswith(str(HUB_PATH)): raise ValueError("topic 非法") return target @mcp.tool() def read_memory(topic: str) -> str: """读取 memory-hub 中指定主题的完整内容，topic 是相对路径，如 architecture/data-loader""" path = _safe_topic(topic + ".md") if not path.exists(): return "没有找到对应记忆，请确认主题路径或查看 MEMORY.md" return path.read_text(encoding="utf-8") @mcp.tool() def search_memory(keyword: str) -> str: """按关键词搜索所有记忆文件，返回文件名和摘要片段""" results = [] for md in HUB_PATH.glob("**/*.md"): text = md.read_text(encoding="utf-8", errors="ignore") if keyword in text: lines = [l.strip() for l in text.splitlines() if keyword in l] results.append(f"{md.relative_to(HUB_PATH)}: {lines[0][:80] if lines else ''}") return "\n".join(results[:20]) or "没有匹配结果" @mcp.tool() def append_memory(category: str, title: str, content: str) -> str: """追加一条记忆，category 如 decisions/conventions，title 作为文件名""" safe_name = title.replace(" ", "-")[:40] path = _safe_topic(f"{category}/{safe_name}") if path.exists(): path = path.with_name(f"{path.stem}-{len(list(HUB_PATH.joinpath(category).glob('*')))}.md") path.write_text(f"# {title}\n\n{content}\n", encoding="utf-8") return f"已写入 {path.relative_to(HUB_PATH)}"

这个服务的启动方式我用的 stdio，不占用端口，也就没有端口冲突问题。Claude Code 和 Cursor 的配置分别放在各自项目配置文件里。

Claude Code 在项目根目录的.mcp.json：

{ "mcpServers": { "memory-hub": { "command": "python", "args": ["mcp_server.py"], "cwd": "/absolute/path/to/memory-hub" } } }

Cursor 在.cursor/mcp.json，内容几乎一样。这样两个工具启动后，都能看到memory-hub这一组 MCP 工具。Cursor 用 Agent 模式时，它会自行判断是否需要调用这些工具；Claude Code 则是只要规则文件里提到“遇到不确定的项目决策时先查 memory-hub”，它就会主动用。

3.4 给 Codex CLI 接入记忆

Codex CLI 对 MCP 的支持我踩过几次坑，目前最稳的方案不是 MCP，而是 AGENTS.md 软链接。假如项目里已经有自己的 AGENTS.md，那就不能直接覆盖，我会在主项目的 AGENTS.md 末尾追加一句：

## 项目记忆 项目历史决策、架构方案、避坑记录统一存放在独立仓库 memory-hub 中。 需要了解某个模块的设计背景时，先阅读 /absolute/path/to/memory-hub/MEMORY.md 的对应章节； 如果需要完整背景，再读取 architecture/ 或 decisions/ 下对应的 Markdown 文件。

如果项目本来没有 AGENTS.md，那更简单，直接软链过来：

ln -s /absolute/path/to/memory-hub/MEMORY.md /path/to/project/AGENTS.md

但要注意，软链接方案有一个副作用：MEMORY.md 里如果写了比较多的细节，Codex 每次启动都会全量读取，容易把上下文撑爆。所以我才会强调 MEMORY.md 必须控制在 100 行以内，只放摘要和指针。这样 Codex 读到的是路线图，细节按需再看原文。

3.5 自动回写：让每次会话都给中枢“投喂”

读只是第一步，让 AI 把新结论写回来才是这套系统真正值钱的地方。我在每个工具的规则文件里都加了一条统一约定，内容差不多是这样：

## 记忆回写规则 当你在本次会话中完成了以下任意一件事，请在结束时同步更新 memory-hub 仓库： 1. 做出了一个影响后续开发的架构决策； 2. 修复了一个之前反复出现的问题； 3. 发现某个工具或命令的用法和文档不一致； 4. 明确了某个代码区域的 Ownership 或调用约束。 更新时按类型写入 architecture/、decisions/、conventions/、runbooks/ 下的对应文件。 如果只是简单补充，使用 append_memory 工具；如果修改现有内容，先读取原文件再重写，保持历史可追溯。

这条规则挺有用，但也有翻车的时候。AI 有时会“一本正经”地写一篇很长的架构文档，其实内容是瞎编的。我的做法是：所有回写必须经过 Git diff 审核，不能直接信任。每次会话结束后，我都会看一眼新增了什么，不对就回滚。这样既保留了 AI 的效率，也保证了记忆的质量。

4. 关键配置参数与使用细节

4.1 上下文注入还是按需检索

这里强调一个原则：启动注入少量，细节按需读取。如果把所有记忆都塞进初始提示，上下文窗口很快就满了，模型的注意力会被稀释，反而记不住最要紧的东西。

我目前的配比是：MEMORY.md 只存摘要，Claude Code 和 Codex 启动时加载；architecture 和 decisions 的完整内容完全不进提示词，由 MCP 或@file按需读取；runbooks 基本不进提示词，只有当用户明确问“怎么发布”“怎么跑测试”时才去读。

举个例子，Claude Code 里我不会把阅读记忆的步骤写死，而是直接在 CLAUDE.md 里约定：

当讨论到某个模块的架构设计时，先用 read_memory 读取 architecture/ 下对应的文件，只有找不到时才自行推断。

这样每次讨论都基于仓库里的历史决策，而不是模型脑补。

4.2 更新冲突与版本管理

多人共用 memory-hub 时，最烦的问题就是冲突。两个人同时让各自工具往decisions/写文件，很可能因为文件名一样、内容不同产生 merge 冲突。

我的解决办法有三个。第一，文件命名强制带日期：decisions/2025-06-13-data-loader-queue.md。这样即使撞主题，文件名也都不同，基本不会冲突。第二，回写尽量用 append 而不是 rewrite，新决策单独成文，不修改旧文件。第三，每个文件里都记录“状态”字段，已废弃的决策通过状态标注置为过期，而不是物理删除。

MEMORY.md的冲突是另一个难点，因为大家都可能改它。我的处理是把它当作“目录页”，只允许在末尾追加新条目，不允许随意改旧条目。任何结构性修改都由人来完成，AI 只负责按模板追加。

4.3 几个实用参数配置建议

MCP 服务不用端口，走 stdio，所以没有端口占用问题，但 Python 环境依赖要保证三端一致。如果启动报模块找不到，优先检查PYTHONPATH和当前虚拟环境。

Claude Code 自身的max_turns、permission_mode这些参数和记忆直接关系不大，重点是别在规则里给太多操作自由度。我建议在回写规则里明确“写入前先读取现有文件”，防止 AI 接管整个 memory-hub。

Cursor 那边最好把Agent模式下的模型温度和长上下文参数按默认来，不需要特别调。真要调的是.cursor/rules/的文件匹配规则。比如：

--- glob: "**/*.{ts,tsx}" ---

这样规则只会在打开 TypeScript 文件时生效，既控制上下文，又能精准对齐场景。

4.4 安全边界：哪些记忆不该进共享区

很多人只想着“怎么让 AI 记住更多”，却忽略了记忆仓库本身是敏感信息的集散地。我明确要求 memory-hub 里禁止出现下面几类内容：

• API Key、数据库密码、密钥、token；
• 客户往返的机密数据；
• 未公开的融资、人事、收购等信息；
• 个人隐私类信息，比如同事内部联系方式。

我的建议是在 memory-hub 根目录放一个.env-sample，需要敏感值的地方只写占位符：

DB_PASSWORD=<从本地 .env 读取>

然后在规则文件里让 AI 遇到敏感信息时只用占位符，不要把真实值写进记忆文件。仓库如果使用公开 GitHub 仓库承载，那更要小心，这不仅仅是合规问题，还是泄密问题。

5. 常见问题与排查技巧实录

5.1 MCP Server 无法启动或工具不出现

这是最容易踩的坑。症状是 Claude Code 里看不到 memory-hub 工具，或者 Cursor 的 MCP 面板显示失败。排查顺序我总结成了表格：

遇到 MCP 相关问题时，先在命令行里手动跑一次配置里的启动命令，确认能正常启动再去找工具配置的锅。

5.2 上下文过长导致模型“假性遗忘”

有时候模型明明读到了记忆，但回答时还是像没看一样。这大概率是上下文太拥挤，模型注意力被稀释了。我建议把 MEMORY.md 控制在 100 行内，单文件架构文档也控制在 200 行内。如果决策类文件超过 200 行，就拆成多个主题文件，用索引串联。

另外，在 Claude Code 的规则里可以明确加一句：

当读取 memory 文件后，先确认自己是否理解其中关键结论；如果后续回答偏离记忆中的结论，需要主动指出。

这句话对减少“假性遗忘”挺有效，相当于逼模型先把记忆结论说出来再干活。

5.3 Cursor 规则不生效

Cursor 的.cursor/rules/文件不是改了立刻生效的。我踩过的坑包括：文件名带_导致匹配不到、glob 路径写错、没有重启后加载。排查时可以打开 Cursor 设置里的 Rules 面板，看看当前文件是否被选中。如果规则依赖 MCP，记得在 Agent 模式下使用，普通聊天模式不会主动调工具。

还有一个容易忽略的点：Cursor 的项目级规则默认只在打开项目根目录时生效。如果你通过软链接打开子目录，规则就失效了。解决办法是统一从项目根目录启动 Cursor。

5.4 不同工具对同一问题给出相反建议

这是很正常的，Claude 和 Codex 在模型训练、对齐方式上有差异，就算给了同样记忆，也可能给出不同建议。以前我只能手动把两边结论搬来搬去，现在我在记忆里多写了一条“决策记录模板”，包含“为什么选这个方案”、“和哪个备选方案比较过”、“哪些约束条件不可妥协”。

这样即便新工具想推翻旧决策，它也必须先阅读背景，再判断哪些约束条件已经变化。如果约束变了，那确实应该做新决策；如果没变，就让它尊重现有决策。把这套逻辑写进记忆后，两边“打架”的概率明显下降。

5.5 回写质量不稳定

AI 回写的最大问题不是少写，而是“乱写”。有时候它会根据一个很模糊的结果，就生成一份看似严谨、实际是空话的文档。我的过滤办法是三重检查：第一，看 diff，只保留真正有信息增量的改动；第二，要求回写内容必须包含“前置背景”和“可验证结论”，没有这两项的直接打回；第三，定期整理，把零散决策文件合并成架构文档时，必须有人参与。

6. 实操心得与后续扩展方向

这套本地优先的协作中枢，我实际用了一个多月，最直接的感受是“切换工具的成本”变低了。以前从 Claude Code 切到 Cursor，我总要花几分钟重新交代项目背景；现在打开 Cursor 应用规则，它自己就会去 memory-hub 里捞信息。Claude Code、Codex、Cursor 三个工具至少能共享同一套“项目事实和决策”，剩下模型理解风格上的差异，已经小到可以接受。

再分享一个小技巧：在每一个工具的规则文件里，都写上同一句话——“当你要修改核心代码之前，先去 memory-hub 看一眼相关决策记录”。这句话看起来简单，但对三个工具都有效。它让推理过程先对齐记忆，再落代码，比事后解释省得多。

后续我打算往两个方向扩展。一是把 sessions/ 里记录下来的高频问题自动摘要成“阻坑笔记”，定期更新进 runbooks；二是给 memory-hub 加一个简单的 Web 页面，让不习惯用命令行的同事也能直接浏览和编辑记忆。目前这套方案的代码我已经放在内部仓库里，主要组件都是开源依赖：FastMCP、SQLite、Markdown 解析器。如果你也想给团队搭一个，照着第二节和第三节的结构起个新仓库，半天就能跑通。

我最后想说的是，AI 编码工具的记忆能力会越来越强，但无论工具怎么变，“把项目事实和决策沉淀下来”这件事永远值得做。本地优先的开源实现，是目前最透明、最可控、也不怕工具厂商锁定的做法。