跳到主内容
概念Agent 记忆Memory长期记忆向量库CLAUDE.mdAGENTS.md上下文工程

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 每次启动自动读取:

  • CLAUDE.md:Claude Code 的记忆文件,写技术栈、命令、代码风格
  • AGENTS.md:2026 年已成跨工具的事实标准,Codex、Gemini CLI、OpenCode 等都认

它同时解决两件事:人也是读者(新人 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)。做法分两步:

  1. 把文档集合(用户聊天记录、书稿章节)一次性编码成可复用嵌入,不用每次查询都重读原文;
  2. 学习「为当前问题检索什么、放在哪」,把与查询相关的信息写进固定数量的 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 摘要未给出代码链接),文中不将其记为开源。论文数据亦为作者自测,无第三方复现。

记忆的坑:污染与过时

记忆系统不是纯增益,它引入两类新故障:

  1. 记忆污染:早期学到的错误约定(比如某个已废弃的构建命令)被反复注入,Agent 把错误越滚越扎实。解法:记忆要可编辑、可清除,且标注来源与时间
  2. 记忆过时:项目演进后旧约定失效(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(tag 2026-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。