多代理协作的共享记忆实践：用Atlas打通Claude Code与Codex

老实说我一开始对“多代理协作”这个词是有点意见的。大多数人的用法无非是开好几个终端一个跑 Claude Code一个跑 Codex谁有空谁上。问题是这俩AI都只认自己那点会话上下文你让Claude Code分析了半天架构换到Codex那边继续写代码它根本不知道前面聊过什么甚至会基于一个完全相反的假设给你重构代码。这种“换一个AI就等于换一个脑子”的体验在有共享记忆之前其实是常态。后来我在一个实际项目上试用了 Atlas 这个记忆同步层让 Claude Code 和 Codex 共用一套项目记忆整个协作体验才算理顺了。这不是什么花哨的调度框架本质就是给多个AI代理建一个“共享大脑”记录谁做过什么、为什么这么做、下一步要做什么。这篇文章我就把整个落地过程、踩过的坑、以及我总结的配置思路完整写出来。不管你是刚接触这两个工具的新手还是已经被上下文断裂折磨了一两个月的老手应该都能从这里找到能直接抄作业的内容。1. 为什么多代理协作需要共享记忆1.1 一个代理的记忆是怎么丢的先说一个最容易被忽略的事实大模型本身是没有记忆的。你看到的“我记得你之前说过”其实是客户端或封装层在每次请求时把历史对话重新塞进上下文窗口。Claude Code 和 Codex 这种终端AI工具表面上看起来是会话式的底层仍然是“无状态请求 上下文拼装”。这带来两个问题。第一个问题是上下文窗口有上限聊长了旧内容会被截断或压缩代理会慢慢忘掉最初的技术约束第二个问题是每个代理的上下文是独立的Claude Code 记下的东西不会自动同步给 Codex。你可能在 Claude Code 里确认了“结算模块用数据库事务保证一致性”转头在 Codex 里问同一个问题时它完全不知道这条决策还会给出一个和事务方式冲突的乐观锁方案。我见过不少团队试图用文档来解决这个问题比如写 CLAUDE.md、AGENTS.md或者维护一份需求说明。这些静态文档的问题在于它们只在创建时有效一旦进入实现阶段代理的决策、修改、回退、变更理由这些动态信息没人会手动同步到文档里。你花十分钟写一段说明AI写代码一小时产生的临时决策远比你的静态文档多。1.2 共享记忆不是“高级功能”而是协作底座有人可能会说那我不用多代理就用一个工具不行吗可以但你等于放弃了不同模型在不同任务上的优势。Claude Code 在长文档分析和架构设计上表现更稳Codex 在某些代码生成和批量重构场景下响应更快。多代理协作的本质是让不同工具做各自擅长的事。问题是一旦代理数量超过一个最缺的不是工具而是信息同步。举个现实中的例子三个工程师一块写代码如果没有交接文档没有缺陷记录没有共享的决策日志最后一定会出现一个人改A模块、另一个人改依赖A的B模块、两个人同时改了同一个函数名的局面。AI代理也是一样而且它比人类更糟糕——人类工程师至少还会互相说一句话两个终端里的AI基本是零沟通。共享记忆层要解决的就是这种“零沟通”问题。它至少要做到三件事跨会话记忆同一个代理下次启动时能回忆起之前做过的关键决定跨代理同步不同代理读取同一份项目记忆保证理解一致状态可追溯每条记忆都记录时间、来源代理、状态避免出现互相矛盾的信息。所以共享记忆不是锦上添花而是多代理协作能不能真正跑起来的前提。没有这一层所谓多代理协作只是“多个AI各自单干”跟协作没有关系。2. 先认识 Atlas定位、架构与核心概念2.1 Atlas 到底是什么Atlas 在我使用的版本里定位是一个本地优先的 AI 代理记忆服务。它既不是聊天客户端也不是大模型网关而是独立运行的一个小型后台服务负责收集、存储和检索来自不同 AI 代理的记忆数据。你可以把 Atlas 想象成一个团队的海马体。Claude Code 和 Codex 是负责干活的两只手Atlas 是负责记事的脑区。每次代理做出一个值得记住的决定它就把这件事写进 Atlas每次代理开始新任务时Atlas 会把相关的历史记忆重新注入到这个代理的上下文里。这种方式和传统“把所有对话历史都粘进上下文”最大的不同在于Atlas 不是按会话顺序存储而是按“实体”和“主题”组织记忆。比如它会区分“用户偏好”“模块决策”“接口定义”“Bug追踪”这几类记忆检索时只返回与当前任务相关的部分。这样既避免了上下文被无关历史塞满也提高了跨代理的信息命中率。2.2 核心概念Workspace、Entity 与 Memory Entry我刚开始用 Atlas 时被它几个术语绕了一下。搞清楚了就很直观这里用表格梳理核心概念作用示例Workspace项目级记忆库一个项目通常一个shopping-cart / billing-serviceEntity记忆关联的对象比如文件、模块、用户checkout.py / OrderService / adminMemory Entry一条具体记忆由标题、内容、标签、来源组成“订单超时取消使用定时任务”Provider接入的记忆来源Claude Code 或 Codex 各算一个claude-code / codexDecision带状态的记忆可标记 proposed、accepted、revoked“缓存更新策略选择 Cache-Aside”需要特别说明的是 Decision 这种状态。普通记忆只是信息Decision 是影响后续行为的约束。只有被标记成 accepted 的 Decision才会在代理启动时作为强制上下文注入。这个设计非常关键否则不同代理很容易从互相矛盾的记忆里各取所需。2.3 和 Claude Code / Codex 的对接方式Atlas 和这两个工具对接不是靠直接改它们的二进制而是通过三个层面第一层是插件或 Hook。Claude Code 支持 PreToolUse、PostToolUse 之类的 HookAtlas 可以注册这些 Hook在每次工具调用前后自动记录上下文。Codex 则更依赖启动指令AGENTS.md和自定义命令Atlas 提供一个 CLI比如atlas recall和atlas memorize供代理在会话中调用。第二层是文件同步。Atlas 会把记忆以 Markdown 或 JSON 文件形式同步到项目目录下的.atlas文件夹。这样即使不用插件代理也能通过读取这些文件感知记忆。这个方式适合不喜欢装插件的用户。第三层是 API 服务。Atlas 默认在本地启动一个 HTTP 服务端口通常是 8231 或类似值。Claude Code 可以通过一个自定义工具调用这个 APICodex 也可以通过它的 function calling 机制调用。如果你用的是旧版本直接命令行调用即可。我实际测试下来因为 Atlas 是本地服务单次记忆检索的延迟基本在几十毫秒不会明显影响对话速度。3. 完整落地配置 Atlas 并与两个代理打通3.1 环境准备与安装在动手之前先确认机器上有 Node.js 18 或更高版本以及 Python 3.10 或更高版本。两个AI工具本身都是 Node CLIAtlas 我装的是带 Python 后端的版本所以两个运行时都要有。先装 Claude Code 和 Codexnpm install -g anthropic-ai/claude-code npm install -g openai/codex然后验证安装claude --version codex --version如果你之前已经装过这两个工具建议升级到最新版本因为 Atlas 的插件机制依赖版本比较新的 Hook 接口。我的环境里 claude code 用的是 1.x 版本codex 用的是 0.2x 版本功能上都正常。接着安装 Atlasnpm install -g atlas-ai/memory atlas --version安装完成后先用atlas init初始化当前项目的记忆库cd your-project atlas init --workspace ecommerce-checkout这个命令会在项目根目录生成一个.atlas文件夹里面包含memories/、decisions/、config.json三个核心部分。memories用于存碎片信息decisions用于存带状态的决策项config.json记录当前工作区配置和API端口。3.2 初始化共享配置Atlas 安装好以后先做全局配置。我建议在用户目录下建一个配置文件避免每个项目重复写atlas config set --key port --value 8231 atlas config set --key storageMode --value local atlas config set --key debug --value truestorageMode local意味着记忆只保存在本机。如果你的团队需要多人共享可以考虑把它改成git模式也就是记忆文件提交到 Git 仓库里大家通过分支合并。但我个人建议先本地跑通再上团队模式。然后启动 Atlas 服务atlas serve看到类似Atlas memory service listening on 127.0.0.1:8231的输出就算成功了。记住这个服务必须保持运行Claude Code 和 Codex 读写记忆时连不上服务会直接走 fallback也就是不记录任何记忆你的协作链条就断了。3.3 让 Claude Code 读写 Atlas 记忆接入 Claude Code我采用的是 Hook 方式。Claude Code 的配置文件在项目根目录的.claude/settings.json如果没有就手动创建{ hooks: { PreToolUse: [ { command: atlas recall --scope current --format markdown } ], PostToolUse: [ { command: atlas memorize --source claude-code --entry \$CLAUDE_TOOL_RESULT\ } ] } }这里有个关键点Hook 的上下文环境变量因版本而异。我的实测环境里$CLAUDE_TOOL_RESULT能取到工具执行结果但有些版本里变量名是$TOOL_RESULT。更稳妥的做法是让 Atlas 的 CLI 自己从日志目录读取最新记录比如{ command: atlas memorize --source claude-code --file .atlas/last-tool-result.json }这个方案不需要依赖不确定的环境变量。你把 Claude Code 的工具结果重定向到一个文件里Atlas 负责读取并结构化存储。除了 Hook我还在 CLAUDE.md 里加了一段规则每次开始新任务前运行atlas recall --scope current --format markdown将输出作为背景信息。所有涉及架构的确认使用atlas decision --status accepted记录。这样即使没有 Hook 触发Claude Code 也会主动去检索记忆。3.4 让 Codex 读写 Atlas 记忆Codex 的接入方式略有不同。Codex 的上下文启动文件是AGENTS.md它支持在文件里写“指令”来驱动工具调用。如果 Atlas 提供了codex-mcp插件可以用 MCP 方式接入atlas add-provider codex --type mcp --port 8231 codex mcp add atlas --command atlas-mcp-server如果你用的是普通 CLI 模式就在AGENTS.md里加入这样的指令## 记忆协作 - 每次开始编码前执行 atlas recall --source all --scope current - 实现过程中遇到关键决策执行 atlas memorize --source codex --content 决策描述 - 需要确认历史决策时执行 atlas decisions --status acceptedCodex 比 Claude Code 更依赖明确的指令。如果 AGENTS.md 里的命令不够具体它很容易跳过记忆调用。所以我建议在项目根目录创建.atlas-rules.md把上面三条规则写成必做项然后在 AGENTS.md 里引用它。3.5 完整协作流程示例配置完成后我实测了一个电商结算模块的开发和 review 流程。整个过程是这样的阶段使用的代理关键动作Atlas 的作用1. 需求分析Claude Code生成接口设计和数据库表结构草案记录设计决策标记 accepted2. 订单模块实现Codex实现订单创建的复杂逻辑召回 Claude Code 的接口设计避免字段冲突3. 支付状态异常处理Claude Code检查并修正状态机逻辑读取 Codex 新写的异常处理记录4. 最终 reviewClaude Code合并检查查看两个代理各自的决策识别冲突实际运行时Claude Code 在阶段1写出了设计文档我执行atlas decision --id order-service-db --status accepted把它固化。阶段2 切到 Codex 时它通过 AGENTS.md 里的指令自动执行了atlas recall一次性拿到了阶段1的全部关键决策包括订单状态字段命名和数据库索引方案。它没有重新问我“订单状态应该用什么值”直接照着设计实现。这个体验非常明显如果是在没有 Atlas 之前Codex 大概率会给出一个自己的命名规范然后阶段3 的 Claude Code 又会觉得这个命名不对两边改来改去。有了共享记忆这个问题直接从源头消失了。4. 踩坑实录多代理共享记忆的常见问题与排查技巧4.1 Codex 的 endpoint 报错怎么处理使用过程中最常见的报错是这个类型cc switch local proxy failed while handling codex endpoint /responses. provider...第一次遇到时我还以为 Atlas 装错了后来排查发现问题出在 Codex 的自定义 API Endpoint 和 Atlas 的请求路由冲突。Codex 允许你把请求转发到一个自建的 API 网关但 Atlas 的同步插件也尝试请求同一个 endpoint而这个 endpoint 并不支持插件发来的鉴权头于是请求失败。解决思路分三步先确认 Codex 的 endpoint 配置运行codex config show看看api_base_url是什么确认 Atlas 的 provider 配置里 baseURL 是否和它一致atlas provider list在 Atlas 插件里把请求路径改成/responses之外的健康检查端点或者给 Atlas 单独配置一个只读的 API Key。关键经验是不要让 Atlas 直接依赖 Codex 的对外配置。两者即使指向同一个网关也应该使用不同的 Bearer Token并给 Atlas 单独开一组最小权限。4.2 auth token is unavailable 的排查另一个高频问题是代理报auth token is unavailable通常发生在切换代理之后。原因也很直接Claude Code 用的是 Anthropic 的 API KeyCodex 用的是 OpenAI 的 API Key二者本身不该混。但 Atlas 在尝试读取“当前用户认证信息”时可能优先读取了系统环境变量里的OPENAI_API_KEY或者反过来。如果你用的是第三方兼容网关两台代理甚至可能共用同一个网关但网关要求不同的认证头。Atlas 的 provider 配置里有一个authEnvVar字段可以直接指定读取哪个环境变量。我在.atlas/config.json里这样设置{ providers: { claude-code: { authEnvVar: ANTHROPIC_API_KEY, baseURL: http://127.0.0.1:8231/v1 }, codex: { authEnvVar: OPENAI_API_KEY, baseURL: http://127.0.0.1:8231/v1 } } }这样每个 provider 各认各的 key互不干扰。如果你用的是自己的中转网关就把OPENAI_API_KEY替换成你网关认可的变量名例如OPENAI_BASE_URL对应的 key。4.3 上下文漂移记忆同步了但代理还在打架这是最隐蔽的坑。表面上看Claude Code 和 Codex 都能读取 Atlas 里的记忆了但生成的结果仍然不一致。我查了半天发现问题不是读取失败而是记忆库里有两条互相矛盾的记录一条说“订单号使用雪花算法生成”来源是 Codex状态为 accepted另一条说“订单号使用自增ID”来源是 Claude Code状态也是 accepted。两个代理各自读到了自己之前写的那条所以继续按照自己的想法干活。解决这个问题的核心是严格执行“状态机制”。记忆库里的每条 Decision 必须在一个时间点只有一个 accepted 状态。当 Claude Code 写下新决策时它会先用atlas decision --revoke order-id-rule撤掉旧的再写入新的 accepted 决策。我在 AGENTS.md 里加了一条规则所有决策写入前先执行atlas recall --type decision --entity order查看是否已有 accepted 决策如果有冲突必须先撤销再写入。这个流程虽然给代理多加了两个步骤但换来的是跨代理行为一致性非常值得。4.4 Token 开销失控的问题共享记忆不是越多越好。刚开始我把所有对话历史都塞进 Atlas结果每个代理启动时都要读取大量记忆Token 消耗直线上升响应速度也变慢了。后来我做了分类控制记忆类型是否注入上下文策略项目约定、命名规范是每次请求注入摘要架构决策是仅注入 accepted 状态全文临时推理过程否只存不读用于追溯代码片段按需通过具体实体检索在 Atlas 配置里每个 workspace 可以设置defaultRecallScope。我设为decisionrequirement也就是默认只召回决策和需求不召回所有聊天历史。如果需要讨论细节用atlas recall --entity checkout.py按文件检索。还有一个控制 Token 的办法是摘要压缩。Atlas 可以启动一个本地小模型通过 llama.cpp 之类把长记忆自动压缩成摘要但我个人实测摘要模式更适合做索引不适合做唯一知识源。压缩过程会丢掉细节比如具体的函数名和变量名建议摘要只用于检索排序最终注入时还是用原文。5. 我的实际体会与后续扩展用 Atlas 跑了一段时间多代理协作后我最深的体会是共享记忆最大的价值不是让 AI “记住一切”而是让 AI 知道“哪些信息是可信的、哪些是已经废弃的”。在人类团队里这叫“版本管理”和“决策记录”在 AI 代理团队里Atlas 承担的其实就是这个角色。如果后续要扩展我建议沿着两个方向做。第一是把记忆和自动化测试打通每次代理修改代码后把测试结果和修复记录也写回 Atlas形成“决策-实现-验证”的闭环。第二是做分层记忆将仓库级、团队级、个人级记忆分开避免不同项目之间互相污染。Atlas 的 workspace 已经支持这种隔离但真正用起来需要团队约定好规范这个比工具本身更花时间。最后再分享一个我从失败里总结出来的小技巧不要试图让 AI 代理自动决定“什么值得记”。刚开始我让代理自由发挥结果它把一大部分无关紧要的调试过程都写进了记忆库重要决策反而被淹没了。后来我在 Atlas 的规则文件里明确列出必须记录的内容类型比如“接口变更”“重构原因”“废弃代码块”“测试失败原因”只有在这些类型的指令触发时代理才会执行atlas memorize。这样一来记忆库才真正变得干净、可信、可依赖。