记忆系统：Agent 的经验本

本章摘要：

记忆系统是 Agent 自动积累的"经验本"，与 AGENTS.md 互补——AGENTS.md 是静态规矩，记忆是跨会话积累的经验。记忆按类型（用户/反馈/项目/参考）分类，按相关性检索注入。强制记录 Why 和 How to apply——知道为什么才能在未来判断边界情况。

AGENTS.md 是你主动写给 Agent 的指令。但指令是静态的：你只能预先写好，没人能把每件小事都写进 AGENTS.md。你的偏好、临时的团队决策、某个需要特殊处理的遗留接口——这些不成文的规矩，做错了照样出问题。

记忆系统填补了这个空白。它让 Agent 在对话中自动积累经验，跨会话持续演进。

两套系统对比

	AGENTS.md	自动记忆
谁编写	你	Agent 自己
包含内容	指令和规则	学习和模式
范围	项目、用户或组织	每个工作树，跨工作树共享
加载方式	全量拼接	按相关性检索，非全量

注：此处的工作树指的是 git worktree，简单讲就是复制当前工作目录去完成一个新的任务，互不打扰。有兴趣的话可以自行搜索。

简单说：AGENTS.md 是你写给 Agent 的规矩，记忆是 Agent 自己做的笔记。这两种加载模式的根本差异在于：AGENTS.md 是"普适规矩"、记忆是"具体经验"。规矩可以预先全部加载（量小、稳定），经验必须按需检索（量大、动态）。

记忆的类型与组织方式

记忆文件结构

以 Claude Code 为例，所有记忆位于同一目录下，有一个固定的索引文件。

~/.claude/projects/{项目标识}/memory/
├── MEMORY.md              ← 索引文件
├── user_profile.md        ← 用户记忆
├── feedback_meeting.md    ← 反馈记忆
├── project_launch.md      ← 项目记忆
└── reference_brand.md     ← 参考记忆

索引文件在会话启动时加载到上下文，提供记忆的概览；具体记忆文件是对话过程中按需加载。

注：除了 MEMORY.md 以外，其他文件名称不定，并不一定按照示例的代码进行命名

四种记忆类型 & MEMORY.md 索引

用户记忆（user）——关于你的角色、技术背景、工作偏好。

反馈记忆（feedback）——你给过的工作方式指导，纠正和确认都记录。核心理念：记录失败和成功同样重要。 只记纠正会避免错误，但会逐渐偏离已验证的正确做法。必须包含 Why（记录原因）和 How to apply（记录应用方式）。知道为什么才能判断边界情况。

项目记忆（project）：记录当前项目的工作、决策与约束。项目记忆常记录一些对时间敏感的信息（此类记忆随时会变），提示词会建议 Agent 在记录项目记忆时标注具体日期以明晰时效。项目记忆也会同样要求记录 Why 和 How to apply。

参考记忆（reference）——外部系统的位置和用途。通常团队级。

MEMORY.md——索引文件，会话启动时加载到系统提示，限制：200 行、25KB），示例：

- [用户背景](user_profile.md) — Tesla CEO，偏好英文和简洁风格
- [会议纪要 24h 内发出](feedback_meeting.md) — 会议纪要必须 24 小时内发出，三段式格式
- [春季发布会物料冻结](project_launch.md) — 2026-06-30 春季新品发布会物料冻结
- [品牌视觉规范](reference_brand.md) — 公司共享盘「品牌中心」目录与 Figma 链接

记忆文件格式 & 示例

每个记忆文件有 frontmatter 标明类型：

字段	作用
name	标识符，用于去重和内部引用
description	一行摘要，会用于记忆检索时的匹配
type	记忆类型，决定可见性和默认作用域

user_profile.md（用户记忆）：

---
name: user-profile
description: Tesla CEO，偏好英文和简洁风格
type: user
---
Elon Musk，Tesla CEO。偏好英文交流，喜欢直接简洁的回答风格，不想要冗长的解释。

feedback_meeting.md（反馈记忆）：

---
name: meeting-style
description: 会议纪要必须 24 小时内发出
type: feedback
---
会议纪要必须 24 小时内发出，格式用「决议 / 待办 / 风险」三段式。
**Why:** 之前拖到周五发纪要，周一大家已经忘了会上拍板的事，执行节奏全乱
**How to apply:** 任何会议结束后立即起草纪要，发出去之前确认每条决议都标了负责人

project_launch.md（项目记忆）：

---
name: product-launch
description: 2026-06-30 春季新品发布会，所有营销物料冻结
type: project
---
2026-06-30 春季新品发布会，即日起所有对外宣传物料（海报、推文、详情页）冻结，不再接受改动。
**Why:** 发布会前一周改文案风险极高，印刷品、渠道投放都已定型
**How to apply:** 收到物料修改需求时一律先拒绝，并引导到发布会之后再排期

reference_brand.md（参考记忆）：

---
name: brand-guidelines
description: 品牌视觉规范与素材库
type: reference
---
品牌视觉规范与官方素材库在公司共享盘的「品牌中心」目录下，Figma 文件链接在 README 第一行。
**Why:** 每次设计稿返工多是因为没用最新 logo 或色值，对外印象很受影响
**How to apply:** 任何对外物料（PPT、海报、推送）动笔前先打开这份规范确认字体、配色、logo 用法

什么该记、什么不该记

判断标准："这条信息是不是可以通过读取代码仓或本地文件来获取"——人的偏好、决策背景、外部链接是 Agent 无法实时获取的，需要被记录成记忆。

记忆记录的核心：Why 和 How to apply

强制记录 Why 和 How to apply 而非 What——知道为什么才能在未来判断边界情况，单纯记 What 会让记忆沦为纠错清单。

每条记忆应该回答两个问题：

• Why：这条信息为什么重要？当时发生了什么？
• How to apply：未来在什么情况下该用这条信息？

Subagent 记忆

Subagent 有自己独立的记忆作用域，与主 Agent 的记忆不共享。这允许不同角色的 Subagent 积累各自的专业知识。一般来说，Subagent 不会主动写入记忆，须经 Agent 定义文件的提示词来引导 Subagent 主动写入记忆。

Subagent 记忆可按角色放在不同位置（如用户级、项目级或本地级，由 memory 配置控制），记忆的格式与主 Agent 一致。

记忆的生命周期

记忆贯穿 Agent Loop 的每个阶段：

启动时：加载索引

会话启动时，Agent 把记忆索引文件作为背景知识注入到系统提示词。索引列出所有记忆的标题和摘要——Agent 借此知道"我有这些笔记可用"。

对话进行中：按需检索

每轮对话开始时，系统把除 MEMORY.md 之外的所有记忆打包成 [type] filename (时间): description 格式的清单（这里仅用 description 而非全文），单独发起一次大模型 API 调用，让模型从清单中选当前 query 最相关的记忆（≤ 5 条）。 然后系统将其对应的 .md 记忆文件的全文注入到用户上下文的附件中（<system-reminder>，不同于 AGENTS.md 放在最开始，此处的附件是加入到用户消息末尾的，详见：上下文：Agent 的视野）。

检索的核心思想是"轻量索引 + 按需加载"——索引很小、可见；具体记忆按需调出，避免上下文爆炸。

记忆附带新鲜度标签：

记忆年龄	显示
当天	无警告
昨天	Memory (saved yesterday)
2 天前	Memory (saved 2 days ago)
超过 1 天	附加失活警告

这条记忆已保存 N 天。记忆是时间点的观察，不是实时状态——关于代码行为或文件位置的声明可能已过时。在断言为事实前请验证当前代码。

对话结束后：自动提取

对话结束后，Agent 在后台自动判断本轮对话是否需要提炼为新记忆。这个过程是异步的——是由一个后台的仅能读取项目文件和写入记忆文件的 Subagent 完成的，用户无需等待，下次对话即可使用新记忆。

深度整合记忆：AutoDream

本文介绍的即时提取是"随手记笔记"——每轮对话后即时提取。Agent 还有一套更深层的记忆整合机制——AutoDream，在积累足够素材后像人类睡眠一样批量整理记忆。详见 AutoDream：Agent 的睡眠记忆整理。