Agent 记忆(Memory)
上下文窗口是 Agent 的短期记忆,装不下也留不久;长期记忆要把关键信息写进外部存储再按需检索。CLAUDE.md / AGENTS.md 是最朴素的长期记忆,也是当前工程上最有效的方案。
发布 2026-08-30更新 2026-11-15核实 2026-11-15为什么 Agent 需要记忆
把 Agent 当实习生看就懂了:实习生入职第一天能干活,是因为记住了团队约定(用 pnpm 不用 npm、提交前跑 lint)。而一个没有记忆的 Agent,每次会话都像失忆重来——你反复教它同样的事,它反复犯同样的错。
更硬的约束来自上下文窗口本身:
- 容量有限:Context Rot 证明输入一长质量就掉,窗口远未满就已退化
- 生命周期短:会话结束、compaction 压缩之后,早期内容就没了
- 按 token 计费:每次都重读全部历史,账单撑不住
记忆系统的本质:把「每次都要重学」的东西挪到窗口外面,按需取回。
两层记忆:短期与长期
| 短期记忆 | 长期记忆 | |
|---|---|---|
| 载体 | 上下文窗口 | 外部存储(文件/向量库/数据库) |
| 生命周期 | 单次会话内 | 跨会话、跨项目 |
| 容量 | 几十~几百 K token | 无上限 |
| 读写 | 模型原生 | 需要 Agent 主动调用工具 |
| 典型内容 | 当前任务步骤、刚读过的文件 | 项目约定、踩过的坑、用户偏好 |
学术界的分层更细(受认知科学启发,MemGPT/Letta 一系把这套发扬光大):
- 工作记忆:当前上下文里的活跃内容
- 情景记忆(episodic):过去发生的事件流水——「上次重构是怎么失败的」
- 语义记忆(semantic):沉淀下来的事实与偏好——「这个项目用 pnpm」
- 程序记忆(procedural):固化成规则的操作流程——「提交前必须跑测试」
工程上不必照搬四层,但**「事件流 → 提炼 → 沉淀」**这个方向是共通的:先记录发生了什么,再总结成可复用的结论,最后固化到规则文件里。
工程实现的三条路线
1. 记忆文件:CLAUDE.md / AGENTS.md(最朴素,最有效)
把项目约定写成 Markdown 放在仓库根目录,Agent 每次启动自动读取:
它同时解决两件事:人也是读者(新人 onboarding 看同一份文件),版本可管理(记忆跟着 git 走,可 review、可回滚)。这比任何智能记忆系统都可靠——因为它简单到不会出错。
写法要点:只写 Agent 会反复用到的稳定约定(构建命令、目录结构、禁区),别写成需求文档。详见 AGENTS.md 详解。
2. 向量检索:记忆库 + RAG
把历史会话、踩坑记录切块后存进向量库(embedding),新任务开始时先检索相关记忆注入上下文:
- 优点:能记住海量历史,按语义召回
- 风险:检索质量决定一切——召回错了等于给 Agent 喂错误记忆,比没有记忆更糟
适合多项目、长周期积累的个人助手型 Agent;单仓库编程场景下,记忆文件通常够用。
3. 内置记忆系统:工具厂商的尝试
MiMo Code 把记忆系统做进了 Agent 本体——跨会话记住项目上下文与用户习惯。方向正确,但注意两点:记忆存在哪(本地 or 云端)决定隐私边界;记忆能否查看、编辑、清除决定可控性。闭源记忆系统在这两点上天然存疑,选型时要看厂商的披露。
2026-11 研究进展:把整个文档库压成 16 个 memory token
前面三条工程路线有一个共同前提:记忆就是文本,检索出来拼进 prompt。2026 年 10 月的一篇论文给了另一条路——把记忆压到输入嵌入空间里,不落成可读文本。
这就是斯坦福团队(作者含 Jure Leskovec)的 Memorilla(arXiv 2610.21375,2026-10-15 首发,11-03 更新到 v3)。做法分两步:
- 把文档集合(用户聊天记录、书稿章节)一次性编码成可复用嵌入,不用每次查询都重读原文;
- 学习「为当前问题检索什么、放在哪」,把与查询相关的信息写进固定数量的 memory token,直接喂给一个冻结的 LLM。
关键数字(论文口径):
| 指标 | 结果 |
|---|---|
| 记忆预算 | 固定 16 个 memory token |
| 八个基准(个性化 / 长文档 / 知识密集问答) | 在 5 个上优于 Mem0、MemoRAG 等基线 |
| FactKG 准确率 | 84.33%,高于全上下文推理的 80.43%,而表示源文档用的 token 少 108 倍 |
| TextWorld 具身任务 | 平均成功率从全历史上下文学习的 18.6% 提升到 24.2%,并减少在已探索房间之间来回游荡 |
它为什么值得单独记
因为它改的是记忆的载体,不是检索策略。
RAG 路线里,记忆的最小单位是「一段文本」,所以你能 grep、能人工复核、能算出「这段记忆是从哪份文件来的」。Memorilla 这类做法把记忆压成向量槽位:省 token、省延迟、还能让冻结的模型「持续学习」,代价是这些槽位对人不可读——你无法审计模型到底记住了什么。
这跟本页前面讲的「记忆污染」是一对天然矛盾:
- 文本记忆:可审计,但占 token、容易过时、容易被注入污染;
- 潜空间记忆:省资源、抗噪,但出了问题你只能看行为,看不到「它记错了哪一条」。
所以短期内它更像「工作记忆的压缩器」,而不是「长期记忆的替代品」。真正需要追责的场景(医疗、金融、合规),可读的那一层还得留着。
一处待核实:多篇二手报道称该工作「已开源」,但本轮未找到对应的公开仓库(arXiv 摘要未给出代码链接),文中不将其记为开源。论文数据亦为作者自测,无第三方复现。
记忆的坑:污染与过时
记忆系统不是纯增益,它引入两类新故障:
- 记忆污染:早期学到的错误约定(比如某个已废弃的构建命令)被反复注入,Agent 把错误越滚越扎实。解法:记忆要可编辑、可清除,且标注来源与时间
- 记忆过时:项目演进后旧约定失效(monorepo 拆分了、框架升级了),记忆文件没跟着更新。解法:把记忆文件纳入维护流程,lastVerified 思维同样适用于记忆
一个实用习惯:让 Agent 在每次踩坑后主动提议把教训写进 AGENTS.md——人审核后合入。记忆的写入路径有人把关,污染速度就可控。
和上下文工程的关系
记忆是上下文工程的子问题:后者管「这一次请求的窗口里放什么」,前者管「跨请求的沉淀与召回」。完整链路是:
踩坑/约定 → 沉淀进记忆(AGENTS.md / 向量库) → 下次任务按需召回注入 → 窗口内只保留当前任务的高信噪比内容
三层各司其职,缺哪层都会退化:没记忆则反复重学,没检索则记了找不到,没上下文工程则找到了也淹没在噪声里。
常见误区
- 「上下文窗口够大就不需要记忆」:错。窗口再大也跨不了会话,且长输入直接触发 Context Rot
- 「记忆文件是给模型写的文档」:错。AGENTS.md 首先写给人看——它是一份恰好能被机器消费的工程约定
- 「记忆越多越好」:错。污染与过时的记忆是负资产,宁缺毋滥,定期清理
- 「向量库是记忆的标准答案」:过度设计。单项目编程场景,一个 Markdown 文件解决 80% 的问题
记忆 vs 压缩:一个必须先看懂的冲突
这是 2026 年长会话场景下最容易被忽略的一组矛盾,也是本页最实用的一节。
| 记忆(本页主题) | 压缩(上下文压缩) | |
|---|---|---|
| 目的 | 让 agent 记住该记住的 | 让会话装得下 |
| 谁决定留什么 | 你(写进文件)/ agent(写入策略) | 压缩算法,多数情况下你不参与 |
| 时机 | 随时、可预期 | 可能在你不在场时触发 |
| 可逆性 | 文件在,就在 | 有损,不可回滚 |
| 长任务下的风险 | 记忆污染、记忆过时 | 把你还没落盘的进度压掉 |
结论:凡是「你还指望它原样留着」的东西,都不要只存在于会话里——必须落盘。 这条规则在自动压缩时代从「建议」升级成了「硬要求」。
具体到 Claude Code:v2.1.299 起 200K+ token 会话空闲约 54 分钟会自动压缩(见 Claude Code 工具卡),v2.1.302 起 /config 新增 Idle compaction 行可关闭。依赖会话内原始产出的场景应当关掉它,并把进度写进本页「记忆文件」那一节说的 CLAUDE.md / NOTES.md。
怎么验证「记忆真的被读到了」
写记忆文件最常见的失败不是写错,而是写了但 agent 没读。三种验证方法,从快到慢:
| 方法 | 怎么做 | 适用 |
|---|---|---|
| 反问法(最快) | 直接问:「你现在的指令里,有哪些来自项目记忆文件?」让它复述 | 每次改完记忆文件后 |
| 对抗法 | 故意问一个与记忆相反的问题,看它是否纠正你 | 验证关键约束是否生效 |
| 留痕法 | 在记忆文件里写一条可观测的动作指令(如「每次回答先输出一行 [MEMO-OK]」),看是否出现 | 批量排查、CI 化检查 |
第三种方法会污染输出,只在排查阶段临时使用,验证完记得删掉。
记忆系统的四个高阶误区
误区一:把记忆文件当成「什么都往里塞」的垃圾桶。 记忆文件每次会话都会加载,写得越长,每一轮的输入成本越高、有效信息密度越低。一条被 50 条无关内容包围的约束,等效于没有约束。记忆文件的优化目标是「短且必读」,不是「全面」。
误区二:以为「agent 自己会写记忆」就等于「记忆是对的」。 内置记忆系统写入的是它认为重要的,不是你认为重要的。它会把一次碰巧成功的做法固化成技能,也会把一次误判固化成「经验」。自动沉淀的记忆必须人工抽检——错误一旦被固化,会稳定地重复。
误区三:向量检索记得越多越好。 检索式记忆的失败模式是相似但错误的命中:语义相近 ≠ 语义相关。记忆库越大,这类噪声命中越多。检索记忆要做去重与过期清理,不做只会越用越差。
误区四:跨会话记忆可以替代版本控制。 不能。记忆会过时(本页「记忆的坑」一节),而代码与设计决策需要可追溯。记忆负责「下次别再踩这个坑」,Git 负责「这个决定是谁在什么时候做的」——两者的职责不重叠,别用前者偷懒替代后者。
2026-10-18 更新:本次复核了什么
- 新增「记忆 vs 压缩」与「怎么验证记忆被读到」两节,理由是长会话与自动压缩已成为 2026 年的默认形态,而记忆是本页主题里最先被压缩机制影响的一环。
- Claude Code 侧的事实依据:当前最新 v2.1.302(官方 CHANGELOG 一手核对,2026-10-18)。其中与记忆直接相关的是空闲自动压缩(v2.1.299 引入、v2.1.302 起
/config可关)与 fork 子代理默认开启(v2.1.302,扩大到claude -p/ Agent SDK / 桌面端 / VS Code)。官方 CHANGELOG 版本标题下不含日期,2026-10-16T20:53 UTC为 GitHub Releases tag 时间戳,非厂商公布发布日。 - 🔄 2026-11-04 订正(只改数字 + 一条与记忆主题直接相关的新事实):上一条写于 2026-11-03 的「Claude Code 最新 stable 为
v2.1.316」已过时;截至本次复核,最新 stable 为v2.1.317(tag2026-11-03T01:25:46Z,prerelease: false)。失效的只是「当前最新」这个数字——v2.1.299 空闲自动压缩、v2.1.302 起/config可关、fork 子代理默认开启、v2.1.311 起 standard-context 会话超 200K 改为自动压缩续跑四条结论描述的是行为,仍然成立。⭐ 新事实(与记忆主题直接相关):v2.1.317撤掉了 Read 工具的「file unchanged since your last Read」占位符,重复读取未改动文件重新返回全文——这是把此前为省 token 做的优化回退了。对上下文管理的含义:同一文件被反复回读的会话,上下文增长更快,自动压缩会更早触发;此前按「重复 Read 几乎不占上下文」做的窗口估算需要上调。详见 v2.1.317 资讯。 - 未复核项:各厂商内置记忆系统(文中「工具厂商的尝试」一节)的当前实现细节,本次未逐项核对,沿用此前口径。
- 🆕 2026-11-15 增补(研究侧一条):新增「把整个文档库压成 16 个 memory token」一节,依据 Memorilla(arXiv 2610.21375 v3,2026-10-15 首发 / 11-03 更新,作者含 Jure Leskovec)。选它的理由是它换的是记忆载体(向量槽位而非文本块),直接冲击本页反复强调的「记忆可审计」前提。论文数据为作者自测;二手报道称「已开源」但本轮未找到公开仓库,未按开源陈述。原「未复核项」不变。
相关阅读
相关工具
相关模型
Aider vs Claude Code:终端 AI 编程双雄怎么选
Aider vs Claude Code 2026 选型对比:开源 BYOK 多模型 vs Anthropic 订阅长任务 Agent,从编程能力、多模型支持、价格、Git 集成、国内可用性和适合人群判断,帮你选对终端 AI 编程工具。
Claude Code vs Cline:CLI AI Agent 怎么选?2026 对比
Claude Code vs Cline 2026 选型对比:Anthropic 官方闭源 CLI Agent vs Apache-2.0 开源 VS Code 插件。从模型绑定、工作流、MCP 支持、价格、隐私和适合人群 6 个维度帮你选对 CLI AI 编程工具。
Claude Code vs Codex CLI:终端 AI Agent 双雄对比
Claude Code vs Codex CLI 2026 选型对比:Anthropic 与 OpenAI 两大官方终端 Agent 的模型、长任务、MCP 生态、Windows 支持、订阅打包价格和国内可用性全方位对比,帮你判断该用哪个终端 AI Agent,以及能不能两个一起用。
Claude Code vs Crush:Anthropic 官方 vs 多模型 TUI(2026 实测选型)
Claude Code vs Crush 怎么选:Anthropic 官方 CLI(长任务最稳),对上 Charmbracelet 开源 TUI(多模型切换 + LSP)。按模型、长任务、价格对比。
Cursor vs Claude Code:什么时候用哪个?(2026 实测选型)
Cursor 和 Claude Code 到底怎么选?一句话结论 + 决策树 + 价格实测 + 国内可用性对比。GUI 派选 Cursor,终端长任务派选 Claude Code,最优解其实是共存。
Devin vs Claude Code:AI 编程 Agent 怎么选?异步自主 vs 终端同步对比
Devin vs Claude Code 2026 选型对比:Cognition 异步自主 Cloud Agent vs Anthropic 终端同步 CLI Agent,从形态、工作模式、长任务能力、并发、价格、中文支持和适合人群 8 个维度判断,帮你选对 AI 编程 Agent。