最近朋友圈里讨论 Coding Agent 的声音明显变了：前半年大家还在比谁的提示词写得花哨，最近已经开始聊“长期记忆”了。国庆前后不少团队在限时招募内测，主题几乎都是同一件事——给你手头的编码智能体装上跨会话的长期记忆，让它不再是“关掉窗口就失忆”的临时工。我趁着假期把整套方案从头到尾盘了一遍，也拿手头的几个 Agent 做了实测。这篇文章不打算教你怎么抢内测名额，而是把“长期记忆”这件事的底层逻辑、常见实现载体、我的落地实验和踩坑记录完整写出来。如果你用的刚好是 OpenAI Codex 这类的命令行编码代理，或者别的 AI 编程工具，这套思路基本都能直接搬过去用。
1. Coding Agent 的健忘症：上下文一断，重写两小时
先说最让人崩溃的现象。你花四十分钟和一个编码助手聊清楚了一个模块的拆分方案，接口约束、命名规范、异常处理全部对齐，结果手一抖把终端关了，重新开个会话，它一脸无辜地问你：这个项目是什么技术栈？目标框架是哪一个？之前讨论的方案还存在吗？那一刻你会觉得它不是 AI，是鱼，只有七秒记忆。
这个问题不是单个产品做得不好，而是架构上天然吃亏。大模型本身是无状态的，所有“记忆”都体现在上下文窗口里。窗口一换，前面的对话历史就被清空，模型对项目的理解归零。很多工具虽然会把当前文件、当前选中代码作为上下文传给模型，但那只覆盖“当下”，覆盖不了“过往的决策”。我在过去一年里被这个问题坑了无数次，最典型的有三类场景。
第一类是重构中断后的恢复。一个跨文件重构往往要做几个小时，中途你要去开会、吃饭、处理紧急 bug，等你回来接着干的时候，Agent 已经把上午的思路忘光了。你不得不把已经改完的文件重新贴给它，让它从代码里反推意图，效率大打折扣。第二类是反复校准规则却反复失效。我让 Agent 写代码时统一使用某个内部工具库，不在业务层直接落 SQL，它每次答应的好好的，但换个会话又开始引入新的查询写法，你得像监工一样一遍遍纠偏。第三类是多文件改动的断点续作。一个功能涉及前端页面、接口层、数据模型三层改动，Agent 在单次会话里能处理得很好，但一旦超过上下文上限被截断，后面就跟喝了假酒似的，前面定好的字段名都能给你改回去。
那有人会说，我把项目背景、规范说明、过去的对话记录全塞进新会话开头不就行了？这招我试过，效果很差。问题在于上下文窗口是有限的，你把几万字历史塞进去，留给模型生成代码的余量就少了，费用也成倍上涨。更麻烦的是，一长串没整理过的历史里大多数是噪音，模型会挣扎着在里面找重点，反而容易被角落里的过时结论带偏。你需要的不是“把记忆原样堆进去”，而是“把记忆提炼成结构化的东西，按需调取”——这才是我理解的长期记忆。
所以整个问题的本质可以概括成一句话：大模型天生健忘，但我们可以给它的工作流补上“记忆系统”，让它在新会话里能快速恢复对项目的理解。接下来我从原理层拆一下这套系统该怎么搭。
2. 长期记忆的三层架构：瞬时、短期、长期各存什么
要给 Coding Agent 装记忆，第一件事是分清记忆的层级。拿人做类比特别合适：瞬时记忆是眼睛扫过的那一屏，短期记忆是今天上午开会讨论的结论，长期记忆是你一年前踩过的坑、总结出的规则。AI 的上下文窗口就是瞬时记忆，会话摘要和项目文件里的约定是短期记忆，沉淀在仓库、知识库、个人偏好配置里的内容才是长期记忆。
我把常见实现分层整理成了下面这张表，方便你按需选型：
| 记忆层级 | 对应载体 | 生命周期 | 适合存什么 | 典型毛病 |
|---|---|---|---|---|
| 瞬时记忆 | 上下文窗口、当前会话 | 单次会话 | 当前改动文件、临时结论 | 一关窗口就丢 |
| 短期记忆 | 会话摘要、项目记忆文件 | 天/周级别 | 本周任务、当前架构决策 | 不维护就过期 |
| 长期记忆 | 仓库规范、向量库、个人偏好档 | 月/年级别 | 团队规范、踩坑记录、惯用技术栈 | 不好检索、容易和短期冲突 |
这里有个容易被忽略的原则：记忆不是越多越好，而是越结构化越好、越可检索越好。很多人一开始做反了，想把所有历史对话原封不动的存下来，再用的时候全量喂给模型。结果模型被海量历史淹没，出现两个典型症状：一是注意力涣散，回答变得又长又空；二是在新旧规范之间摇摆，昨天定的事被前天更早的事覆盖。正确的姿势是给记忆分好层，瞬时记忆只放当前任务上下文，短期记忆放“项目当前的状态”，长期记忆放“不变的规则和沉淀”。
“项目当前的状态”是个值得展开的点。我通常把它维护成一份结构化的决策日志，包括日期、背景、决策内容、替代方案、结论这五栏。说白了就是把和人开会时记的纪要转成机器能读的文本。A 方案为什么不用、B 方案为什么最终选中，这些内容看起来跟代码无关，但对 Agent 后续的每个改动都有决定性影响。有了这份决策日志，哪怕 Agent 丢掉了几十次会话的原始聊天记录，它依然能靠一份几百字的摘要快速恢复“上下文感”。
长期记忆的存储位置也很有讲究。传统做法是把规范写在项目的 README 或 docs 里，但问题是 Agent 不会每次主动去读 README，读到了也未必知道该按什么优先级执行。所以更可靠的方式是把规范沉淀到 Agent 约定俗成的记忆文件里，比如 AGENTS.md、CLAUDE.md 这类文件名现在已经被很多工具默认识别，启动会话时自动加载。它的好处是零依赖、随仓库走、能进 code review——改这个文件本身就是一次提交，有历史、可评审、可回滚。
光知道分层还不够，真正动手的时候你会发现，“选什么载体”比“记什么东西”更让人头疼。下一节我把这几个月实测过的四种载体方案展开说。
3. 我给 Agent 配过的记忆载体：四种方案实测对比
记忆架构落地时，我先后试过四种方案，各有各的适用场景。直接说结论：我目前最推荐“记忆文件 + 向量库”的混合模式，但如果你项目不大，只用一个记忆文件也完全够用。下面是详细的实测记录。
方案 A：项目记忆文件。在仓库根目录维护一个 AGENTS.md 或者 CLAUDE.md，把技术栈、目录结构、命名规范、常用命令、架构决策全部写进去。等 Agent 启动时，让它先读这个文件再开始干活。这个方案成本最低，效果最直接，适合中小项目和大多数个人项目。我一开始用的时候踩了个小坑：文件里塞了太多“过程描述”，Agent 读完后反而抓不住重点。后来我把文件精简成“规则 + 命令 + 铁律”三段式，规则用短句子，命令给出可直接复制的块，铁律标注哪些是不能商量的事，效果立刻好了很多。
方案 B：滚动对话摘要。每次会话结束时，让 Agent 或你自己把这次聊出来的关键结论提炼成一段结构化摘要，追加到一个历史记录文件里；下次新会话开始时，只把最近几次的摘要作为上下文前缀喂进去。这个方案的本质是把“原样保留全部对话”变成“保留压缩后的结论”，能在不引入任何外部依赖的情况下实现跨会话记忆。之前用这类方案取代全量历史堆砌，费用省了大约一半，准确率反而更高了。不过它有一个明显短板：摘要的维护完全依赖纪律性，你要是哪天忘了写摘要，记忆链就断了。
方案 C：向量库 + 检索增强（RAG）。把过去的会话记录、评审意见、架构文档全部切块做向量化，存入本地的向量数据库；每次会话开始时，根据当前任务的关键词检索出最相关的内容，拼进提示词。这是信息最全的方案，适合大项目、多人协作者多、旧代码积累深厚的场景。我印象很深的一次是处理一个历史包袱很重的模块，Agent 需要理解三年前定下的兼容性约束，靠纯记忆文件根本写不了那么细，但向量检索能把它从旧设计文档里捞出来。缺点也很明显：需要搭服务、维护索引，检索结果有时不稳定，出了问题不好调试。
方案 D：外部数据库或任务看板。把记忆结构化成记录，存进 SQLite、Notion、或者项目管理工具里，让 Agent 在执行任务前先查询相关条目。这更像“记忆外包”。适合团队场景，因为任务是多人共享的，Agent 只是参与者之一。你可以把需求状态、验收标准放在这里，Agent 每次开工前拉一下当前条目，知道自己该干嘛。坏处是引入了额外系统，Agent 要会调用查询接口，复杂度更高。
四种方案的对比表也放出来，方便大家按自己的情况选型：
| 方案 | 实施成本 | 记忆容量 | 检索能力 | 维护负担 | 适合场景 |
|---|---|---|---|---|---|
| 记忆文件 | 低 | 低 | 无，全量载入 | 低 | 个人项目/中小仓库 |
| 滚动摘要 | 中 | 中 | 弱，靠摘要质量 | 中 | 单会话任务复杂的项目 |
| 向量库RAG | 高 | 高 | 强 | 高 | 大仓库/团队协作 |
| 外部数据库 | 高 | 高 | 强 | 高 | 团队流程化开发 |
为什么我最终选择混合模式而不是只用向量库？核心原因是可解释性。纯粹依赖向量检索时，Agent 说“我根据某条历史做出了某个决策”，你很难快速验证那段历史是不是准确、是不是最新。而记忆文件天生是人可读的，进了 Git，有提交历史、有 diff，出了问题可以直接翻 blame。把规则性和不可妥协的约束放进记忆文件，把模糊的、需要深度检索的历史经验放进向量库，两边互补，既能保证核心约束的确定性，又能保留记忆的广度。
4. 一次完整实验：让 Codex 在三十次会话后还记得我的架构决策
理论讲完了，来个实操复盘。我这次实验用的是 OpenAI 的命令行编码代理 Codex——就是首次运行会打出一段欢迎引导信息、需要你登录账号的那个 CLI 工具。实验对象是一个历史包袱比较重的 Java 服务，需要分三十多次会话完成一个模块的老代码清理和接口重构。实验前我先把它的“记忆系统”搭了起来，目标是验证：第三十次会话时，它到底还能不能准确说出第十二次会话里定下的架构决策。
先看第一步：初始化记忆文件。我在仓库根目录建了一个 AGENTS.md，内容不是随手的项目介绍，而是严格分段的。开头写项目定位，包括它是什么服务、依赖哪些内部中间件；然后是技术栈清单，Java 版本、构建工具、ORM 选型；接着是目录结构说明，标注哪些目录是生成的、哪些是人写的，警告 Agent 不要手动改生成代码；再往下是命令速查，构建命令、测试命令、本地起服务命令；最后是“铁律”区，写清楚哪些事绝对不能做，比如不允许在业务代码里直接拼接 SQL、不允许绕过统一异常处理器。整个文件控制在两百行以内。
第二步是设计“记忆注入脚本”。我做了一个很小的 Python 工具，在每次启动 Codex 前跑一遍，逻辑很简单：读 AGENTS.md 全文，读决策日志里最近若干条记录，再从一个向量库里检索当前任务相关的历史片段，最后把这三部分拼接成一个context.md，通过 Codex 的启动参数注入。核心代码长这样：
import sqlite3 from pathlib import Path def build_context(task_desc: str) -> str: parts = [] # 1. 规则型记忆：直接全量载入 rules = Path("AGENTS.md").read_text(encoding="utf-8") parts.append(f"## 项目契约\n{rules}") # 2. 最近决策：从决策日志取最近5条 conn = sqlite3.connect("memory.db") cur = conn.execute( "SELECT date, decision FROM decisions ORDER BY date DESC LIMIT 5" ) recent = "\n".join(f"- {d}: {c}" for d, c in cur.fetchall()) parts.append(f"## 最近决策\n{recent}") # 3. 向量检索：偷懒型实现，直接用SQLite的like cur = conn.execute( "SELECT snippet FROM chunks WHERE chunk LIKE ? LIMIT 3", (f"%{task_desc[:8]}%",) ) hits = "\n".join(r[0] for r in cur.fetchall()) if hits: parts.append(f"## 相关历史\n{hits}") return "\n\n".join(parts) if __name__ == "__main__": desc = input("描述一下当前任务: ") print(build_context(desc))这只是个最小实现，生产上你会换成真正的向量索引，但思路是一样的：规则全量载入、决策定量取最近、历史按需检索。这么设计的理由很朴素——规则型记忆量小但优先级最高，必须每条都在上下文里；决策日志取最近的，因为太老的可能已经过时；历史片段按需检索，避免无关信息挤占窗口。
第三步是运行中的实时维护。每次会话结束时，我会手动把这次的决策追加到决策表里，更新 AGENTS.md 中受影响的段落。这个动作看起来麻烦，但配合 Git 管理习惯了就还好。我把记忆文件单独放了一个目录，和代码放同一个仓库，每次改动都是一次独立提交。这样做的好处是，如果某天 Agent 基于一条已经被推翻的旧决策干活，你能在 git log 里找到这条决策被修改的完整时间线，定位问题特别快。
实验做到第二十五次会话时，我故意做了一个测试：不告诉它之前讨论过什么，只让它继续处理某个接口的清理工作。它在分析代码时主动提到了一句，“按照我们之前确定的策略，对外接口保持兼容，内部实现切换到新缓存组件，所以这里需要加的是适配层而不是直接改接口签名”。那一刻我确定，长期记忆这套是真正生效了。后来我又验证了一次它是否记得第十六次会话里明确否决过的方案，它也没有重新提那个被否掉的旧方案。
实验里还有个值得记录的细节：记忆注入只是改造了输入，Agent 本身没做任何定制。这意味着只要你有一个支持自定义启动上下文的编码代理，无论它是 Codex 还是其他工具，这套外挂记忆方案都可以平移。我甚至把同样的注入脚本用在了别的轻量代理上，配置一下上下文入口，效果同样成立。很多人一听到给 Agent 装长期记忆，下意识觉得要重新训练模型或等在内部集成，实际上在模型能力完全不变的前提下，靠改造输入侧就能实现八成以上的记忆效果。
5. 装上长期记忆之后，我先替你踩了这四个坑
方案能跑通是一回事，稳不稳定是另一回事。我在这套记忆系统上线后的两周里，陆陆续续踩了四个比较典型的坑，写出来给你们当预演。
坑一：记忆污染。这是最严重也最隐蔽的问题。旧决策没有被标废弃，Agent 在某次检索时捞到了三个月前的一条结论，而且完全不觉得它过时了，照着写了很一段代码。我当时排查了很久才意识到，并不是 Agent 变笨了，而是记忆库里“活规则”和“死规则”混在一起，它分不清该信哪条。解决办法是给每条决策加状态位：active 表示当前有效，deprecated 表示已废弃且写明废弃原因和时间。检索注入的时候，只取 active 状态的内容，deprecated 的除非特别需要否则不进入上下文。
坑二：上下文膨胀。记忆系统上线初期，我为了让 Agent “记得更多”，把注入体积做得很大，结果发现它的短期表现反而变差了：基础代码能力没问题，但总在无关细节上纠结，会反复确认一些本来不该成为重点的约束。原因也简单，上下文窗口里如果 60% 是历史记忆，留给任务本身的注意力就少了；模型处理长文本时对中间段的注意力天然衰减，塞得越多衰减越明显。后面我强制给注入内容设定 token 预算，规则文件控制在 2000 token 内，最近决策只取 5 条，向量检索结果不超过 3 段。宁可记忆少一点，也要保证任务本身处在注意力最集中的位置。
坑三：指令优先级冲突。AGENTS.md 里的规则、用户临时输入的指令、系统层提示词这三者有冲突时，Agent 会不知所措。我遇到一次最典型的情况：我在某个会话里临时跟 Agent 说“这次直接改接口签名就行”，但记忆文件里明确写着“对外接口保持兼容”，Agent 犹豫了一阵，最后还是选了记忆中更长期的规则。事后想想这个行为本身是合理的，但它在某些场景下会违背你的临时意图。解决办法是给记忆分层时定一套优先级规则，通常长期契约优先于临时指令，但如果临时指令里出现“本次例外”这样的明确信号，则临时指令优先。这个规则本身也要写进记忆文件，让 Agent 遇到冲突时有据可依。
坑四：敏感信息进记忆。记忆系统和代码仓库一样，会沉淀大量历史信息。我最初向量化旧文档时，把一段含有内部连接串和密钥的配置也切了进去，虽然只是本地测试环境，但这个做法本身是高风险行为。你得在记忆写入环节加一道过滤，凡是字段名形似密钥、Token、密码的，一律跳过；记忆文件进 Git 之前，也要用扫描工具过一遍，防止把不该提交的凭据带进去。
如果你们项目想复现这套方案，我建议把排查思路固化成一个固定动作：发现 Agent 行为异常之后，不要急着改提示词，先看注入上下文里实际有什么。打开记忆脚本生成的 context 文件，逐段检查是规则出了问题、决策过期了、还是向量检索捞错了内容。这个“先看输入再看模型”的顺序很重要，因为绝大多数记忆故障其实都发生在输入侧，模型本身是稳定复现的。注意，我这里是给出一条排查链路，而不是让你们陷入玄学调试——顺序对了，定位问题基本就是十分钟的事。
6. 把长期记忆从单人玩法变成团队基建
个人项目里把记忆系统跑通只是第一步，真正有价值的是把它推广成团队基建。这件事我在第六节单独聊，因为它牵扯的不只是技术方案，还有协作习惯。
先说仓库级共享记忆。AGENTS.md 是跟着代码仓库走的，这意味着它天然适合团队共享。团队可以把公共约定、部署流程、测试要求、Code Review 红线都写进去，所有成员和所有 Agent 共用同一份“团队契约”。我见过一个效率提升很明显的例子：团队把“提交前必须跑某个内部静态检查”“测试覆盖率不得低于 80%”“错误码统一走公司内部规范”写进记忆文件后，新入职同事和 Agent 的行为模式立刻统一了，Review 时因为“不知道有这规矩”而发生的返工明显减少。要注意的是，团队级记忆文件的维护不能靠某一个人，得有明确的 owner，否则过两个迭代就变成一堆过时规则的垃圾堆。
再说个人偏好记忆的迁移。我平时除了用 Codex 这类全功能代理，也会折腾一些更轻量的个人编码代理，它们各有各的弱智点，但只要你把记忆外挂到统一格式里，换工具的成本就低很多。我把个人层面的偏好——比如编辑器缩进习惯、提交信息风格、喜欢哪种程度的代码注释——单独记成一份 profile 文件，不随项目走，不随工具走。换一个新代理时，只要让它先读这份 profile，它就能快速伪装成一个懂你习惯的老搭档。这不只是省去重新调教的时间，更是让你在试新工具时心态更轻松，反正核心记忆在自己手里。
最后是工作流记忆。我最近在尝试把非代码类的团队节奏也写进记忆，比如“每周一更新依赖”“发版前需要冻结主分支”“每周三下午做技术分享”。预期效果是让 Agent 不只是被动执行需求，还能在合适的节点主动提醒相关事项。虽然现在还做不到让 Agent 自动挂个定时器，但通过会话启动时检查“今天该干什么”这种简单机制，已经可以把一部分流程化管理成本转移到 Agent 身上。这个方向目前还比较糙，但值得团队尝试。
如果你想把这套东西落到自己的项目里，我给的建议是先小后大。不要一开始就搭向量库和注入脚本，先在仓库里建一个几十行的 AGENTS.md，跑两个迭代，感受一下 Agent 的表现变化。确认需求真实存在、方向没问题之后，再把滚动摘要和检索加上去。我见过太多人一上来就整全套，结果三天后维护负担超过收益，整套方案被弃用。渐进式落地，看起来慢，实际上是能长期跑下去的唯一姿势。
这趟假期实测下来，我最深的体会是：给 Coding Agent 装长期记忆，技术上并没有多神秘，本质就是给无状态的大模型配一个有状态的输入层。但价值上限比想象中高得多——它让 Agent 记住的不只是代码，更是“我们为什么这样写代码”的决策过程。这些东西原本只存在我们脑子里，现在终于有机会沉淀成可检索、可复用、可交接的资产了。
