1. 从“换个工具就失忆”说起Agent 记忆到底卡在哪用 Claude Code 写了一个礼拜的项目换到 Codex 上继续结果它对你之前定的命名规范、目录结构、踩过的坑一无所知一切从头解释——这个场景我相信只要同时用过两个以上编码 Agent 的人都遇到过。标题里说的“Agent 的记忆终于不跟着工具搬家了”讲的正是这件事把记忆从某个具体工具里抽出来变成独立于工具之外的一层让 Claude Code、Codex 甚至以后换的任何 Agent 都能读到同一份上下文。先说清楚这篇东西适合谁看。如果你只是偶尔用一次 AI 补全代码那记忆这件事对你意义不大但如果你已经把 Agent 当成日常开发的一部分每天要跟它交代项目背景、技术选型、代码风格、历史决策那你一定体会过“重复交代”的痛。这篇内容就是围绕这个痛点展开的我会把记忆分层的思路、落地方式、具体配置、踩过的坑都讲一遍尽量做到你看完能自己搭一套。核心问题其实就一句话Agent 的记忆目前是绑在工具上的而不是绑在项目上的。Claude Code 有它的 CLAUDE.md 和记忆技能Codex 有它自己的上下文机制两者互不相通。你在 A 工具里积累的偏好、约定、历史决策到了 B 工具里全部归零。这不是模型能力问题是工程架构问题——记忆的存储层和使用层没有解耦。我自己的做法是把记忆拆成三层短期记忆当前会话的上下文、长期记忆跨会话的项目知识、永久记忆几乎不变的个人偏好和规范。短期记忆交给工具自己管长期和永久记忆抽出来用文件系统加一套约定来承载任何工具只要能读文件就能用。下面我会把这套思路拆开讲透。2. 记忆分层的设计思路为什么不能只靠工具自带的记忆2.1 工具自带记忆的三个硬伤先说为什么不能直接用工具自带的记忆功能。我实测下来Claude Code 的记忆技能和 Codex 的上下文机制各有各的问题归纳起来是三个硬伤。第一个是格式不互通。Claude Code 习惯读 CLAUDE.mdCodex 更依赖会话内的上下文和它自己的配置约定两者的组织方式、触发时机、加载优先级都不一样。你没法指望把一份 CLAUDE.md 直接丢给 Codex 就能用。第二个是生命周期不可控。工具自带的记忆什么时候写入、什么时候淘汰、保留多久基本是黑盒。我遇到过 Claude Code 把某次临时调试的结论记下来结果后面几次会话都被这个错误结论带偏的情况。你想手动清理还得去翻它的存储位置。第三个是迁移成本高。一旦你决定换工具或者团队里有人用 A 有人用 B记忆就没法共享。标题里“不跟着工具搬家”说的就是这个——记忆应该跟着项目走而不是跟着工具走。2.2 三层记忆模型的划分依据我采用的划分方式是短期、长期、永久三层这个划分不是拍脑袋来的而是对应了信息变化的频率。短期记忆是当前会话内的上下文变化最快一次对话结束基本就没用了。这部分交给工具自己管最合适因为它的读写频率极高抽出来反而增加开销。长期记忆是跨会话的项目知识比如这个项目的目录结构、核心模块职责、技术选型理由、已知的坑。它的变化频率是“天”级别一个项目周期内会不断增补但不会每次会话都变。永久记忆是几乎不变的个人或团队规范比如代码风格偏好、提交信息格式、命名约定、常用命令。这部分变化频率是“月”甚至“年”级别一旦定下来基本不动。划分清楚之后存储策略就自然出来了短期记忆不落盘长期记忆按项目落盘永久记忆按人落盘。工具只负责读不负责写写入由你自己控制。2.3 为什么选择文件系统而不是数据库有人会问为什么不搞个数据库或者向量库来存记忆。我的答案是在个人和小团队场景下文件系统的性价比碾压数据库。第一文件系统零依赖。你不需要起服务、不需要装驱动、不需要维护连接。一个目录加几个 Markdown 文件就能跑起来任何工具都能读。第二可读可编辑。记忆出问题的时候你直接打开文件看一眼就知道哪里错了改一行就行。数据库你还得写查询、改记录调试成本高一个量级。第三天然支持版本控制。把记忆目录纳入 Git你就有了完整的变更历史谁什么时候改了哪条记忆一目了然。数据库要做这个还得额外搭一套。第四迁移成本几乎为零。换机器、换工具、分享给同事拷贝目录就行。这也是标题里“不跟着工具搬家”能成立的技术前提。当然文件系统也有它的边界。当记忆条目超过几千条、需要语义检索的时候文件系统就不够用了那时候再上向量库也不迟。但在那之前别过度设计。3. 记忆目录的落地结构一份可直接抄的目录规范3.1 目录层级与文件命名约定我用的目录结构是这样的你可以直接照着建.agent-memory/ ├── global/ │ ├── preferences.md │ ├── code-style.md │ └── commands.md ├── projects/ │ └── my-project/ │ ├── overview.md │ ├── architecture.md │ ├── decisions.md │ └── pitfalls.md └── sessions/ └── 2025-01-15-debug-auth.mdglobal/放永久记忆跟人走不跟项目走。projects/放长期记忆按项目分目录。sessions/放短期记忆的归档可选主要用于事后回溯。文件命名我坚持用语义化英文加连字符不用中文不用下划线。原因是不同工具对文件名的处理策略不一样英文加连字符的兼容性最好不会出现编码问题。这一点看着小但踩过坑就知道中文文件名在某些终端环境下会出乱子。3.2 每类记忆文件该写什么preferences.md写个人偏好比如“回答用中文”“解释代码时先给结论再给理由”“不要主动重构我没让你动的代码”。这些是跨项目通用的。code-style.md写代码风格比如缩进用几个空格、函数命名用驼峰还是下划线、注释语言、导入顺序。这部分最好直接抄你项目里 linter 的配置保持一致。commands.md写常用命令比如怎么起本地服务、怎么跑测试、怎么构建。这个文件的价值在于Agent 不用每次问你“测试怎么跑”直接读就行。overview.md写项目一句话简介加核心目标控制在 200 字以内。太长了 Agent 读起来费劲也容易抓不住重点。architecture.md写模块划分和依赖关系。我习惯用纯文本画一个简单的层级图不用 Mermaid因为不是所有工具都能渲染。decisions.md写历史决策格式是“日期 决策 理由”。比如“2025-01-10 选 SQLite 不选 Postgres因为单机部署数据量小”。这个文件是长期记忆里最有价值的因为它记录了“为什么”而“为什么”恰恰是 Agent 最容易搞错的地方。pitfalls.md写已知的坑比如“这个模块的时区处理有历史遗留问题改之前先看 issue #123”。这个文件能帮 Agent 避开你踩过的雷。3.3 怎么让不同工具都读到这份记忆这是关键一步。不同工具的加载机制不一样我的做法是在每个工具的原生配置里加一段引用指向统一的记忆目录。Claude Code 这边我在项目根目录的 CLAUDE.md 里写一段## 项目记忆 本项目使用统一记忆目录位于 .agent-memory/。 每次会话开始前请先读取以下文件 - .agent-memory/global/preferences.md - .agent-memory/global/code-style.md - .agent-memory/projects/my-project/overview.md - .agent-memory/projects/my-project/architecture.md - .agent-memory/projects/my-project/decisions.md - .agent-memory/projects/my-project/pitfalls.mdCodex 这边如果它支持类似的配置文件就写同样的引用如果不支持自动加载就在会话开始时手动把内容贴进去或者用脚本把记忆内容拼成一段前缀。提示不要指望工具自动发现记忆目录。显式引用比隐式约定可靠得多尤其是工具版本更新之后隐式约定最容易失效。这里有个细节值得说引用路径用相对路径不要用绝对路径。绝对路径换机器就废了相对路径跟着项目走天然可迁移。4. 实操从零搭一套跨工具记忆系统4.1 初始化目录与模板文件第一步在项目根目录建目录mkdir -p .agent-memory/global mkdir -p .agent-memory/projects/my-project mkdir -p .agent-memory/sessions然后把模板文件建起来。我习惯用一个脚本一次性生成省得每次手敲cat .agent-memory/global/preferences.md EOF # 个人偏好 - 回答语言中文 - 解释风格先结论后理由 - 代码改动不主动重构未要求的代码 EOF cat .agent-memory/projects/my-project/overview.md EOF # 项目简介 一句话描述 核心目标 当前阶段 EOF模板文件建好之后先填一遍。别嫌麻烦这一步填得越细后面 Agent 越省心。4.2 把记忆目录纳入版本控制第二步把.agent-memory/加进 Git。这里有个取舍global/里的个人偏好要不要提交我的做法是分两个仓库管理。global/放在一个独立的私有仓库里通过软链接或者子模块挂到各个项目下projects/跟着项目仓库走团队共享。如果你嫌子模块麻烦也可以简单点global/不提交每个开发者本地维护自己的projects/提交团队共享项目级记忆。这样至少保证了项目知识的共享个人偏好各管各的。注意记忆文件里不要写敏感信息比如密钥、内部地址、个人信息。这些一旦提交到 Git 就很难彻底清除。4.3 会话开始时的记忆加载流程第三步把加载流程固定下来。我的习惯是每次开新会话先做三件事确认当前项目路径定位到对应的projects/子目录读取global/下的偏好和风格文件读取当前项目的overview、architecture、decisions、pitfalls如果工具支持自动加载就把这段写进配置如果不支持就手动执行。我写了个简单的 shell 函数来拼前缀load_memory() { local project$1 cat .agent-memory/global/preferences.md cat .agent-memory/global/code-style.md cat .agent-memory/projects/$project/overview.md cat .agent-memory/projects/$project/architecture.md cat .agent-memory/projects/$project/decisions.md cat .agent-memory/projects/$project/pitfalls.md }用的时候load_memory my-project输出直接贴给 Agent 就行。这个函数看着简陋但实测下来比任何花哨的方案都稳。4.4 会话结束时的记忆回写第四步会话结束时把新产生的长期记忆回写。这一步最容易被忽略但恰恰是记忆系统能不能滚起来的关键。我的做法是每次会话结束前问自己三个问题这次有没有产生新的项目决策有就写进decisions.md这次有没有踩到新的坑有就写进pitfalls.md这次有没有发现架构描述不准的地方有就更新architecture.md回写的时候注意只写结论和理由不写过程。比如“试了三种方案最后选了 A”这种过程不用写直接写“选 A理由是 X”。过程留在会话记录里长期记忆只留精华。5. 常见问题与排查技巧实录5.1 记忆加载了但 Agent 不遵守这是最常见的问题。你明明把偏好文件贴进去了Agent 还是按它自己的习惯来。原因通常有三个。一是记忆内容太长被截断或稀释。Agent 的上下文窗口有限你贴了几千字它可能只记住了开头。解决办法是精简每个文件控制在 500 字以内只留最关键的。二是指令不够明确。你写“尽量用中文”Agent 可能理解成“可以用中文也可以不用”。改成“所有回答必须用中文”明确程度立刻不一样。三是优先级冲突。工具自带的系统提示优先级可能高于你贴的内容。这种情况下把关键约束放在会话最开头或者用更强的措辞。5.2 记忆文件越写越乱怎么办用久了记忆文件一定会膨胀这是必然的。我的处理方式是定期归档。每个月花十分钟过一遍decisions.md和pitfalls.md把已经过时的条目移到sessions/归档目录或者直接删掉。判断标准很简单这条记忆对未来的会话还有指导意义吗没有就删。architecture.md和overview.md要保证和当前代码一致。我习惯在每次大重构之后更新这两个文件不然它们会变成误导 Agent 的源头。5.3 多工具同时用记忆冲突如果你同时用 Claude Code 和 Codex可能会出现两边对同一件事的理解不一致。根源是记忆回写的时候只更新了一边。我的解决办法是记忆目录单一来源。所有工具都读同一份文件回写也只写这一份。工具自己的原生记忆功能尽量关掉或者不用避免两套记忆打架。如果某个工具强制要求用它自己的记忆格式那就把它当成一个“视图”定期从统一目录同步过去而不是反过来。5.4 常见问题速查表问题现象可能原因排查方向Agent 不遵守偏好内容太长或指令模糊精简文件改明确措辞记忆加载失败路径错误或文件不存在检查相对路径和文件权限记忆内容过时未定期维护建立月度归档习惯多工具理解不一致记忆来源不统一统一到单一目录回写内容太啰嗦写了过程没写结论只留结论和理由5.5 几个我踩过的坑第一个坑是用中文文件名。有次我把文件命名成项目简介.md结果在某个终端环境下读取失败排查了半天才发现是编码问题。从那以后所有记忆文件一律用英文命名。第二个坑是把记忆目录放在项目外面。一开始我觉得放外面更“通用”结果换项目的时候经常忘记切换导致 Agent 读到别的项目的记忆。后来改成放在项目根目录下跟着项目走问题就没了。第三个坑是过度依赖自动加载。有段时间我完全依赖工具的自动加载结果工具更新之后加载机制变了记忆静默失效我还以为是模型变笨了。后来改成手动加载加自动加载双保险才稳定下来。6. 记忆系统的扩展方向与个人体会这套东西跑顺之后可以往几个方向扩展。一个是加一层检索当记忆条目多到几百条的时候用简单的关键词匹配先筛一遍只把相关的贴给 Agent减少上下文占用。另一个是加一层校验定期让 Agent 自己检查记忆文件和代码是否一致不一致的地方标出来人工确认。还有一个方向是团队共享。把projects/目录做成团队共享的记忆库每个人往里贡献自己踩的坑和做的决策新加入的人直接读这份记忆就能快速上手。这个价值比个人用大得多但前提是得有维护机制不然很快就会变成垃圾场。我自己的体会是记忆系统的核心不在于技术多复杂而在于坚持维护。工具会换模型会升级但一份维护良好的项目记忆是能一直用下去的。标题说“不跟着工具搬家”本质上说的就是这件事——把记忆的所有权拿回到自己手里工具只是读取者不是拥有者。最后分享一个小技巧每次开新项目的时候先花二十分钟把overview、architecture、decisions三个文件填个初稿哪怕内容很粗糙。这二十分钟的投入在后续几十次会话里会以“不用重复解释”的形式加倍还回来。