你有没有遇到过这种情况跟 Coding Agent 聊了快一个小时从架构设计到接口约定全都对齐了它甚至帮你把目录结构和核心接口都搭好了。你满意地合上电脑第二天早上重新打开一个新的会话把项目路径指给它结果它一脸茫然地从头开始问你这个项目是干嘛的。那一刻你才意识到Coding Agent 写代码的能力再强记不住事也是白搭。OpenAI 那个命令行编程智能体 Codex CLI 刚出来时那句欢迎语 “Welcome to Codex” 让不少人心里一热——终于可以在终端里直接指挥一个会写代码的 Agent 了。社区里像 pi coding agent 这类轻量方案也陆续冒出来但无论是哪家的 Coding Agent都有一个绕不开的硬伤会话一关记忆清零。你复述了多少遍背景它下次照样问。这就是我最近一直在折腾的事情——给 Coding Agent 装上长期记忆。这篇文章我打算用做项目的方式把这段时间踩过的路完整拆开长期记忆到底该存什么、有哪几种落地形态、怎么一步一步搭起来、哪些坑我帮你先踩了。不管你现在用的是 Codex CLI、某个开源 Coding Agent还是自己搭的自动化编码管线这套记忆方案都有参考价值。全文没有高深理论都是可以直接抄作业的配置、脚本和排查方法。1. Coding Agent 的“金鱼记忆”困局1.1 会写代码但记不住事的 Agent先说一个扎心的现象。我最初用这类命令行 Coding Agent 的时候最大的体感是“智商高记性差”。它写 CRUD 接口、调试报错、生成测试代码都挺利索但只要任务一多、会话一长就开始犯迷糊。更头疼的是一旦断开重开一个 session它就彻底“失忆”了。你可能会想上下文窗口不是动辄 128K、200K 了吗怎么还记不住这里有个很容易忽略的点上下文窗口是“工作记忆”不是“长期记忆”。Agent 能看到的只有当前这次对话里塞进去的内容。窗口再大也只能覆盖几个小时的对话历史一旦新会话开启之前聊的架构决策、技术选型理由、目录约定全都跟这个会话一起消失了。这就像一个能力很强的外包工程师每天早上来上班都要重新问一遍你上周五拍板的那几个问题。我在本地实验的时候统计过一个稍微复杂一点的任务比如给老项目加一个模块我至少要花两三轮对话重新交代一遍项目背景和约束条件。算下来因为“失忆”导致的无效沟通大约占了整个开发时长的三到四成。这是纯粹的成本浪费不是 Coding Agent 能力不够是它没有“记忆器官”。1.2 长期记忆到底该记什么既然要给 Coding Agent 装记忆第一步不是急着写代码而是先想清楚一件事记什么。一开始我犯过一个错误想把所有对话历史全部存下来指望 Agent 需要时自己翻。结果就是记忆库越滚越大真正有用的信息被淹没在一堆“嗯嗯”“好的”“我马上看一下”这种交互噪音里。检索的时候召回一堆乱七八糟的东西比不装记忆还糟。后来我按信息价值把该记的内容重新梳理了一遍大致分成五类项目约定目录结构、命名规范、代码风格、框架约束。这类信息是 Agent 判断“怎么写代码”的基础。架构决策为什么选 PostgreSQL 而不是 MySQL、为什么把支付模块拆成独立服务。这类信息是防止未来会话推翻旧决策的关键。用户偏好比如“接口返回统一包装成{code, msg, data}”或者“测试文件必须放在__tests__目录下”。这类信息决定产出的可用性。当前状态任务进行到哪一步了、哪些文件改过了、哪些测试还挂着 X 失败。这类信息用于跨会话续接任务。教训与踩坑比如“这个项目的 mock 服务不能用默认端口会跟本地代理冲突”。这类信息能避免同一个错误反复犯。反过来有几类内容明确不记纯粹的寒暄、一次性问答、已经被代码文档覆盖的信息。记忆是稀缺资源要像整理冰箱一样定期清掉过期的东西而不是往里面硬塞。2. 长期记忆的四种落地形态2.1 对话摘要最轻量的记忆方案先聊最容易上手的一种对话摘要。原理特别简单每次会话快结束时让 Agent 自己把这次聊出来的关键信息按固定模板压缩成一份摘要存到一个文本文件里。下次新会话开始时再把这份摘要注入上下文。我最早就是用这个方案几分钟就能搞定。当时定了这样一个摘要模板项目名、当前目标、已完成事项、待办事项、关键决策、下一步计划。每次会话结束让 Agent 对照模板写摘要我检查一遍就存入memory/session-summary.md。新会话开始时直接把这个文件的内容贴到系统提示词后面。这个方案有个明显的好处实现成本几乎为零不需要额外装任何东西任何一个能读文件的 Coding Agent 都能立刻支持。缺点也很明显摘要质量依赖 Agent 自己的理解能力而且一旦项目周期变长摘要文件本身就会膨胀最后变成一份没人会看的超长文档。它更适合作为整套记忆方案的第一层而不是唯一方案。2.2 记忆文件给 Agent 一本工作笔记第二层是结构化记忆文件这也是我现在用得最多、性价比最高的方案。核心思路不是存“这次聊了什么”而是存“这个项目长期有效的事实”。你一定听说过AGENTS.md或者CLAUDE.md这类文件的本质就是给 Agent 看的“工作笔记”让它在开始干活之前先读一遍项目约定。我在此基础上做了扩展直接建了一个memory/目录里面放了几个固定命名的文件project.md项目全局信息包括背景、目标、技术栈、目录结构。decisions.md架构决策日志每一条带日期、背景、结论和替代方案。preferences.md用户偏好像“接口格式统一走{code, msg, data}”这类。progress.md当前任务状态做跨会话续接用。lessons.md踩坑记录每次解决完一个诡异问题就往里写一条。这套方案比单纯摘要强在哪它把不同类型的记忆分门别类地放在固定位置Agent 需要哪类信息就直接去读对应文件不会出现“翻完整个摘要就为了找一个接口命名约定”的情况。而且这些文件对人也同样可读你随时能翻开看看项目里到底沉淀了什么。2.3 向量检索库按需回忆的“外接大脑”如果说记忆文件是笔记那向量检索库就是给 Agent 装了一个真正意义上的“外接大脑”。思路是把历史对话、技术文档、代码变更记录全部切成小块做 embedding 向量化之后存入向量数据库。当 Agent 遇到一个新问题时在库里按相似度做检索只把最相关的片段召回并注入上下文。这个方案我在第三个阶段才尝试因为它的搭建成本明显高一些。你需要一个向量数据库我用的是本地跑的轻量方案还要写一段检索逻辑把命中的片段拼回 prompt 里。但它解决了一个根本问题记忆文件是“人工分类”的你得先决定某条知识该放在哪个文件里向量检索是“语义召回”的信息丢进去就行用的时候靠内容相似度找回来不用先想好分类。这更接近人脑的记忆方式——你不是按照“第几章第几节”来回忆而是按语义触发。唯一的问题是召回质量很依赖 embedding 模型和切分策略。后面我在第四个部分专门讲讲我在召回上踩过的坑。2.4 技能沉淀把经验固化成资产第四层跟前面三层不太一样它记的不是“发生了什么”而是“怎么做”。我管这叫技能沉淀。举个例子。我经常让 Coding Agent 给 Python 项目补测试但每次新项目它都会犯同样的错误忘了在conftest.py里配置 fixture或者测试数据库不隔离。后来我把一套完整的“给 Python 项目补测试”的标准流程整理成一个技能包包含步骤、模板代码、验收标准。下次再遇到类似任务Agent 直接调用这个技能包而不是从零摸索。技能沉淀是“把做对过的事变成能重复调用的资产”。它需要你在每次任务结束后主动复盘把泛化能力强的经验提炼成技能。相比前三种“被动记忆”这种方式算是更高级的主动复用。很多项目里把这类技能叫 Skill 或者 PluginOpenAI Codex 这类 Agent 也在支持类似的扩展机制。如果你正在做一个长期项目我建议从第一天起就建一个skills/目录。我把这四种形态的适用场景和工作量做个表方便你对照选择记忆形态核心理念实现成本信息粒度适合阶段对话摘要总结会话要点极低粗个人试用、快速验证记忆文件分类存事实低中中大型项目主力方案向量检索语义按需召回中高细超长周期、大量历史记录技能沉淀经验变成可复用资产中高反复执行同类型任务3. 实操从零给 Coding Agent 装上长期记忆3.1 先定边界项目级记忆还是用户级记忆动手之前先解决一个边界问题这套记忆是跟着项目走还是跟着你这个人走我建议分两层。项目级记忆放在项目仓库里跟代码一起走。团队协作时把这个目录加入版本控制大家用同一个 Agent 都能看到同一份记忆。用户级记忆放在你的用户目录下记录的是跨项目的个人偏好比如“我习惯接口文档用中文写”或者“错误日志统一用 JSON 格式输出”。我见过不少人一上来就搭一个庞大的全局记忆库什么信息都往里塞结果每个项目反而被无关的全局记忆干扰。正确做法是先做项目级记忆这是收益最高的部分。等用顺手了再考虑把跨项目的偏好抽到用户级。3.2 搭一个记忆仓库的骨架下面是我目前在用的记忆仓库结构你可以直接照着建your-project/ ├── memory/ │ ├── project.md # 项目全局信息 │ ├── decisions.md # 架构决策日志 │ ├── preferences.md # 用户偏好与编码约定 │ ├── progress.md # 当前任务进度 │ └── lessons.md # 踩坑记录 ├── skills/ │ ├── add_python_tests.md # 技能包补测试流程 │ └── code_review.md # 技能包代码评审清单 └── .agent-session.md # 临时会话状态用完即弃每个文件的开头我建议都写一段“内容说明 最近更新时间”方便 Agent 快速判断这个文件是否值得读、信息是否新鲜。比如project.md开头就是# project.md 本文件记录项目全局信息会话开始时必读。 最近更新2025-09-28decisions.md里每一条决策用固定格式写带时间戳和状态这样就不会被旧决策污染。# decisions.md ## 2025-09-20支付模块独立成服务 - 背景订单流程里支付逻辑越来越复杂影响下单接口稳定性 - 决策拆成独立服务通过异步消息通信 - 替代方案继续内嵌在订单服务里否耦合过高 - 状态已实施3.3 用系统提示词约束记忆读写协议文件结构搭好了还差最关键的一步让 Agent 知道什么时候读、什么时候写。这需要在系统提示词里加一段“记忆协议”。我现在的做法是在系统提示词里固定加一段话你是一个带有长期记忆的编程智能体。 【会话开始前】 1. 如果项目目录下存在 memory/project.md必须先阅读 2. 根据任务类型选择性阅读 memory/decisions.md 和 memory/preferences.md 3. 如果存在 memory/progress.md先了解当前进度在旧进度基础上继续。 【会话进行中】 - 当你确定了新的接口命名、架构决策或用户偏好时主动准备记录到对应的 memory 文件中。 【会话结束前】 1. 更新 memory/progress.md记录本次会话完成事项、未完成事项 2. 如果产生了新的架构决策或踩坑经验主动更新 decisions.md / lessons.md 3. 删除 .agent-session.md 中的临时状态如果有。 【注意】 - 写入 memory 文件时保持简洁、结构化不要大段复制对话内容 - 不确定是否该记录的信息宁可少写也不多写。你可能会问Agent 真的会遵守这套协议吗实测下来在系统提示词里写清楚规则之后配合度很高。因为现在的 Coding Agent 本质上都是遵循指令的对话模型你只要把“何时读、何时写”说清楚它就会像一个带工作日志习惯的工程师一样执行。关键是不可贪多规则越多越容易被忽略这几条已经是压到不能再少的底线了。3.4 召回策略什么时候翻记忆翻哪一层记忆存好了怎么用才是精髓。我把记忆注入分成两层第一层是“常驻注入”。把project.md和最新的progress.md作为固定内容放在系统提示词或者第一次用户消息里。这部分信息量不大但每一个任务都依赖它必须随叫随到。第二层是“按需检索”。把decisions.md、lessons.md、preferences.md做成候选池根据任务类型动态检索。怎么判断该翻哪个文件最简单的方式是写一段规则如果任务涉及架构调整或技术选型读decisions.md如果任务涉及写代码读preferences.md和lessons.md如果任务和某个曾经的诡异问题相关先检索lessons.md。用了向量检索之后我把这段规则简化成了“根据任务描述做语义检索召回前 5 段最相关内容”。当时设的参数是文本按 800 字符左右切块top-k 取 5相似度阈值设为 0.45。这个组合在多数场景下效果都不错既能保证召回相关性又不会引入太多碎片。关于上下文窗口怎么分配我算过一笔账如果模型上下文窗口是 200K token日常任务的代码和中间输出会占掉大部分留给记忆的预算其实很紧张。我的经验值是常驻注入控制在 2K token 以内按需检索控制在 4K token 以内给真正的任务执行留出空间。别贪心把整本记忆库都塞进去那不是记忆是干扰。4. 实战踩坑与排查实录4.1 记忆污染最容易被忽视的大坑记忆系统的第一杀手不是“记不住”而是“记错”。我吃过一个大亏某个项目里有一次框架升级把旧的目录结构全改了但早先的会话往project.md里写的内容还是旧结构。结果后面对话里 Agent 反复按旧结构找文件闹出一堆不存在的路径白白折腾了大半天。这次之后我定了一个铁律任何记忆文件里都不得留存“历史状态”的存量描述只能写“当前状态”。具体做法是文件更新时直接覆盖而不是追加保留历史。旧决策放到decisions.md里带状态字段当前状态只体现在progress.md的文件顶部。另外我给所有记忆条目都加了一个“更新时间”。Agent 在读到记忆时能通过时间戳判断这条信息是否还有效。别小看这一行字它能避免非常多的“过期信息当现行规则”的混乱。4.2 检索失效embedding 质量与召回参数向量检索方案上线后我遇到过两种失效场景。第一种是切分粒度问题。一开始我把整个lessons.md当成一个文本块去做 embedding结果检索时相似度全被长文本稀释跟查询真正相关的那一两句话根本召不回。后来我把文本按 800 字符左右切块并且确保切块边界尽量落在自然段落上召回质量立刻提升了一大截。第二种是相似度阈值失灵。有段时间我用了 0.5 的相似度阈值结果发现很多真正相关的信息被过滤掉了召回的片段虽然相似度达标却不一定是任务需要的。这其实是因为抽象概念的语义相似度天然就低。最后我调整了策略不设死板的阈值而是用 top-k 硬召回然后在提示词里提醒 Agent“如果召回的片段与当前任务无关直接忽略不要强行使用”。这个调整很有效。4.3 常见问题速查表我把这段时间遇到的典型故障整理成了速查表方便你直接对照现象可能原因解决方法Agent 每次都要重新问一遍项目背景project.md未创建或未注入检查记忆协议是否在系统提示词中生效Agent 引用了已废弃的目录结构记忆文件没及时更新更新记忆文件时直接覆盖旧状态检索出来的内容驴唇不对马嘴文本切分粒度过大按 800 字符左右切块并保持段落边界多个项目之间记忆串味记忆库没有按项目隔离核对 memory 目录是否放进了项目仓库记忆文件越写越长Agent 越来越迟钝缺少清洗机制定期重写记忆文件只保留当前有效信息Agent 自己往记忆文件里写废话记忆协议约束不足明确写入规则简洁、结构化、不复制对话向量检索召回的片段都是重复内容没有做去重合并写入前先按 embedding 相似度查重4.4 我的独家调试技巧最后分享一下我自己的调试方法算不上高端但非常实用。第一招让 Agent 复述记忆。每次装完一套记忆方案我先不布置真实任务而是问 Agent“请根据你的记忆复述一下这个项目的技术栈、当前进度和关键约束”。它的回答直接暴露记忆库到底被读取了没有。如果复述出来的内容跟记忆文件对不上那说明注入链路有问题趁早排查。第二招做一次“记忆体检”。间隔几周我会用一段固定的提示词让 Agent 全量检查所有记忆文件标出过期信息、矛盾信息和重复信息。这个过程相当于给 Agent 的记忆做一次大扫除避免系统时间久了变成一堆陈年旧账。第三招日志回放。如果某次任务的产出明显离谱我会打开这一轮的完整交互日志检查 Agent 到底读了哪些记忆文件、检索了哪些片段。我发现九成的问题不在模型能力上而在“该读的记忆没读到”或者“读到的记忆是错的”。5. 关于这次限时招募我在想什么5.1 为什么选择“长期记忆”这个切口说了这么多回到开头那个标题——国庆限时招募。其实这就是我最近在张罗的一个事搞一个为期一周的“Coding Agent 长期记忆实战营”找一群同样在折腾 Coding Agent 的人一起把这类工具真正用起来。为什么选“长期记忆”这个切口因为我观察到一个现象现在大家在讨论 Coding Agent 时关注的几乎全是“它能写多复杂的代码”“它支持哪些工具调用”但很少人关心“它能不能把项目长期运行所需的知识稳定地延续下去”。能力再强的 Agent只要记忆是零散的、临时的就始终停留在“高级补全工具”的层面谈不上真正的智能协作。国庆这一段刚好是长假窗口适合集中折腾。我打算用这个时间带着参与者一起给各自的 Coding Agent 搭一套长期记忆系统从记忆库设计、读写协议到检索召回完整落一遍。5.2 招募计划与参与方式这个活动没有做成大型课程的意思我更愿意叫它“共修营”。人数不会太多目标是保证每个参与者的问题都能被认真对待。节奏大概是这样的Day 1 确认每个人手头的项目和 Agent 类型协助设计记忆边界和仓库结构Day 2 到 Day 3 完成记忆文件的搭建和系统提示词改造Day 4 开始接入真实任务观察 Agent 行为变化Day 5 到 Day 6 引入检索和技能沉淀进阶内容最后一天做一次全员复盘把各自沉淀出的记忆模板、技能包和踩坑记录整理成一套可复用的公共资产。参与方式很简单按照招募页面的说明提交申请就行门槛只有一个你必须有一个真正在用的项目而不是拿 Hello World 练手。没有真实项目记忆系统就是空中楼阁因为你根本感受不到“记忆缺失”带来的痛。5.3 适合谁参加、能收获什么老实说这个活动不太适合零基础的人。如果你还停留在“刚听过 Coding Agent 是什么”的阶段可能会觉得内容太干、节奏太快。我觉得最适合的人是下面这几类已经用 Codex CLI、pi coding agent 这类工具做过至少一两个真实项目感受到“会话一关就失忆”的痛点。手里有一个开发周期超过两个月的项目中间需要反复切换任务上下文。团队里想统一 Coding Agent 协作方式需要一套可落地的记忆规范。能收获什么往浅了说是一套搭建记忆系统的完整实操经验往深了说是重新理解“什么才是 Agent 协作中真正有价值的信息”。我不喜欢承诺什么“七天精通”之类的话我更愿意说等你亲手把 Agent 的长期记忆跑起来之后你会再也回不去那个每次都要重新自我介绍的工作方式。我个人在折腾这一整套东西时的体会是长期记忆这件事千万别想着一步到位。先从一个memory/project.md文件开始跑顺了再加决策日志再往后才是向量检索。记忆不是越复杂越好而是越贴合你的使用习惯越好。给 Coding Agent 装上长期记忆之后那种“递一次需求、跟它连续协作一个完整周期”的踏实感确实只有体验过才知道。