如果你的 Coding Agent 每次开新会话都得把项目背景、代码规范、历史决策重新讲一遍那它本质上还不是你的结对搭档顶多算一个记性很差但很努力的外包临时工。长期记忆这件事我过去一个月里反复倒腾了好几个方案踩了不少坑今天把思路、代码和踩坑记录都整理出来顺便说一个国庆期间的限时体验招募。这篇文章适合正在用 Claude Code、Cline、Continue 这类工具的开发者也适合打算入坑 Coding Agent、但已经被每次都像初次见面搞到崩溃的人。1. 为什么你的 Coding Agent 总在假装失忆三种典型断片现场我把 Coding Agent 的失忆分成三种场景几乎每个重度使用者都遇到过。这不是 Agent 不够聪明而是现在的工具链设计本身就有天花板。1.1 会话内断片上下文窗口不是硬盘先说最让人上头的第一种明明在一个会话里聊了十来轮之后它开始把一小时前定好的方案忘掉了。你问它刚才不是说了用 compose 替代 BuildContext 吗它礼貌地道歉然后继续写一堆和结论相反的建议。这背后的机制其实很好理解。Transformer 模型在推理时只能看到当前上下文窗口内的内容窗口就是一个固定大小的草稿纸不是无限大小的仓库。长对话会把这张纸越填越满早期的信息要么被截断要么被后来的内容挤到注意力权重很低的位置。你以为它在认真听实际上它每一轮都在重新读一张越来越厚的纸而你最开始的约定早就被后续几千 token 的代码讨论淹没。我实测过单次会话的有效记忆大概在上下文窗口的 60% 左右就开始明显衰减。也就是说如果你用的 Agent 上下文是 200k不是真的能稳定记住 200k 之前的细节后半段往往需要你反复提醒。与其说这是模型缺陷不如说是使用方式出了问题——把信息塞进窗口却从没考虑过分层存储。1.2 跨会话失忆每次开工都是一次初次见面第二种更伤今天下班前你让 Agent 分析完了一个前端项目的目录结构还约定了组件命名规范第二天回来开个新会话它完全不记得。你重新描述一遍需求它又花二十分钟把已经看过的文件重新读一遍然后给出一个和昨天完全冲突的实现思路。这不是模型不行是目前绝大多数 Coding Agent 产品都是无状态的每个新会话等于在全新环境里启动。你之前喂给它的 prompt、它阅读过的文件内容、你们讨论过的取舍结论全部停留在上一个会话的上下文窗口里会话一关全部归零。很多用户误以为项目里有代码 Agent 能理解项目规范。实际上如果规范只存在于你的对话里没有沉淀成文件、没有写进启动时的 System Prompt那 Agent 每次看到的就只有代码本身而你之前告诉它的所有潜规则都会消失。你感觉它在装失忆其实是它真的不记得因为它压根没有长期存储。1.3 Agent 之间的孤岛团队记忆缺失第三种最近越来越常见团队里有人用 Codex CLI、有人用 Cline、还有人用开源方案大家各自的 Agent 都在跑但互相之间完全不共享记忆。A 同事的 Agent 发现了一个奇怪的圆角样式 bug写在了某个会话里B 同事的 Agent 在同一时间又在为同一个 bug 生成完全相反的重构方案。这个局面特别像团队每个人都有自己的笔记本但谁都不给别人看。更麻烦的是同一台机器上如果跑多个 Coding Agent它们连自己的历史都不会同步。Codex CLI 的欢迎语welcome to codex现在已经成了社区黑话越来越多命令行的 Coding Agent 在涌现但它们默认都不带跨会话记忆。说到底Agent 工具是按会话来设计的不是按项目生命周期来设计的这个错位才是长期记忆问题的根源。2. 长期记忆到底该装什么以及什么不该装想清楚记什么比研究怎么记更重要。我见过有的方案把每一条对话都存进向量库结果检索出来的全是噪音辅助效果还不如不记。2.1 四类真正值得长期留存的信息我在自己的方案里把记忆分成四层每一层我都给了明确的边界。第一层是用户偏好也就是你自己的操作习惯。比如日志用 JSON 格式不要用纯文本重构命名时保留动词不要改名词这类全局性约定。这类信息应该进核心记忆文件每次会话开始都直接喂给 Agent优先级最高。第二层是项目知识包括目录结构背后的设计意图、模块间的依赖关系、历史技术选型的理由。比如为什么这个项目用 Vuex 而不是 Pinia支付模块和订单模块的调用顺序不能动。这类信息是 Agent 理解项目的关键但很多项目根本没有写进文档完全存在于老开发的大脑里。第三层是任务状态也就是做到哪儿了。比如你在做一次涉及十多个文件的模块拆分上次会话已经完成了前三个文件的迁移剩下哪些还没改有哪些测试挂了。这层信息适合结构化存储不要塞进自然语言记忆里否则检索很容易混。第四层是结论与教训就是每次踩坑后的经验沉淀。比如升级 xxx 库后 production 构建会报 duplicate identifier需要手动清理缓存。这层信息价值密度高但数量少适合作为面试的经验库。2.2 记忆的毒性如何避免记忆越多、效果越差记忆不是越多越好这一点我从反面体验里学得最深。第一次做长期记忆时我图省事把过去两周的所有 Agent 会话全存进了 SQLite然后用关键词检索喂回上下文。结果 Agent 回复之前要先在几千条记录里找自己找到的还经常是不相关的前缀生成了大量误导。后来我做了个硬性筛选只有能影响未来至少三次会话的信息才允许进长期区一次性的临时细节只留在任务状态里。这个阈值听起来很主观但实操很有用。比如今天需要更新 README是一次性不配占记忆槽位但当前迁移策略每周一个模块禁止跨模块重构就必须记因为后面每做一步都要遵守。另外还要注意记忆过期。项目会变约定会改三个月前的决策现在可能已经失效。只写不问的记忆库迟早变成垃圾场。我建议给每条记忆加一个 updated 字段每次 Agent 读到它时顺手核对一遍和当前代码不一致的就打标签超过三次不一致自动降权。虽然麻烦但能避免长期记忆退化成长期误导。3. 五种给 Coding Agent 装记忆的实现路径与选型从最简单到最复杂我把现在社区里主流的方案都试了一遍。每种都有适用场景没有银弹。3.1 记忆文件法用项目根目录的一份 Markdown 换全局约定最简单的方式也是最容易被忽略的方式直接在项目根目录放一个专门给 Agent 读的记忆文件比如AGENTS.md、CLAUDE.md、CODE_STYLE.md。Coding Agent 工具大多支持在指令里配置启动时自动读取某些文件把核心约定写进这份文件里每次新会话等于自动注入记忆。具体格式上我建议克制一点不要写论文。用条目列出项目目标、技术栈版本身份、目录布局、命名约定、禁止事项、当前正在推进的任务。每次变更由开发者手动修改或者让 Agent 在任务结束时按模板更新。这个方案零成本、零依赖适合个人项目和 3 人以下的小团队。缺点也很明显静态文件不会自动检索历史大型项目约定多到文件膨胀之后Agent 可能花在解析记忆上的时间比干活还多。3.2 向量检索 RAG让 Agent 自己想起来历史记录第二种是把过去的会话记录、代码片段、设计文档切片后转到向量数据库里比如 sqlite-vec、LanceDB然后让 Agent 在开始任务前先用问题去做向量检索把 top-k 相关片段注入上下文。这种方式最接近让 Agent 回忆起自己做过什么不需要人去维护条目式记忆。这套方案的优势是覆盖广老对话都能被捞回来劣势是 embedding 质量直接决定检索效果同一个问题在不同日期可能触发完全不同的历史片段还得处理重复和冲突。我在试这个方案时被项目里大量版本差异搞得头大2024 年的一条旧记录说项目用 React Router v6而现在已经升到 v7检索出来反而误导 Agent。所以用 RAG 必须配合时间过滤和冲突消解规则。3.3 任务状态数据库结构化保存决策与进度这个方法适合多步骤任务。我不让 Agent 去自然语言记忆里翻自己做到哪一步了而是专门建了一个 SQLite 表来追踪任务状态每条记录包含任务 ID、文件路径、状态pending/in_progress/done/failed、依赖关系、最后更新时间。每个操作开始前查一遍操作结束后更新一遍。这么做的好处是状态永远不会丢在对话里而且是确定性的不会出现我记得它做完了其实没有的幻觉。代价是前期要花时间定义表结构还得说服自己每一次都要按照流程去更新。如果你只是拿 Agent 查一个报错这个方案明显过重如果你在做多模块重构、跨会话迁移这个方案几乎是刚需。3.4 会话摘要自动压缩低成本跨会话方案方案四是每次会话结束时让 Agent 给你写一份摘要。我试过用一条 Prompt 要求它按目标、调整、产出、遗留四点总结然后我把摘要追加到一个memory.log文件里下次开新会话时把最近 3 条摘要注入上下文。思路就是拿 token 换记忆比完整历史轻量得多。这个方案真的能解决跨天回来了不记得前几天做什么的问题而且实现成本非常低不需要额外装服务。但摘要的颗粒度很难控制太粗Agent 恢复不了具体决策太细摘要比完整代码还长注入之后白白占用上下文。我调了几轮之后决定给摘要设长度上限每条不超过 500 字写不下的丢进细节文件靠需要时再查。3.5 MCP 记忆服务与 Agent 解耦的通用接口MCP 方案是去年开始热起来的。通过 Model Context Protocol 把记忆能力暴露成独立的服务接口Agent 可以随时向这个服务发起记住查询遗忘操作记忆不再依赖于某一种 Agent 工具的私有限制也没有读文件写文件那么脆。我用 MCP 方案的时候其实是看中了它的通用性同一套记忆服务可以同时给 Cline、Continue、甚至终端里的 Codex CLI 用换工具不换记忆。代价是要多维护一个服务进程第一次配置也稍微麻烦。但如果你的工作流里同时有好几个 Agent 工具MCP 这个买卖非常划算。3.6 到底怎么选一张表讲清方案维护成本检索方式适合阶段主要风险记忆文件法极低启动注入个人项目文件膨胀后信息拥堵向量检索 RAG中语义相似度 Top-k大量历史素材旧版本误导任务状态数据库高SQL 精确查询多步骤重构定义太繁琐会话摘要压缩低追加/截断读取跨天工作摘要粗细难控制MCP 记忆服务中高接口统一查询多 Agent 环境服务稳定性我给的建议是第一次尝试的人从记忆文件 会话摘要组合开始先用一个周末跑通再考虑要不要上向量数据库。一上来就建全套记忆服务的最后大概率会因为维护成本放弃。4. 我实际在用的层级记忆方案可直接抄作业下面是我目前在用的方案。它没有用太重的外部依赖只靠项目目录下的结构化文件加一个 SQLite 文件实现我用了一周多稳定性和性价比都很不错。4.1 目录结构与核心记忆文件这是项目的记忆目录结构.agent-memory/ ├── core.md # 核心记忆偏好 项目知识 禁止事项 ├── tasks.db # 任务状态 SQLite ├── sessions/ # 每次任务的自动摘要 │ ├── 2025-09-28-feat-auth.md │ └── 2025-09-29-refactor-api.md └── lessons/ # 踩坑结论 └── 2025-09-30-typescript-duplicate.mdcore.md是整个方案的心脏必须由人维护不要完全撒手给 Agent。我建议按照固定小标题来写方便后续 Agent 解析## 项目目标 当前主线任务是拆分订单模块大纲见 docs/roadmap.md ## 技术栈 Next.js 14 / TypeScript / Tailwind ## 结构约定 - 页面组件放 app/ - 业务逻辑放 lib/use-cases/ - 禁止在页面组件内直接调用 API ## 代码风格 - 函数命名使用动词开头 - 文件命名全部小写 kebab-case - 日志必须 JSON 格式 ## 禁止事项 - 不要改 shared/ 下的类型定义除非会议通过 - 不要在 reducer 里做副作用每次新会话开始Agent 的第一件事就是读这个文件相当于给它的工作记忆做个开机初始化。4.2 读入与写回让 Agent 按流程工作我在 Agent 指令文件里写了一段自定义系统指令规定它的每个会话都必须遵守三段式流程读取.agent-memory/core.md并检查sessions/目录里最近两次摘要。开始实际任务。任务结束时用模板把本次会话产出追加到sessions/如果发现任何值得长期保存的教训写入lessons/。这个流程纯粹靠 Prompt 约定代码层面没有硬约束。关键在于任务结束的写回指令要具体到格式不能让 Agent 自由发挥。我用的模板是### 任务摘要 日期YYYY-MM-DD 目标一句话描述 完成项列表形式列出关键改动 遗留下次需要跟进的事情 决策记录本任务中做过的技术取舍及原因实测下来只要模板明确Agent 写回来的摘要质量非常稳定。我遇到过的问题是它偶尔会把整个项目的代码片段重复塞进摘要后来我在模板里加了不允许贴代码只写文件路径和行为描述问题立刻解决。4.3 轻量检索FTS5 足够不用上重型数据库需要回顾历史的时候我没有直接上向量检索引擎而是用了 SQLite 的 FTS5 全文搜索。理由很简单会话摘要和 lessons 都是自然语言素材关键词搜索已经能覆盖 80% 的回忆需求没必要为剩下的 20% 增加 embedding 复杂度。初始化一个全文检索表特别简单CREATE VIRTUAL TABLE session_search USING fts5(content, session_date, topic); INSERT INTO session_search SELECT content, date, topic FROM sessions_metadata;配合 Agent 的查询习惯我写了一个极简的 Python 脚本把查询方式封装成python search.py 订单。每次想不起来之前怎么处理某个问题时我会先跑一下这个脚本再把检索结果贴给 Agent 当提示。这套流程虽然朴拙但在一个中型项目上完全够用跑起来也比向量检索舒服得多。4.4 踩坑记录哪些设计差点让整个方案报废第一个坑是 Agent 会在写代码过程中顺手更新core.md把自己即兴发挥的偏好写进了核心记忆结果后面的会话都被它自己洗脑。解决方式是给core.md加了只读约束任何对该文件的修改都要经过我确认并且把写入权限从 Agent 自定义指令里彻底拿掉。第二个坑是摘要文件越攒越多启动时如果傻乎乎地把最近的 10 条摘要全部塞进上下文Token 消耗就非常离谱。我后来只注入最近 2 条摘要和 lessons 里最近 3 条更早的历史全部靠关键词搜索翻。记忆最有价值的不是最多而是在需要那一刻能精准出现。第三个坑是关于任务状态的。我最初把状态写在core.md里结果有一次任务跨了三天第三天的时候 Agent 把状态字段读成了已经过期的垃圾。后来我把任务状态全部挪进tasks.db并按updated_at排序状态变更时才会刷新彻底避免了人还没做完摘要已经宣布完成的错乱。5. 国庆期间的限时体验招募把这套记忆体装到你的 Agent 上这套方案我现在用得还算顺手但我知道它一定还有不少边界情况是我一个人测不出来的。正好国庆假期有整块时间我准备做一次限时体验招募把方案开放给一批有真实项目的开发者你来用我来盯问题最后把共性问题整理成一版更健壮的方案公开出来。5.1 这次招募适合谁如果你满足下面任何一条这次招募大概率会有用你已经在用 Coding Agent但每次新会话都要重新解释项目背景和代码规范你同时用两个以上 Agent 工具想让它们共享同一套项目记忆你正在做跨越多天的重构任务急需一种能记录任务进度和决策理由的机制你尝试过自己搞长期记忆但被向量库、MCP 配置劝退了。名额我会控制在 30 个人左右不是要搞饥饿营销而是我知道自己假期里能跟进的深度有限人再多就只能敷衍那没意思。5.2 参与方式和会拿到的东西这次不搞表格收集之后就不管了的方式。报名时你需要简单说一下你平时的 Agent 工作流以及你目前最想解决的失忆场景。我会按项目类型挑一批人进群统一发下面这些材料我当前的.agent-memory/完整目录模板和core.md示例Agent 自定义指令的完整 Prompt 片段可直接复制进 Cline / Continue / Codex CLI 等工具任务状态表tasks.db的建表语句和读写脚本摘要自动压缩的模板和检索脚本search.py。进群之后有问题直接扔群里我白天在晚上也会集中回复。活动时间暂定国庆期间 10 月 1 日到 10 月 7 日假期结束之后我会把收集到的真实反馈和你遇到的问题整理成一篇新的分享发出来到时候参与者的名字和问题场景都会脱敏处理。5.3 我的私人期望与防坑承诺我不是要推销什么收费工具这套方案本身就是开源的、散落在各种配置文件里的。我发起这次招募的真实原因是想知道在我的这套设计之外别人在真实项目里会遇到哪些我没想到的边界。比如有不同类型项目的结构差异有团队协作时多条 Agent 并发写同一个记忆目录的冲突问题还有 Windows 环境下的路径转义问题这些靠我一个人根本测不全。我会承诺三件事第一所有参与者遇到的问题都不会被藏着汇总后公开第二方案保持免费不引入任何你不知道的后台存储第三任何涉及你项目内部代码的内容都不会出现在公开文档里。你也可以选择完全不用自己的业务代码拿一个玩具项目来跑重点是流程能走通。坦白讲长期记忆这块目前没有完美答案我也是靠一次次跑废再重来才攒出这套东西。如果你试过之后发现哪里不对劲那正好是我最需要的地方。按住自己项目的节奏来先把记忆装上再说装歪了也比没有强。