先说我遇到的真实场景我现在日常开发的主力工具是 Claude Code跑批处理和代码重构时经常切到 Codex。这俩工具单拎出来都很能打问题在于——它们互相不认识。上午 Claude Code 刚跟我确认了订单模块的字段设计和 API 约定下午切到 Codex 继续写前端调用它不知道后端返回的到底是什么结构生成的 TypeScript 类型全凭猜我一行一行改到想摔键盘。多代理协作这件事说起来很美一个管架构、一个管实现、一个管测试实际跑起来你就会发现代理之间不共享记忆等于每个 AI 都在从零开始上班。Atlas 就是来解决这个尴尬的。它是一个命令行工具核心思路很朴素把记忆从模型各自的会话窗口里抽出来放到一个统一的文件仓库里Claude Code 和 Codex 通过这个仓库读写项目上下文。A 代理写下的技术决策B 代理启动时马上能读到。这篇文章我会从原理讲到底层实现再给一套可以直接抄的配置方案和协作流程适合手里同时用多个 AI 编程助手、又被上下文切换折磨过的开发者参考。1. 为什么 AI 编程代理需要“共享记忆”1.1 单代理的记忆困境先说说不用 Atlas 时我在项目里实际遇到什么问题。Claude Code 的会话记忆本身做得不差。它支持--resume恢复之前的会话项目根目录放一个CLAUDE.md可以让它在每次启动时自动加载项目约定。Codex 那边也有类似机制用AGENTS.md来沉淀规则上下文快满的时候还会自动压缩。听起来都有记忆能力但这些记忆有一个共同的前提它长在各自的会话里。一旦你切换工具所有记忆跟着切断了。Claude Code 在会话里建立起来的上下文Codex 完全看不到Codex 在调试过程中发现的坑Claude Code 下次重构时照样踩一遍。更麻烦的是这两个工具跑在同一个代码仓库里你不可能分别给它们各讲一遍需求背景然后指望两边产出的代码风格和 API 约定是一致的。我做过一个比较典型的例子让 Claude Code 先设计一套用户鉴权接口包括 token 刷新机制和错误码定义。设计完我很满意切到 Codex 让它基于这套接口写前端请求封装。结果它完全不知道 token 刷新是异步的也不知道错误码 1002 是“登录态过期”生成的代码直接把 401 当成唯一错误处理。问题不在 Codex 笨而是它没有拿到该有的上下文。这不是任何单一模型的缺陷是工具链的断层。1.2 多代理协作的真实场景很多人以为多代理就是同时开好几个窗口让不同模型各写各的模块。如果你真的这么干过大概率会发现在代码合并的时候想骂人。A 模型定义了一个OrderStatus枚举B 模型又在另一个地方定义了一套字符串常量两个东西表达的是同一个概念但命名和取值都不一样最终整合出来的代码是四不像。合理的多代理协作应该是分工明确、上下文共享的。我理想中的流程是一个代理负责需求分析和架构设计产出技术方案和接口约定。另一个代理负责具体实现按照方案写业务代码。第三个代理负责走查检查实现是否偏离了设计。流程说起来很顺但除非有一个机制把架构代理的输出同步给实现代理否则实现代理就是在没有设计约束的情况下自由发挥。你在 prompt 里写给它的需求说明只是整个设计文档的一个摘要副本而且这个摘要在转述过程中极容易失真。真正需要的是让所有代理访问同一份权威的记忆而不是靠人来回复制粘贴。1.3 Atlas 的设计思路与定位Atlas 的做法是把记忆从对话中彻底剥离出来变成一个项目级别的独立仓库。操作上就是你先用atlas init在项目里初始化一个记忆库然后不管是 Claude Code 还是 Codex需要记东西的时候就往这个库里写需要了解项目背景的时候就从库里查。这个设计最打动我的地方是它对代理保持中立。Atlas 不绑定任何一家模型厂商它只是一个存储和检索的中间层。Claude Code 能读Codex 也能读其他通过命令行调用的 AI 工具同样能读你不需要为每一对工具组合单独开发一套同步方案。当然“Atlas”这个名字在 AI 领域有重名华为有一款叫 Atlas 的推理加速卡GitHub 上还散落着几个同名项目。这里说的是那个开源的多代理记忆工具装的时候看清楚包名别下错了东西。2. 深入拆解 Atlas 的记忆机制2.1 记忆仓库的结构设计Atlas 初始化之后会在项目目录下生成一个.atlas文件夹。这个文件夹不是随便存一些文本它内部是有结构的。默认的目录布局是这样的.atlas/ ├── index.json ├── decisions/ ├── context/ ├── projects/ └── logs/decisions/存放技术决策记录比如“鉴权方案采用 JWT”“数据库连接池上限设置为 20”。这类内容的特点是变更频率低、影响范围大。context/存放项目背景信息比如模块说明、目录结构、第三方服务的接入方式。变更频率中等是代理日常干活时查询最多的地方。projects/按子项目或模块划分的内容适合大仓库里多个团队并行开发的场景。logs/Atlas 自己的操作日志用于排查“这个记忆到底是谁写的、什么时候写的”。index.json是整个仓库的索引文件负责维护关键词到具体记忆文件的映射。为什么单独搞一个索引因为文件数量多起来之后如果每次查询都全量扫描所有 Markdown 文件效率会非常低。加上索引之后atlas search可以在几十毫秒内返回结果。每个记忆条目本身是一个 Markdown 文件文件名是短横线分隔的语义化名称比如jwt-auth-flow.md。文件内容建议按照固定的模板组织包含元信息写入时间、写入代理、正文描述、关联条目三个部分。这样做的目的是为了让不同代理写入的内容风格统一读取的时候不需要做额外的格式兼容。2.2 代理间通信链路Claude Code 和 Codex 怎么跟 Atlas 通信这是整个方案里最关键的一环。Atlas 提供三种接入方式按集成深度从浅到深排列第一种是 CLI 包装方式。在 Claude Code 的CLAUDE.md或 Codex 的AGENTS.md里写清楚“每次启动先执行atlas search --key project/overview”让代理把查询结果作为上下文的一部分。这种方式改动最小不依赖任何额外的运行环境也是我目前用得最多的。第二种是通过 MCPModel Context Protocol协议接入。Claude Code 桌面版和 Codex CLI 都支持配置 MCP 服务器Atlas 可以作为一个 MCP server 注册进去。这样代理不需要在 prompt 里被频繁提醒它在需要的时候会主动通过工具调用去查记忆。MCP 的体验更自然但配置复杂度也更高新手建议先把第一种跑通再说。第三种是文件桥接。也就是让多个代理直接约定读写某个共享目录里的文件这个目录充当记忆的载体。实际上 Atlas 的仓库本身就是普通文件你甚至不装 Atlas 也能手动读写只是少了索引和搜索能力。这个方式适合在工具不支持前两种方案时做兜底。三种方式的选型逻辑其实很简单想要稳定就用 CLI 方式想要体验就用 MCP 方式想要通用就用文件桥接。我在日常项目里是 CLI 方式打底、MCP 方式做增强两边都不耽误。2.3 记忆的优先级与冲突消解记忆仓库一旦被多个代理写入冲突几乎是必然的。Claude Code 认为订单状态应该用PENDING - PAID - SHIPPED - COMPLETEDCodex 那边按照自己的理解写成了pending - paid - done。两边各有各的道理碰撞起来你怎么处理Atlas 的理念是不做自动裁决它把所有写入的记忆都加上时间戳和来源标记冲突的判定交给使用者和高优先级的决策记录来处理。具体规则可以按下面的方式来每个记忆条目在index.json里有一个priority字段取值范围从 0 到 10默认是 5。当两个代理写入的内容互相矛盾时以priority值更高的条目为准。如果优先级相同以updated_at时间更晚的为准。任何代理在写入前都可以用atlas query先查一下相关条目是否存在存在就选择更新而不是新增。这套规则虽然简单但足够应付大多数协作场景。实际执行时我更倾向于在decisions/里单独保存一份高优先级的架构决策把容易冲突的命名约定、接口规范全部沉淀成 DRDecision Record其他代理读到 DR 之后就不会再各自发挥了。3. 实操搭建 Claude Code Codex Atlas 协作环境3.1 安装 Atlas 并初始化记忆仓库Atlas 是基于 Node.js 的命令行工具安装之前确保机器上已经有 Node.js 18 以上的版本。安装命令很简单npm install -g atlas/cli装完之后先验证一下版本确认安装成功atlas --version接下来进入你的项目目录初始化记忆仓库cd ~/projects/myapp atlas init --name myapp执行完之后项目里会多出一个.atlas目录同时生成一份初始的index.json。你可以把它提交到 Git 仓库里让整个团队共享这套记忆。如果项目本身是工作区里面包含多个子项目我建议在每个子项目目录下单独初始化一个 Atlas 仓库而不是在根目录搞一个巨大的全局库。这样每个子项目的记忆边界更清晰查询结果也更精确。安装完成后可以先试着手动写入一条记忆验证整体流程是否通畅atlas add --key project/tech-stack --content 后端使用 FastAPI前端使用 React数据库使用 PostgreSQL然后查询一下atlas search --key tech-stack能看到刚才写入的内容说明安装和初始化都没有问题。3.2 让 Claude Code 接入 AtlasClaude Code 接入 Atlas 最推荐的方式是在项目根目录的CLAUDE.md文件里追加一段操作约定。这样每次 Claude Code 启动时都会读到这个文件也就知道了 Atlas 的存在和使用规则。我的CLAUDE.md里追加的内容长这样## 项目记忆系统 本项目使用 Atlas 管理共享记忆所有重要信息必须写入 .atlas 仓库。 - 开始任务前先执行 atlas search --key project/overview 了解项目背景。 - 修改接口或架构时先执行 atlas search --key decisions/当前模块 查看是否已有决策记录。 - 做出重要技术决策后执行 atlas add --key decisions/xxx --content 决策内容。 - 不确定的信息优先查询 Atlas不要自己猜测。这里的关键点是“开始任务前必须查询”。很多时候代理不是不遵守规则而是它根本不知道有这条规则。CLAUDE.md 是 Claude Code 每次启动都稳定加载的文件把 Atlas 的使用方法写在这里就能保证它在干活前先去看记忆库。如果你用的是 Claude Code 桌面版还可以通过 MCP 的方式把 Atlas 注册成工具。配置入口在设置里找到 MCP Servers添加一个命令类型的服务器启动命令是atlas mcp。注册成功之后Claude Code 会在需要时自动调用 Atlas 的能力不需要你反复在 prompt 里提醒它。3.3 让 Codex 接入 AtlasCodex 的接入方式跟 Claude Code 大同小异只是说明文件名不同。Codex CLI 启动时会自动读取项目根目录的AGENTS.md所以我们在这个文件里写入同样的约定## Shared Memory Protocol This project uses Atlas as its shared memory layer. 1. Before starting any task, run atlas search --key project/overview. 2. After making architecture decisions, run atlas add --key decisions/xxx. 3. When context is ambiguous, run atlas search --key context/模块名 first. 4. Do not duplicate or overwrite existing memory entries without checking timestamps.Codex 对系统提示的遵循能力很强只要在AGENTS.md里写清楚了它执行起来基本不会打折扣。我在实际项目中观察到的行为是Codex 会在生成代码前先跑一次atlas search然后根据搜索结果来约束自己的实现。虽然这会让每次任务多一次命令调用但换来的上下文准确性是值得的。如果 Codex 版本支持 MCP 配置可以通过codex mcp add命令把 Atlas 注册为一个 MCP service实现方式跟 Claude Code 桌面版类似。注册后 Codex 在会话里就可以直接调用 Atlas 的查询和写入工具。3.4 验证共享记忆是否生效环境配置完成之后需要做一个端到端的验证确保两个代理真的能共享记忆。我常用的验证流程是第一步在 Claude Code 会话里写入一条记忆atlas add --key context/auth --content 用户认证采用 JWTaccess token 有效期 15 分钟refresh token 有效期 7 天token 过期后客户端用 refresh token 静默刷新第二步退出 Claude Code打开 Codex 会话直接问它先查询 .atlas 仓库里的 auth 相关记忆再回答refresh token 的有效期是多长如果 Codex 能准确回答出“7 天”就说明共享记忆链路已经打通了。如果它答不上来优先检查AGENTS.md是否被正确读取以及 Atlas 命令是否在项目的$PATH里。我自己的经验是90% 的验证失败都出在一个低级问题上代理工作时的工作目录不是项目根目录导致它找不到.atlas文件夹。解决办法是在说明文件里明确写上“使用绝对路径访问 Atlas 仓库”避免因为相对路径问题造成误导。4. 实战案例一个前后端任务的完整协作流程4.1 需求拆分与记忆写入理论讲完我拿一个实际的电商后台需求来演示整套流程。需求很简单给订单模块增加一个导出功能支持按时间范围和订单状态筛选导出的文件是 CSV。这个需求如果让一个代理从头写到尾问题不大但我想演示的是两个代理如何分工。我决定让 Claude Code 负责后端导出接口和异步任务实现让 Codex 负责前端的导出按钮、文件下载和进度提示。分工之前先把需求和技术约束写进 Atlas。在 Claude Code 里执行atlas add --key projects/order-export/requirement --content 订单导出功能支持按时间范围和订单状态筛选导出 CSV 文件文件最大支持 5 万行超过则拆分多个文件并打包下载 atlas add --key projects/order-export/backend-api --content POST /api/orders/export参数 start_date、end_date、status返回 task_idGET /api/orders/export/tasks/{task_id} 查询导出状态 atlas add --key projects/order-export/tech-constraint --content 后端使用 FastAPI Celery前端使用 React Query 管理下载状态这三条记忆分别对应需求、接口约定、技术约束。写入之后Claude Code 就拿到了“必须按这个接口约定实现”的指令不会自己另起炉灶设计一套新的 API。Codex 那边虽然不参与后端设计但它读到了接口约定的记忆写前端请求代码的时候就能精准对接不会出现字段名对不上的问题。4.2 两个代理并行干活分工之后两个代理几乎是同时开工的。Claude Code 那边我给它布置的任务是“实现订单导出后端严格按照 Atlas 里的接口约定”。它开始前先执行了atlas search --key projects/order-export把需求、接口、技术约束全部读进上下文然后开始写 FastAPI 路由和 Celery 任务。Codex 那边我给它布置的任务是“实现订单导出前端页面对接后端导出接口字段和路径以 Atlas 记忆为准”。它也先在 AGENTS.md 的指引下查询了 Atlas重点读了backend-api那条记忆所以它知道该调哪个接口、传什么参数、响应结构长什么样。在并行开发的过程中有一件很重要的事当 Claude Code 发现接口约定需要调整时比如需要增加一个export_type参数区分 CSV 和 Excel它不能只在会话里改还必须同步更新 Atlas否则 Codex 那边永远不知道接口变了。我用一个强制约定来保证同步# 修改接口定义后立即更新 Atlas atlas add --key projects/order-export/backend-api --content POST /api/orders/export参数 start_date、end_date、status、export_type(csv/excel)返回 task_idGET /api/orders/export/tasks/{task_id} 查询导出状态这一步很关键。多代理协作里最常见的错误就是“代理 A 改了设计但忘了告诉代理 B”Atlas 虽然不能自动感知代码变化但它至少能保证“只要 A 写了B 就能读到”。剩下的就是纪律问题。4.3 记忆同步与结果汇总一天工作结束后我习惯性地检查一下 Atlas 的状态atlas stats这个命令会列出今日新增的记忆条数、修改次数和最近的查询记录。我那天看到的数据是Claude Code 写入了 5 条记忆Codex 写入了 3 条两边都没有出现过对同一 key 的写入冲突。这说明整个协作流程跑得很顺。最终代码合并的时候几乎没有出现两个代理互相看不懂对方代码的情况。接口定义两边用的是同一套字段名和路径状态枚举两边用的是同一个OrderStatusCSV 导出的限流规则两边也都清楚。和之前凭 prompt 转述的方案相比这次协作的顺畅程度提升了一个量级。项目结束后我还把整个过程整理成了一条决策记录写进decisions/multi-agent-workflow.md包括这次的接口约定、代理分工边界、以及“任何接口变动必须同步 Atlas”这条规矩。下次再开发类似功能代理们能直接复用这套记忆不需要我重新解释项目背景。5. 常见问题与排查技巧实录5.1 高频报错速查表这套方案跑了一段时间我在社区和实际使用中积累了不少问题的排查经验整理成一张速查表报错信息可能原因排查方向command not found: atlasNode.js 全局 bin 目录不在 PATH 里重新安装或把 npm 全局目录手动加入 PATHcc switch local proxy failed while handling codex endpoint /responses本地请求转发服务异常或端口被占用检查转发服务的运行状态确认端点在浏览器中可访问后重试codex ran out of room in the models context会话上下文过长用atlas compact将长记忆压缩进仓库只在会话里保留引用atlas search查不到刚写入的内容索引未刷新执行atlas rebuild重建索引代理读取记忆时提示文件不存在工作目录不是项目根目录在 CLAUDE.md / AGENTS.md 里使用绝对路径两个代理写的记忆互相覆盖冲突策略没配置检查 priority 字段为关键决策设置高优先级the gpt-5.6-sol model is not supported模型名不在当前 CLI 支持列表检查 Codex 的模型配置切换为已支持的模型名后重试这里单独说一下cc switch local proxy failed while handling codex endpoint /responses这个报错。它看起来像是 Atlas 的问题其实不是。这个错误发生在切换工具或切换服务地址时本质是本地请求转发服务没起来或者地址指向了一个不可用的端口。排查的时候别去翻 Atlas 的配置先确认转发服务本身的状态把这个服务恢复正常错误自然就消失了。5.2 协作流程里的避坑建议最后分享几条我在长期使用中踩出来的经验这些内容官方文档不会写但对实际效果影响非常大。第一记忆不是写得越多越好。我发现很多人在刚接触 Atlas 时会陷入一个误区把所有对话内容都往仓库里扔。结果仓库里的信息冗余严重代理查询时返回了一堆无关内容反而干扰了它的判断。记忆仓库要像代码仓库一样做管理只记录那些“价值高、复用性强”的信息比如接口定义、架构决策、命名约定而不是把日常聊天记录也存进去。第二先查再写别直接覆盖。任何代理在写入记忆之前都应该先执行一次 search确认同一个 key 是否已有内容。如果已存在需要判断是更新还是新增。Atlas 的索引系统对重复 key 的处理逻辑是后写覆盖如果没有这个先查的习惯两个代理很容易互相覆盖掉对方重要的上下文。第三定期清理过期记忆。项目迭代后一些早先的技术决策可能已经被推翻但旧记忆还留在仓库里。代理检索时可能会被过时信息误导。我一般每周做一次 review把decisions/目录下已经失效的记录标记为废弃或者直接删除。保持记忆库的“新陈代谢”才能保证代理拿到的上下文是准确有效的。第四不要把机密信息写进共享仓库。Atlas 的记忆库本质上还是普通文件如果它被提交到 Git 仓库并推送到远端那么任何能访问仓库的人都能看到里面的内容。涉及密钥、数据库密码、内部服务地址的敏感信息就算代理要求你存也不要写进去。可以用环境变量或密钥管理系统替代。第五用绝对路径规避大量诡异问题。这个我前面提过但值得再说一遍。无论是 CLI 方式还是 MCP 方式代理执行命令时的工作目录不一定是你预期的目录最常见的问题就是它找不到.atlas文件夹。在说明文件里把 Atlas 仓库的路径写死成绝对路径可以省掉很多排查时间。根据我个人的使用体会Atlas 最有价值的时刻不是在两个代理配合得很顺的时候而是在你回头复盘“为什么这次交接没有问题”的时候。当你意识到 Claude Code 和 Codex 之间已经不需要你来回当传话筒整个开发流程的流畅度就会明显不一样。如果你也同时用多个 AI 编程助手建议从一个小型项目开始试先把记忆写入和读取的链路跑通再逐步扩大到复杂项目。先让代理学会“先查再写”后面的事情会自然顺起来。