最近圈子里聊得最热的就是 OpenAI 那个 Codex CLI——一句 “welcome to codex”直接把命令行编程Agent带进了主流视野。紧接着 Pi Coding Agent、Claude Code、Google Jules这些工具也跟着刷屏好像一夜之间不会用Coding Agent写代码就不好意思说自己在搞开发了。但真把Coding Agent用起来的人大概率都撞上过同一堵墙这玩意儿记性太差了。上午让它帮你搭好了项目的目录结构下午开个新会话它又问你“项目用什么技术栈”你明明在上一轮强调了“别用 any全部用 interface”换个会话它转头就给你写满 any。这种“每开一个窗口就失忆一次”的体验气得人分分钟想把它卸载重装。Coding Agent要真正成为团队里的一员而不是一个每次都要重新认识的临时外包**长期记忆就是那道绕不过去的坎。这篇文章我会从原理到实操把我自己整理的那套“给Agent装长期记忆”的方法完整拆给你看。顺带说一句国庆期间我拉了个人人都在问的限时招募一起系统折腾这件事文末会讲清楚适合谁来、能拿到什么。1. 为什么 Coding Agent 必须得有长期记忆1.1 先看看 Coding Agent 的“失忆症”到底有多严重很多人第一次用 Coding Agent都默认它“什么都知道且什么都记得”。这其实是对大模型工作方式的误解。Coding Agent 本质上是一个被封装成“程序员助手”的大语言模型它跟你对话时能看到的内容只有当前上下文窗口里塞进去的东西。这个窗口通常能装下几万到几十万的 token听起来很大但换个会话或者重启一次工具它就什么都不剩了。这就像你每天上班都换一个新工位搭档也天天换桌上没有任何历史资料每次干活前都要把所有背景重新说一遍。今天说“后端框架是 NestJS数据库用 PostgreSQL”明天换个会话问它“查询接口怎么写”它回你“假设我们用 Spring Boot 和 MySQL”开始胡说。这就是Coding Agent在真实项目里最让人抓狂的地方——它永远在用“第一次认识你的视角”跟你协作。更隐蔽的问题是模型对整个对话历史的依赖非常线性。哪怕在同一个会话里只要中间穿插了大量的报错信息和调试输出早期你说的“不要改 A 文件只改 B 文件”这种关键约束也会被上下文挤到边缘模型读到后面就“忘记”前面的指令了。这种失忆不是偶发而是结构性的必然。你可能会觉得那我每次给它一个详细的 prompt把所有要求写清楚不就行了能行但这相当于每次开会前都要把项目全部文档读一遍对话成本极高而且人总有写漏的时候。真正可持续的解决方案是把记忆从“对话内容”里抽离出来落到项目能持久保存的地方。1.2 失忆带来的连锁成本远比想象中高失忆的第一个成本是钱。现在好一点的 Coding Agent 基本都按 token 计费每次开新会话为了让 Agent 回忆起项目背景你得先喂它几千甚至上万字的项目说明。这些“重复的背景介绍”没有产生任何新的价值纯粹是白烧 token。一个稍微上规模的项目光是把背景反复解释给 Agent 听一个月可能多烧几十美元的 API 费用。第二个成本是决策漂移。开发中最怕的不是慢而是前后不一致。今天你让 Agent 用 pnpm 装依赖明天它给你建议 npm今天说错误处理统一用全局异常拦截器明天它又在一个新接口里写 try/catch。每一次失忆都可能让项目架构往不同方向偏一点最后整个代码库变成四不像。这种“精神分裂式”的代码风格后期维护成本足以让任何一个技术负责人头疼。第三个成本最隐性但最致命——信任崩塌。当 Agent 每次都要你重复背景、总把之前的约定忘光时你会下意识怀疑它输出的所有代码。本来用 Coding Agent 是为了把精力从“写代码”转移到“评审代码”结果变成了”盯场子”反而更累了。我见过太多人从“狂热使用”到“彻底弃用”根本原因都不是模型能力不行而是记忆能力跟不上。1.3 长期记忆到底该记什么不该记什么要给 Agent 装长期记忆首先要定义清楚“记忆”包含哪些信息。不是所有东西都值得记记忆是有容量的也有优先级。我把编码场景的长期记忆分成四层项目资产层技术栈、目录结构规范、构建命令、测试命令、依赖管理方式。这些是 Agent 干活前必须知道的东西属于“最低配置”。决策记录层为什么要抛弃 X 方案选 Y 方案为什么要用 monorepo为什么数据库加了一层 Redis 缓存。这类“背后的原因”Agent 不会直接从代码里看出来但恰恰是它做后续决策时最需要的。约定偏好层团队代码风格用单引号还是双引号缩进几个空格、命名习惯接口用IUserService还是UserService、TypeScript 里允不允许用any。这些你作为代码评审者最在意的点必须让 Agent 刻进 DNA。进度状态层当前正在做哪个功能做到了哪一步哪个文件改到一半下一步是什么。这个信息对跨会话续接最有用。但有三类信息我建议永远不要写进长期记忆一是临时性的调试细节比如某次报错的堆栈信息解决完就该丢二是过于底层的实现噪音比如某个函数的内部局部变量名问 Agent 的时候现查代码就行三是不断变化的运行时状态比如某次构建的耗时数据记了也很快就会过期。每类信息该放哪、怎么写、如何被 Agent 读取更新就是后面实操部分要展开的事。2. 给 Agent 装长期记忆的三种主流思路2.1 文件记忆最朴素但永远不过时长期记忆最直接的落地方式就是把它写进项目里的文件。现在各种 Coding Agent 都支持“项目级指令文件”比如 Claude Code 的CLAUDE.mdOpenAI Codex 的AGENTS.md还有很多 IDE 插件用的.cursorrules。这类文件会在每次 Agent 启动会话时被自动加载到上下文中相当于你给每个项目配了一份“入职手册”。文件记忆最大的优势是透明且可控。它就是一个普通文本文件你随时可以打开看、改、删也可以提交到 git 里做版本管理。哪次 Agent 表现不对劲打开文件检查问题几乎一眼就能定位——大概率是文件里写了错误的信息或者干脆没写。但它也有明显缺点所有内容都挤在一个文件里会越来越大。一个成熟的 Medium 规模项目如果把目录规范、技术决策、进度记录全写进CLAUDE.md这个文件很快就会膨胀到几万字远超 Agent 关注重点的能力范围。所以我在实际项目中很少只用单文件而是把文件记忆当作“入口文件”用它去引导 Agent 读取更多细分记忆文件——这就是所谓的记忆库方案。2.2 结构化记忆库把记忆分门别类按需读取结构化记忆库的思路是在项目根目录建一个专门的记忆目录比如memory/里面按维度拆分成多个文件每个文件只承担一种记忆职责然后在入口指令文件里约定好读取规则。一个我常用的记忆库目录长这样memory/ ├── 01-project-brief.md # 项目概览与当前目标 ├── 02-tech-stack.md # 技术栈与关键依赖说明 ├── 03-architecture.md # 架构设计与目录结构约定 ├── 04-coding-conventions.md # 代码风格与命名规范 ├── 05-adr.md # 架构决策记录ADR ├── 06-progress.md # 当前进度与下一步计划 └── README.md # 记忆库索引说明每个文件是干嘛的然后在AGENTS.md或CLAUDE.md里写一段比较强硬的指令每次会话开始时你必须先读取memory/README.md了解记忆库结构然后根据当前任务读取对应的记忆文件涉及架构实现必须读 03-architecture.md涉及写代码必须读 04-coding-conventions.md任务结束后如果进度有变化必须更新 06-progress.md。这套方案的精髓在于**“按需读取”**。不用把几万字的记忆全部塞进上下文Agent 只会加载跟当前任务相关的几个文件既节省 token又提高了记忆的命中率。我在自己项目里用这套方案跑了三个月最直观的感受就是Agent 对新会话的“适应期”几乎消失了开场就能进入干活状态。2.3 向量检索记忆让 Agent 拥有“模糊搜索”能力文件记忆和结构化记忆都有一个共同的瓶颈它们是静态的Agent 只能读你写好的内容。你忘了写进去的知识Agent 就不可能知道。而且历史对话里的很多临时结论“哦这个接口返回结构改成{ data, code, msg }了”事后没有同步到文件里就彻底丢了。向量检索记忆解决的是“动态知识沉淀”的问题。思路是把历史对话、文档片段、甚至代码注释切成小块用 Embedding 模型转成向量存进向量数据库每次 Agent 需要记忆时把当前任务描述也转成向量去库里做相似度检索把最相关的 Top-K 条记忆注入上下文。听起来高大上其实原理就是给 Agent 装了一个“项目专属的搜索引擎”。它不只记你主动告诉它的东西还能在历史信息里“翻找”。在技术选型上轻量级方案可以用sqlite-vec直接在本地文件里做向量检索零部署成本或者是 Python 社区常用的chromadb后端项目也可以考虑pgvector直接复用 PostgreSQL。这套方案也有一些麻烦。首先它需要额外搭建服务比纯文本文件复杂得多其次 Embedding 会引入额外延迟如果每轮对话都要做检索体验会打折扣最后向量检索的结果未必比你精心写的文件准它返回的是“相似”片段不是“正确”答案。所以这套方案更适合大项目比如多模块的大仓、或者历史对话特别多的老项目小项目用它就是杀鸡用牛刀。2.4 方案选型对比别纠结按项目大小选为了帮你少走弯路我把三种方案放在一张表里做了对比方案落地成本记忆上限检索能力透明度适合场景单文件记忆极低小几万字会膨胀几乎为零极高小项目、脚本仓库结构化记忆库低中可按维度拆分靠人工组织很高大多数业务项目向量检索记忆高很高理论无上限语义相似度检索一般大型项目、历史语料多我个人的建议是先用结构化记忆库它覆盖了八成以上的场景。等哪天你发现记忆文件已经多到无法有效索引再考虑引入向量检索。不要一上来就搞 Chroma Embedding很多项目折腾完根本用不上最后只留下一堆维护成本。3. 实操从零搭建一套长期记忆系统3.1 第一步在你的项目根目录创建记忆骨架先在项目根目录建一个memory/目录并在里面创建上面列出的六个核心文件。这一步不需要写太多内容先把骨架搭好。然后打开项目的主入口指令文件——如果你用的是 Codex那就是AGENTS.md如果是 Claude Code那就是CLAUDE.md如果两个都用建议在两个里都写同一段规则保持一致。我这里给出一个可以直接复制修改的AGENTS.md模板核心是记忆读写规则Memory Protocol本仓库存在memory/目录用于存放长期记忆。每次会话开始必须读取memory/README.md了解各文件用途。根据任务类型读取对应记忆文件涉及技术栈选择读02-tech-stack.md涉及架构与目录结构读03-architecture.md涉及代码书写读04-coding-conventions.md涉及方案取舍读05-adr.md会话期间如果产生了新的、长期有效的结论如选定某个库、变更某个约定必须同步更新到对应记忆文件。会话结束时必须更新06-progress.md记录当前进度与待办事项。这段规则写得“强硬”一点是有必要的。很多 Agent 默认不会主动去读额外文件如果你用“你可以看看”这种语气它大概率就不看了。直接用“必须”而且在每个子任务开始前重申规则才能保证记忆机制被真正执行。3.2 第二步填充关键记忆文件重点关注风格和决策骨架建好后最重要的一步是把记忆内容填进去。这一步千万不要偷懒因为后续 Agent 的所有输出质量都取决于你喂给它的记忆质量。先写01-project-brief.md控制在 200 字以内写清楚项目是干嘛的、当前核心目标是什么。比如“这是一个社区团购的后台管理系统当前目标是完成订单管理模块的开发。已完成商品模块正在进行订单列表接口联调。”再写04-coding-conventions.md这个文件在实践中最容易出效果。把你平时评审代码时总在说的那些话统统写进去TypeScript 必须开严格模式禁止使用any函数名用动词开头布尔变量用is/has/can开头所有 API 返回值统一包装成{ data, code, msg }样式优先用 Tailwind不要写原生 CSS。这类信息一旦进记忆Agent 写出来的代码立刻就有“团队味”而不是算法题味。05-adr.md是很多人会忽略但特别重要的一个文件。比如你之前决定不用 Redux 改用 Zustand理由是“代码量减少、样板代码少”把这个“为什么”写进去。Agent 后续看到 Zustand 时就不会一脸懵地问“这个项目怎么不用 Redux”它知道这是有意的决策而不是历史遗留。决策记录是 Agent 从“代码工人”进化到“协作伙伴”的关键一步。3.3 第三步让 Agent 养成“先读后写、事毕更新”的习惯记忆文件写好了需要 Agent 形成“读记忆 → 干活 → 更新记忆”的闭环。这一环节光靠AGENTS.md里的静态规则还不够因为规则再强Agent 也可能在执行一轮任务后就不“记得”这条规则了。我的经验是在会话进行中通过 prompt 主动强化。比如你让它写一个新页面开头就说“先读 memory/04-coding-conventions.md然后按照里面约定写。”结尾再加一句“写完把新页面信息更新到 memory/06-progress.md。”一旦你形成这种带节奏的对话习惯Agent 就会逐渐把记忆读写当成一个固定动作。另外一个实用技巧把记忆文件的变化和 git 绑定。既然memory/是项目的一部分它的更新也会出现在 git diff 里。你可以在 commit 时顺手看一眼“这次对话 Agent 在记忆层面更新了什么”等于给记忆机制加了人工审计。有几次我就是在 git 里看到 Agent 自己往 ADR 里写了一行“把接口超时时间改为 10s”才发现它做出了我根本没授意的决策及时纠正了回来。3.4 第四步进阶给 Agent 接一个轻量级语义检索器如果你的项目已经到了“记忆文件多到不知道读哪个”的规模或者你希望 Agent 能自动从历史对话里翻信息那就来试试语义检索。我最推荐的轻量级方案是用 Python sqlite-vec不需要单独启动服务直接是一个本地文件数据库。你需要做的是三步一、把你和 Agent 的历史对话导出成文本二、把文本按固定长度比如 300 到 500 字切块调用 Embedding 接口转成向量三、把向量和文本一起存进 sqlite-vec 表里。检索时把当前问题转成向量用 sqlite-vec 内置的相似度查询把最相关的几块文本取出来注入到 Agent 的上下文里。这套方案的技术门槛主要在前两步涉及到数据清洗和 Embedding 成本。如果你对代码不熟也可以用现成的用户界面工具把对话导出并切块。但我想反复强调引入语义检索不是必需项。我见过不少团队把简单问题搞复杂最后系统要维护、模型要升级、费用还翻倍产出却和结构化记忆差不多。先把记忆库玩明白再考虑语义检索这才是务实的路径。4. 长期记忆落地中的踩坑实录与排查经验4.1 踩坑一记忆膨胀什么都往文件里塞就废了记忆库跑了一个多月后最容易出现的问题就是膨胀。一开始06-progress.md只有几行“当前进度”后面越写越多把每天的对话总结、每个小功能的完成状态都记录了很快就变成了一本流水账。Agent 每次读这个文件要花大量 token 在一堆过时信息上找重点反而“捡了芝麻丢了西瓜”忽略了真正重要的当前进度。排查方法很简单当 Agent 回答开始变得迟缓或者明显抓不住重点项目时打开记忆文件看一眼如果超过 500 行绝对是该清理了。我的处理办法是给记忆文件设“保质期”比如06-progress.md只保留最近一轮迭代的内容完成一个迭代就清空重写04-coding-conventions.md只留真正影响代码风格的硬规则删掉那些“希望你有空时做”的软建议。记忆不是越多越好保持精简才能保持命中率。4.2 踩坑二写了记忆规则Agent 就是不看跑记忆方案第二周我一度怀疑自己是不是白折腾了——明明AGENTS.md里写得清清楚楚“必须先读 memory/README.md”Agent 每次还是无视直接就回答我的问题。后来我排查下来发现有几个典型原因。首先是指令文件的位置不对。Codex 的AGENTS.md必须放在启动命令的当前工作目录Claude Code 的CLAUDE.md默认只会读取第一次启动目录层级的文件不是放在项目任意子目录都生效。其次是指令的语气太弱。像“你可以参考记忆”这种话在模型眼里等同于“假装没看见”。改成“你必须先读取”之后执行率立竿见影地提升。最后是模型差异。同样一套记忆规则GPT-5 系和 Claude 系在执行力度上真的有差别有的模型对“多文件读取”的指令很懒惰这时候可以退一步把所有指令都浓缩进单文件CLAUDE.md不要依赖它主动去读子文件。4.3 踩坑三上下文窗口有限记忆塞太多反而变笨这是一个容易被忽略的“隐性坑”。给 Agent 塞记忆不是免费的每一条记忆都要占上下文窗口。模型有一个有效注意力区间当记忆内容超过这个区间的前半部分时新任务的指令反而会被“稀释”。换句话说你把 5 万字项目文档全部塞进去Agent 写代码时反而更容易忽略你当前的明确指令。缓解方案有两个。一是“分层注入”最核心的指令放在系统提示或主指令文件最前面项目详情放到子文件里按需读进度信息只读最近更新那一版。二是“离线总结”当记忆文件太大时用 Agent 自己把旧记忆总结成一段摘要存到archive/目录主记忆文件里只留摘要链接。这也是我在长项目里最常用的收敛手段——把记忆从“无限增长”变成“滚动更新”。4.4 踩坑四多个 Agent 协作记忆互相打架很多团队已经开始同时用多个 Coding AgentCI 流程里跑一个本地开发用另一个甚至一个管前端一个管后端。如果它们各自读写不同的记忆文件很快就会乱套。最典型的情况是Agent A 更新了自己的progress.mdAgent B 完全看不到还照着旧进度继续干更可怕的是两个 Agent 同时往coding-conventions.md里写相冲突的规则把人搞懵。我建议的解法是让记忆仓库成为单一事实来源。无论多少个 Agent都只读写同一个项目仓库根目录下的memory/不要在各自的工作目录里分别建一套记忆库。如果担忧并发写入冲突给每个 Agent 指定一个专属记忆文件比如progress-frontend.md、progress-backend.md公共约定文件如coding-conventions.md只允许人写不允许 Agent 直接改。记住越是自动化越要明确“谁能写、谁只能读”的边界否则记忆系统会变成新的混乱源。4.5 踩坑五期望过高以为记忆能替代代码评审最后分享一个心态层面的坑。很多人给 Agent 装上记忆后会陷入一种“它什么都知道所以可以完全信任它”的幻觉。但长期记忆解决的是“上下文的一致性”不是“输出的正确性”。记忆再完整Agent 依然会写出错误代码依然需要代码评审和测试兜底。我自己有一个比较务实的原则用记忆换效率不用记忆换质量。效率体现在少解释背景、少重复约定、少纠正风格但功能正确性上的把关该人工评审的步骤一步都不能省。把记忆系统理解成“让协作者更懂规矩”它就很好用了如果你把它理解成“装了记忆就全自动开发”早晚会被现实狠狠打脸。5. 关于这次国庆限时招募聊聊我的真实想法说了这么多最后回到这个项目的标题——国庆限时招募“给你的 Coding Agent 装上长期记忆”。我为什么要在国庆假期搞这场招募因为关注这个主题的人虽然多但真正能独立把记忆系统落地的人非常少。大多数人卡在了这几个地方不知道怎么设计记忆结构、不清楚不同 Coding Agent 的指令文件差异、没有一套能直接上手的模板更别提向量检索这种进阶玩法了。一个人硬憋三分钟热度一过就放弃了但一群人组队集中一个假期把这件事彻底搞定可行性要高出很多。这个招募更适合以下几类人一是已经在用 Claude Code、Codex CLI 或类似工具但始终觉得它们“不够聪明”的开发者二是团队准备全面导入 Coding Agent想先建立一套统一记忆工作流的技术负责人三是对 AI 编程协作感兴趣想趁假期系统掌握一套基于记忆库的高效开发方式的新手——注意新手用这套方案反而容易养成好习惯因为一开始就不会依赖“每轮重复解释背景”的错误模式。至于你能拿到什么我这里不多展开名额和具体权益以原活动帖说明为准但技术内容上我可以提前透露三个核心交付一套开箱即用的长期记忆目录模板、覆盖 Claude Code 和 Codex CLI 的指令文件配置、以及一套从零到一从记忆库过渡到语义检索的完整路径。整个国庆期间我会在线陪跑答疑专门解决你在落地过程中的各种“见鬼”问题比如为什么 Agent 不读记忆、为什么记了还是犯错。我个人的真实体会是长期记忆不是一个“装完就完事”的功能而是一个需要持续养成的工程习惯。一开始你会觉得多了一套要维护的文档很麻烦但一旦跑顺你会发现自己跟 Coding Agent 的协作质感完全变了——它终于不再像一个“每节课都换新同桌”的实习生而是一个真正懂项目、懂你规矩的稳定搭档。如果你也受够了反复解释的疲惫感这个假期正好可以把这件事彻底解决。
给 Coding Agent 装上长期记忆：从失忆到稳定协作的完整方案
最近圈子里聊得最热的就是 OpenAI 那个 Codex CLI——一句 “welcome to codex”直接把命令行编程Agent带进了主流视野。紧接着 Pi Coding Agent、Claude Code、Google Jules这些工具也跟着刷屏好像一夜之间不会用Coding Agent写代码就不好意思说自己在搞开发了。但真把Coding Agent用起来的人大概率都撞上过同一堵墙这玩意儿记性太差了。上午让它帮你搭好了项目的目录结构下午开个新会话它又问你“项目用什么技术栈”你明明在上一轮强调了“别用 any全部用 interface”换个会话它转头就给你写满 any。这种“每开一个窗口就失忆一次”的体验气得人分分钟想把它卸载重装。Coding Agent要真正成为团队里的一员而不是一个每次都要重新认识的临时外包**长期记忆就是那道绕不过去的坎。这篇文章我会从原理到实操把我自己整理的那套“给Agent装长期记忆”的方法完整拆给你看。顺带说一句国庆期间我拉了个人人都在问的限时招募一起系统折腾这件事文末会讲清楚适合谁来、能拿到什么。1. 为什么 Coding Agent 必须得有长期记忆1.1 先看看 Coding Agent 的“失忆症”到底有多严重很多人第一次用 Coding Agent都默认它“什么都知道且什么都记得”。这其实是对大模型工作方式的误解。Coding Agent 本质上是一个被封装成“程序员助手”的大语言模型它跟你对话时能看到的内容只有当前上下文窗口里塞进去的东西。这个窗口通常能装下几万到几十万的 token听起来很大但换个会话或者重启一次工具它就什么都不剩了。这就像你每天上班都换一个新工位搭档也天天换桌上没有任何历史资料每次干活前都要把所有背景重新说一遍。今天说“后端框架是 NestJS数据库用 PostgreSQL”明天换个会话问它“查询接口怎么写”它回你“假设我们用 Spring Boot 和 MySQL”开始胡说。这就是Coding Agent在真实项目里最让人抓狂的地方——它永远在用“第一次认识你的视角”跟你协作。更隐蔽的问题是模型对整个对话历史的依赖非常线性。哪怕在同一个会话里只要中间穿插了大量的报错信息和调试输出早期你说的“不要改 A 文件只改 B 文件”这种关键约束也会被上下文挤到边缘模型读到后面就“忘记”前面的指令了。这种失忆不是偶发而是结构性的必然。你可能会觉得那我每次给它一个详细的 prompt把所有要求写清楚不就行了能行但这相当于每次开会前都要把项目全部文档读一遍对话成本极高而且人总有写漏的时候。真正可持续的解决方案是把记忆从“对话内容”里抽离出来落到项目能持久保存的地方。1.2 失忆带来的连锁成本远比想象中高失忆的第一个成本是钱。现在好一点的 Coding Agent 基本都按 token 计费每次开新会话为了让 Agent 回忆起项目背景你得先喂它几千甚至上万字的项目说明。这些“重复的背景介绍”没有产生任何新的价值纯粹是白烧 token。一个稍微上规模的项目光是把背景反复解释给 Agent 听一个月可能多烧几十美元的 API 费用。第二个成本是决策漂移。开发中最怕的不是慢而是前后不一致。今天你让 Agent 用 pnpm 装依赖明天它给你建议 npm今天说错误处理统一用全局异常拦截器明天它又在一个新接口里写 try/catch。每一次失忆都可能让项目架构往不同方向偏一点最后整个代码库变成四不像。这种“精神分裂式”的代码风格后期维护成本足以让任何一个技术负责人头疼。第三个成本最隐性但最致命——信任崩塌。当 Agent 每次都要你重复背景、总把之前的约定忘光时你会下意识怀疑它输出的所有代码。本来用 Coding Agent 是为了把精力从“写代码”转移到“评审代码”结果变成了”盯场子”反而更累了。我见过太多人从“狂热使用”到“彻底弃用”根本原因都不是模型能力不行而是记忆能力跟不上。1.3 长期记忆到底该记什么不该记什么要给 Agent 装长期记忆首先要定义清楚“记忆”包含哪些信息。不是所有东西都值得记记忆是有容量的也有优先级。我把编码场景的长期记忆分成四层项目资产层技术栈、目录结构规范、构建命令、测试命令、依赖管理方式。这些是 Agent 干活前必须知道的东西属于“最低配置”。决策记录层为什么要抛弃 X 方案选 Y 方案为什么要用 monorepo为什么数据库加了一层 Redis 缓存。这类“背后的原因”Agent 不会直接从代码里看出来但恰恰是它做后续决策时最需要的。约定偏好层团队代码风格用单引号还是双引号缩进几个空格、命名习惯接口用IUserService还是UserService、TypeScript 里允不允许用any。这些你作为代码评审者最在意的点必须让 Agent 刻进 DNA。进度状态层当前正在做哪个功能做到了哪一步哪个文件改到一半下一步是什么。这个信息对跨会话续接最有用。但有三类信息我建议永远不要写进长期记忆一是临时性的调试细节比如某次报错的堆栈信息解决完就该丢二是过于底层的实现噪音比如某个函数的内部局部变量名问 Agent 的时候现查代码就行三是不断变化的运行时状态比如某次构建的耗时数据记了也很快就会过期。每类信息该放哪、怎么写、如何被 Agent 读取更新就是后面实操部分要展开的事。2. 给 Agent 装长期记忆的三种主流思路2.1 文件记忆最朴素但永远不过时长期记忆最直接的落地方式就是把它写进项目里的文件。现在各种 Coding Agent 都支持“项目级指令文件”比如 Claude Code 的CLAUDE.mdOpenAI Codex 的AGENTS.md还有很多 IDE 插件用的.cursorrules。这类文件会在每次 Agent 启动会话时被自动加载到上下文中相当于你给每个项目配了一份“入职手册”。文件记忆最大的优势是透明且可控。它就是一个普通文本文件你随时可以打开看、改、删也可以提交到 git 里做版本管理。哪次 Agent 表现不对劲打开文件检查问题几乎一眼就能定位——大概率是文件里写了错误的信息或者干脆没写。但它也有明显缺点所有内容都挤在一个文件里会越来越大。一个成熟的 Medium 规模项目如果把目录规范、技术决策、进度记录全写进CLAUDE.md这个文件很快就会膨胀到几万字远超 Agent 关注重点的能力范围。所以我在实际项目中很少只用单文件而是把文件记忆当作“入口文件”用它去引导 Agent 读取更多细分记忆文件——这就是所谓的记忆库方案。2.2 结构化记忆库把记忆分门别类按需读取结构化记忆库的思路是在项目根目录建一个专门的记忆目录比如memory/里面按维度拆分成多个文件每个文件只承担一种记忆职责然后在入口指令文件里约定好读取规则。一个我常用的记忆库目录长这样memory/ ├── 01-project-brief.md # 项目概览与当前目标 ├── 02-tech-stack.md # 技术栈与关键依赖说明 ├── 03-architecture.md # 架构设计与目录结构约定 ├── 04-coding-conventions.md # 代码风格与命名规范 ├── 05-adr.md # 架构决策记录ADR ├── 06-progress.md # 当前进度与下一步计划 └── README.md # 记忆库索引说明每个文件是干嘛的然后在AGENTS.md或CLAUDE.md里写一段比较强硬的指令每次会话开始时你必须先读取memory/README.md了解记忆库结构然后根据当前任务读取对应的记忆文件涉及架构实现必须读 03-architecture.md涉及写代码必须读 04-coding-conventions.md任务结束后如果进度有变化必须更新 06-progress.md。这套方案的精髓在于**“按需读取”**。不用把几万字的记忆全部塞进上下文Agent 只会加载跟当前任务相关的几个文件既节省 token又提高了记忆的命中率。我在自己项目里用这套方案跑了三个月最直观的感受就是Agent 对新会话的“适应期”几乎消失了开场就能进入干活状态。2.3 向量检索记忆让 Agent 拥有“模糊搜索”能力文件记忆和结构化记忆都有一个共同的瓶颈它们是静态的Agent 只能读你写好的内容。你忘了写进去的知识Agent 就不可能知道。而且历史对话里的很多临时结论“哦这个接口返回结构改成{ data, code, msg }了”事后没有同步到文件里就彻底丢了。向量检索记忆解决的是“动态知识沉淀”的问题。思路是把历史对话、文档片段、甚至代码注释切成小块用 Embedding 模型转成向量存进向量数据库每次 Agent 需要记忆时把当前任务描述也转成向量去库里做相似度检索把最相关的 Top-K 条记忆注入上下文。听起来高大上其实原理就是给 Agent 装了一个“项目专属的搜索引擎”。它不只记你主动告诉它的东西还能在历史信息里“翻找”。在技术选型上轻量级方案可以用sqlite-vec直接在本地文件里做向量检索零部署成本或者是 Python 社区常用的chromadb后端项目也可以考虑pgvector直接复用 PostgreSQL。这套方案也有一些麻烦。首先它需要额外搭建服务比纯文本文件复杂得多其次 Embedding 会引入额外延迟如果每轮对话都要做检索体验会打折扣最后向量检索的结果未必比你精心写的文件准它返回的是“相似”片段不是“正确”答案。所以这套方案更适合大项目比如多模块的大仓、或者历史对话特别多的老项目小项目用它就是杀鸡用牛刀。2.4 方案选型对比别纠结按项目大小选为了帮你少走弯路我把三种方案放在一张表里做了对比方案落地成本记忆上限检索能力透明度适合场景单文件记忆极低小几万字会膨胀几乎为零极高小项目、脚本仓库结构化记忆库低中可按维度拆分靠人工组织很高大多数业务项目向量检索记忆高很高理论无上限语义相似度检索一般大型项目、历史语料多我个人的建议是先用结构化记忆库它覆盖了八成以上的场景。等哪天你发现记忆文件已经多到无法有效索引再考虑引入向量检索。不要一上来就搞 Chroma Embedding很多项目折腾完根本用不上最后只留下一堆维护成本。3. 实操从零搭建一套长期记忆系统3.1 第一步在你的项目根目录创建记忆骨架先在项目根目录建一个memory/目录并在里面创建上面列出的六个核心文件。这一步不需要写太多内容先把骨架搭好。然后打开项目的主入口指令文件——如果你用的是 Codex那就是AGENTS.md如果是 Claude Code那就是CLAUDE.md如果两个都用建议在两个里都写同一段规则保持一致。我这里给出一个可以直接复制修改的AGENTS.md模板核心是记忆读写规则Memory Protocol本仓库存在memory/目录用于存放长期记忆。每次会话开始必须读取memory/README.md了解各文件用途。根据任务类型读取对应记忆文件涉及技术栈选择读02-tech-stack.md涉及架构与目录结构读03-architecture.md涉及代码书写读04-coding-conventions.md涉及方案取舍读05-adr.md会话期间如果产生了新的、长期有效的结论如选定某个库、变更某个约定必须同步更新到对应记忆文件。会话结束时必须更新06-progress.md记录当前进度与待办事项。这段规则写得“强硬”一点是有必要的。很多 Agent 默认不会主动去读额外文件如果你用“你可以看看”这种语气它大概率就不看了。直接用“必须”而且在每个子任务开始前重申规则才能保证记忆机制被真正执行。3.2 第二步填充关键记忆文件重点关注风格和决策骨架建好后最重要的一步是把记忆内容填进去。这一步千万不要偷懒因为后续 Agent 的所有输出质量都取决于你喂给它的记忆质量。先写01-project-brief.md控制在 200 字以内写清楚项目是干嘛的、当前核心目标是什么。比如“这是一个社区团购的后台管理系统当前目标是完成订单管理模块的开发。已完成商品模块正在进行订单列表接口联调。”再写04-coding-conventions.md这个文件在实践中最容易出效果。把你平时评审代码时总在说的那些话统统写进去TypeScript 必须开严格模式禁止使用any函数名用动词开头布尔变量用is/has/can开头所有 API 返回值统一包装成{ data, code, msg }样式优先用 Tailwind不要写原生 CSS。这类信息一旦进记忆Agent 写出来的代码立刻就有“团队味”而不是算法题味。05-adr.md是很多人会忽略但特别重要的一个文件。比如你之前决定不用 Redux 改用 Zustand理由是“代码量减少、样板代码少”把这个“为什么”写进去。Agent 后续看到 Zustand 时就不会一脸懵地问“这个项目怎么不用 Redux”它知道这是有意的决策而不是历史遗留。决策记录是 Agent 从“代码工人”进化到“协作伙伴”的关键一步。3.3 第三步让 Agent 养成“先读后写、事毕更新”的习惯记忆文件写好了需要 Agent 形成“读记忆 → 干活 → 更新记忆”的闭环。这一环节光靠AGENTS.md里的静态规则还不够因为规则再强Agent 也可能在执行一轮任务后就不“记得”这条规则了。我的经验是在会话进行中通过 prompt 主动强化。比如你让它写一个新页面开头就说“先读 memory/04-coding-conventions.md然后按照里面约定写。”结尾再加一句“写完把新页面信息更新到 memory/06-progress.md。”一旦你形成这种带节奏的对话习惯Agent 就会逐渐把记忆读写当成一个固定动作。另外一个实用技巧把记忆文件的变化和 git 绑定。既然memory/是项目的一部分它的更新也会出现在 git diff 里。你可以在 commit 时顺手看一眼“这次对话 Agent 在记忆层面更新了什么”等于给记忆机制加了人工审计。有几次我就是在 git 里看到 Agent 自己往 ADR 里写了一行“把接口超时时间改为 10s”才发现它做出了我根本没授意的决策及时纠正了回来。3.4 第四步进阶给 Agent 接一个轻量级语义检索器如果你的项目已经到了“记忆文件多到不知道读哪个”的规模或者你希望 Agent 能自动从历史对话里翻信息那就来试试语义检索。我最推荐的轻量级方案是用 Python sqlite-vec不需要单独启动服务直接是一个本地文件数据库。你需要做的是三步一、把你和 Agent 的历史对话导出成文本二、把文本按固定长度比如 300 到 500 字切块调用 Embedding 接口转成向量三、把向量和文本一起存进 sqlite-vec 表里。检索时把当前问题转成向量用 sqlite-vec 内置的相似度查询把最相关的几块文本取出来注入到 Agent 的上下文里。这套方案的技术门槛主要在前两步涉及到数据清洗和 Embedding 成本。如果你对代码不熟也可以用现成的用户界面工具把对话导出并切块。但我想反复强调引入语义检索不是必需项。我见过不少团队把简单问题搞复杂最后系统要维护、模型要升级、费用还翻倍产出却和结构化记忆差不多。先把记忆库玩明白再考虑语义检索这才是务实的路径。4. 长期记忆落地中的踩坑实录与排查经验4.1 踩坑一记忆膨胀什么都往文件里塞就废了记忆库跑了一个多月后最容易出现的问题就是膨胀。一开始06-progress.md只有几行“当前进度”后面越写越多把每天的对话总结、每个小功能的完成状态都记录了很快就变成了一本流水账。Agent 每次读这个文件要花大量 token 在一堆过时信息上找重点反而“捡了芝麻丢了西瓜”忽略了真正重要的当前进度。排查方法很简单当 Agent 回答开始变得迟缓或者明显抓不住重点项目时打开记忆文件看一眼如果超过 500 行绝对是该清理了。我的处理办法是给记忆文件设“保质期”比如06-progress.md只保留最近一轮迭代的内容完成一个迭代就清空重写04-coding-conventions.md只留真正影响代码风格的硬规则删掉那些“希望你有空时做”的软建议。记忆不是越多越好保持精简才能保持命中率。4.2 踩坑二写了记忆规则Agent 就是不看跑记忆方案第二周我一度怀疑自己是不是白折腾了——明明AGENTS.md里写得清清楚楚“必须先读 memory/README.md”Agent 每次还是无视直接就回答我的问题。后来我排查下来发现有几个典型原因。首先是指令文件的位置不对。Codex 的AGENTS.md必须放在启动命令的当前工作目录Claude Code 的CLAUDE.md默认只会读取第一次启动目录层级的文件不是放在项目任意子目录都生效。其次是指令的语气太弱。像“你可以参考记忆”这种话在模型眼里等同于“假装没看见”。改成“你必须先读取”之后执行率立竿见影地提升。最后是模型差异。同样一套记忆规则GPT-5 系和 Claude 系在执行力度上真的有差别有的模型对“多文件读取”的指令很懒惰这时候可以退一步把所有指令都浓缩进单文件CLAUDE.md不要依赖它主动去读子文件。4.3 踩坑三上下文窗口有限记忆塞太多反而变笨这是一个容易被忽略的“隐性坑”。给 Agent 塞记忆不是免费的每一条记忆都要占上下文窗口。模型有一个有效注意力区间当记忆内容超过这个区间的前半部分时新任务的指令反而会被“稀释”。换句话说你把 5 万字项目文档全部塞进去Agent 写代码时反而更容易忽略你当前的明确指令。缓解方案有两个。一是“分层注入”最核心的指令放在系统提示或主指令文件最前面项目详情放到子文件里按需读进度信息只读最近更新那一版。二是“离线总结”当记忆文件太大时用 Agent 自己把旧记忆总结成一段摘要存到archive/目录主记忆文件里只留摘要链接。这也是我在长项目里最常用的收敛手段——把记忆从“无限增长”变成“滚动更新”。4.4 踩坑四多个 Agent 协作记忆互相打架很多团队已经开始同时用多个 Coding AgentCI 流程里跑一个本地开发用另一个甚至一个管前端一个管后端。如果它们各自读写不同的记忆文件很快就会乱套。最典型的情况是Agent A 更新了自己的progress.mdAgent B 完全看不到还照着旧进度继续干更可怕的是两个 Agent 同时往coding-conventions.md里写相冲突的规则把人搞懵。我建议的解法是让记忆仓库成为单一事实来源。无论多少个 Agent都只读写同一个项目仓库根目录下的memory/不要在各自的工作目录里分别建一套记忆库。如果担忧并发写入冲突给每个 Agent 指定一个专属记忆文件比如progress-frontend.md、progress-backend.md公共约定文件如coding-conventions.md只允许人写不允许 Agent 直接改。记住越是自动化越要明确“谁能写、谁只能读”的边界否则记忆系统会变成新的混乱源。4.5 踩坑五期望过高以为记忆能替代代码评审最后分享一个心态层面的坑。很多人给 Agent 装上记忆后会陷入一种“它什么都知道所以可以完全信任它”的幻觉。但长期记忆解决的是“上下文的一致性”不是“输出的正确性”。记忆再完整Agent 依然会写出错误代码依然需要代码评审和测试兜底。我自己有一个比较务实的原则用记忆换效率不用记忆换质量。效率体现在少解释背景、少重复约定、少纠正风格但功能正确性上的把关该人工评审的步骤一步都不能省。把记忆系统理解成“让协作者更懂规矩”它就很好用了如果你把它理解成“装了记忆就全自动开发”早晚会被现实狠狠打脸。5. 关于这次国庆限时招募聊聊我的真实想法说了这么多最后回到这个项目的标题——国庆限时招募“给你的 Coding Agent 装上长期记忆”。我为什么要在国庆假期搞这场招募因为关注这个主题的人虽然多但真正能独立把记忆系统落地的人非常少。大多数人卡在了这几个地方不知道怎么设计记忆结构、不清楚不同 Coding Agent 的指令文件差异、没有一套能直接上手的模板更别提向量检索这种进阶玩法了。一个人硬憋三分钟热度一过就放弃了但一群人组队集中一个假期把这件事彻底搞定可行性要高出很多。这个招募更适合以下几类人一是已经在用 Claude Code、Codex CLI 或类似工具但始终觉得它们“不够聪明”的开发者二是团队准备全面导入 Coding Agent想先建立一套统一记忆工作流的技术负责人三是对 AI 编程协作感兴趣想趁假期系统掌握一套基于记忆库的高效开发方式的新手——注意新手用这套方案反而容易养成好习惯因为一开始就不会依赖“每轮重复解释背景”的错误模式。至于你能拿到什么我这里不多展开名额和具体权益以原活动帖说明为准但技术内容上我可以提前透露三个核心交付一套开箱即用的长期记忆目录模板、覆盖 Claude Code 和 Codex CLI 的指令文件配置、以及一套从零到一从记忆库过渡到语义检索的完整路径。整个国庆期间我会在线陪跑答疑专门解决你在落地过程中的各种“见鬼”问题比如为什么 Agent 不读记忆、为什么记了还是犯错。我个人的真实体会是长期记忆不是一个“装完就完事”的功能而是一个需要持续养成的工程习惯。一开始你会觉得多了一套要维护的文档很麻烦但一旦跑顺你会发现自己跟 Coding Agent 的协作质感完全变了——它终于不再像一个“每节课都换新同桌”的实习生而是一个真正懂项目、懂你规矩的稳定搭档。如果你也受够了反复解释的疲惫感这个假期正好可以把这件事彻底解决。