我的 ~/.agent/memory.md 曾经涨到四百八十行。每次开新会话,它被完整注入上下文,前三千 token 全是历史偏好:「用户喜欢用 pnpm」「用户不喜欢 console.log」「用户在 2025 年 3 月说过想学 Rust」。最后那条对应的是一个早就结束的 side project。

Agent 每次仍然认真地读完,然后在我问 Go 服务怎么排查内存泄漏时,突然建议我「可以考虑用 Rust 重写」。

那一刻我意识到,记忆系统的难点从来不是「怎么记住」。存下来太容易了,写个文件、追加一行就行。难的是怎么有节制地忘:哪些该进长期记忆、哪些只配留在当次会话、哪些进来之后必须能被删掉。一个只增不减的记忆文件,用不了多久就会从「助手了解我」变成「助手活在过去」。

一、三类记忆,三种失效方式

「记忆」是个被用滥的词。真正落到工程上,它至少分三类,生命周期和失效方式完全不同。混在一起管,必然出问题。

类型 典型内容 生命周期 典型失效方式
用户偏好 回答语言、注释风格、包管理器、提交习惯、禁忌 长期,缓慢变化 偏好变了没人更新;把一次性要求固化成永久规则
项目事实 启动命令、目录约定、测试环境、依赖版本、代码生成规则 与项目同生命周期 重构、迁移、升级后过期;项目归档后仍被注入
任务经验 某类报错的排查路径、试过但失败的方案、第三方库的坑 中期,任务结束后可归档 环境变化后不再成立;从小样本过度泛化

用户偏好回答的是「怎么和我合作」。它跨项目生效,变化很慢,但一旦错了,影响面最大。把「这次先用 Python 写个脚本」记成「用户偏好 Python」,下次写服务端也给你 Python,这就是把一次性指令误当偏好。

项目事实回答的是「这个仓库怎么运转」。它只在一个项目内有效,生命周期跟着项目走。项目重构之后,旧的目录约定、旧的启动命令全部作废,但记忆文件不会自动知道。这类记忆最怕「写完就不管」,因为它的过期是静默的。

任务经验回答的是「这类问题以前怎么解决的」。它最有价值,也最容易污染。一次偶然的成功会被记成通用规律,换了环境就不成立;一次失败会被记成「这个库不能用」,其实只是版本不兼容。

三类记忆应该分开放。偏好放全局,项目事实放仓库内的 AGENTS.md 或同类文件,经验放带标签的经验库。混在一个文件里的直接后果是:项目 A 的约定泄漏到项目 B,全局偏好被某个项目的细节覆盖。

我踩过一次很典型的泄漏。项目 A 是个小工具,当时为了避免状态混乱,定了一条「不要用包级全局变量」。这条本来是项目级约定,却被自动记忆写进了全局偏好。后来在项目 B 里,那个服务的架构大量依赖包级注册表,Agent 每次改代码都要「纠正」一遍,建议我把注册表改成依赖注入。它没有错,只是把 A 的约束带到了 B。修的时候不难,删掉一条就行;难的是发现,因为它的表现是「Agent 有点固执」,不像一个明确的 bug。

二、写入门槛:四条测试

Auto Memory 最诱人的地方是「自动」。最危险的地方也是「自动」。模型每轮都能判断「这条信息值得记」,而它的判断标准和你不一样:它倾向于多记,因为记下来显得周到;它不承担记忆膨胀的代价,承担代价的是下一次会话的上下文预算。

所以写入必须有一道门槛。我一般用四条测试,全部通过才允许进长期记忆。

可复用。 下次还会遇到。只对当前任务成立的信息,不该进长期记忆。「这次部署到 staging-3」是一次性事实,「部署走跳板机」才是可复用约定。

稳定。 短期内不会变。价格、版本号、负责人、临时地址都不稳定,记了就要配过期时间,否则一定过期。「这个项目用 Go 1.22」半年后大概率是错的。

非显而易见。 模型自己推不出来,或者推出来容易错。「Python 用缩进表示层级」不用记,模型知道;「这个仓库的 internal/gen/ 是生成代码,禁止手改」必须记,模型看目录名猜不到。

有代价。 不知道会导致实际的返工、故障或时间浪费。「提交信息用中文」记不记都行;「迁移脚本必须先在小数据集上跑,否则会锁表」不记会出事。

后两条是最强的过滤器。很多团队的记忆文件之所以膨胀,是因为只用了前两条:可复用、稳定,但全是模型本来就知道的常识,或者记不记都无所谓的偏好。

该记 不该记
这个仓库用 pnpm,不要生成 lock 以外的包管理文件 今天处理的是订单模块
单测命令是 make test-unit,全量测试要连测试库 刚才那个临时文件在 /tmp/xxx
用户要求注释用中文,标识符用英文 用户这次说「先这样吧」
生成代码目录禁止手改,改 schema 后重新生成 模型的推断「这个函数应该没有被调用」
上次全量迁移锁表四十分钟,必须先小批量 公开文档里能查到的框架用法
这个项目的 e2e 依赖 UTC 时区 密钥、token、任何凭证
客户要求所有导出文件带水印 用户随口一句「这个库有点慢」

写进去的每一条,都要能回答三个问题:它解决什么问题、什么时候该失效、凭什么相信它。答不上来,就不该进长期记忆。

写入方式也值得设计。全自动写入省事,但污染快;全手动确认准确,但没人愿意做。比较可行的是自动起草、批量确认:Agent 把候选记忆写进一个待审区,带来源和理由,用户每周花两分钟过一遍。这和 git 的暂存区是一个思路,写入和生效分开,中间留一道人工闸门。

三、存储形态:为什么先选文件

记忆存哪里,有三种常见选择。

形态 可读性 检索方式 更新与删除 适合规模
Markdown 文件 高,可直接阅读和 diff 全文、标题、人工浏览 简单,改一行即可 几十到几百条
结构化 JSON 中,需要工具查看 按字段过滤、按 key 查找 需要处理合并与冲突 几百到几千条
向量库 低,内容不可直接审阅 语义相似度 更新、删除、重建都麻烦 上千条非结构化经验

多数 Agent 产品先选文件,不是因为文件先进,而是因为在这个阶段,瓶颈是信任,不是召回。

记忆量小的时候,几十条偏好加十几条项目约定,全量注入也就一两千 token,根本不需要检索。真正的问题是:这条记忆对不对、从哪来的、什么时候写的、能不能改。文件天然满足这些:打开就能看,git 能 diff,改错了能回滚,用户可以直接编辑。

向量库把「为什么召回这条」变成了黑盒。记忆错的时候,你连它为什么被想起来都不知道,更别说修。而记忆错了比没有记忆更糟:没有记忆,模型会问你;记忆错了,模型会非常自信地按错的来。

规模上来之后,可以分层。我的做法是一个 MEMORY.md 做索引,每条一行,控制在八十行以内;详情放 memory/ 目录下的小文件,按主题拆分。启动时只注入索引,模型判断相关了再读详情文件。这就是 /AI/00/ 里讲过的渐进式披露,用在记忆上同样成立。

结构化 JSON 适合需要程序处理的场景:按 scope 过滤、按 expires_at 清理、按 confidence 排序。代价是人读起来费劲,手改容易破坏格式,多人协作时合并冲突很难解。如果团队里没人愿意写脚本维护,JSON 的好处很快会被维护成本吃掉。

还有一种常见组合是「文件做事实来源,索引做加速」。Markdown 是唯一可编辑的真相,向量库或全文索引只是它的投影,随时可以重建。这样即使索引坏了、换模型了、迁移库了,记忆本身不丢。反过来,如果记忆只存在向量库里,迁移一次就要重新嵌入,原文还可能因为切片而丢失。把「存储」和「检索」分开,是这套设计里最值得坚持的一条。

文件方案也不是没有代价。它没有并发控制,两个进程同时写会互相覆盖;它没有事务,写到一半崩溃会留下半条记录。规避办法很土:写入用追加而不是重写,每条记忆独立成行,定期整理时再合并。追加写天然避免了大部分覆盖问题,代价是文件会变长,需要配合前面的上限和清理机制。

四、召回:全量、按需与分层

存下来之后,下一个问题是「什么时候取出来、取多少」。

策略 每轮成本 召回质量 适合
启动时全量注入 固定 N token,随记忆量线性增长 不会漏,但不相关的内容会干扰 记忆小于两千 token
按需检索 低,只取相关几条 依赖检索质量,会漏 经验库很大
分层:摘要常驻 + 细节按需 中等,摘要几百 token 平衡,兼顾稳定与覆盖 中大规模

全量注入最大的好处是稳定。模型每次都能看到同样的偏好和约定,行为一致,不会因为检索没召回到而突然改变风格。代价是预算:记忆涨到五千 token,每轮都在为它付费,而且这些内容会挤占真正的工作空间。/AI/02/ 建议长期记忆加技能索引不超过窗口的 10%,按 200k 窗口算就是 20k,听起来很多,但记忆一旦不设上限,很容易吃掉一半。

按需检索省 token,但引入了检索的不确定性。用户问一个 Go 的问题,检索没召回「这个项目禁止引入新依赖」这条约定,模型就会建议你加个库。这种错误很难发现,因为回答本身看起来完全合理。

分层是折中,也是我现在更常用的做法。常驻部分只放两类:短偏好(十几条,每条一行)和项目硬约定(五六条,涉及安全和流程)。经验类内容全部按需,靠标签和关键词检索。这样既保证了行为一致,又不会让历史经验占满窗口。

还有一个和成本有关的细节:常驻记忆应该放在上下文前部,位置稳定,能吃到前缀缓存。记忆文件不要每次会话都重写,哪怕只是调整顺序,也会让缓存失效。记忆的价值是长期,缓存的收益也是长期,两者都要求「别乱动」。

注入顺序也影响注意力。记忆段里最靠前和最后的位置更容易被读到,中间容易被忽略。所以硬约束放最前,常用偏好放最后,中间放那些「有最好、没有也能干活」的条目。这个排序不需要精确,但方向要对:别把「禁止自动提交」埋在二十条偏好的正中间。

五、冲突、时效与去重

记忆一旦超过几十条,冲突就不可避免。同一件事,昨天的说法和今天不一样;全局偏好和项目约定打架;两条记录一个说用 npm,一个说用 pnpm。

处理冲突需要明确的优先级,不能交给模型临场判断。

显式指令高于观察推断。 用户明确说「这个项目用 pnpm」,比 Agent 观察到「目录里有 pnpm-lock.yaml」更可信。前者是意图,后者是现状,现状可能是历史遗留。

就近高于全局。 项目内的 AGENTS.md 优先于全局偏好。全局说「注释用英文」,项目说「这个仓库的注释用中文」,以项目为准。这条规则能解决大部分跨项目污染。

新的高于旧的,但旧的保留。 不是直接删除旧记录,而是标记 superseded_by,保留时间和来源。这样出问题时能回溯「什么时候改的、为什么改」。直接删掉,等于丢掉了审计线索。

无法判定时问用户。 两条记录互相矛盾,又没有时间或来源可依,最稳妥的做法是停下来问一句。让模型「综合判断」出一个第三条,是最坏的选择,它会造出一个谁都没说过的新事实。

时效要靠字段,不能靠模型记性。价格、版本、负责人、地址、命令,都应该带 expires_at 或 last_verified。读取时先过滤过期项,再排序,而不是把过期项也塞进去让模型自己判断。

1
2
3
4
5
6
7
8
9
10
{
"scope": "project:payment-api",
"key": "test.command",
"value": "make test-unit",
"source": "repo/AGENTS.md",
"updated_at": "2026-10-02",
"expires_at": null,
"confidence": "high",
"supersedes": "test.command@2026-06-11"
}

去重的关键是用主题键,而不是自由文本。写入前先按 scope + key 查一遍,有同键就合并或覆盖,没有才新增。如果只按文本相似度去重,会出现「单测命令」和「测试命令」两条几乎一样的记录,模型每次读到两条,反而更困惑。

六、记忆污染:错误会被反复强化

这是我认为最需要警惕的一节。记忆不是只读的档案,它会参与决策;决策产生的结果又会被总结成新的记忆。这是一个闭环,错了会自我强化。

一个真实的漂移过程。原始记录是:「在 monorepo 的 packages/ui 里不要直接引 lodash,用 utils/lodash.ts 的封装,因为要统一 tree-shaking 和按需加载。」经过一次自动摘要,变成「不要用 lodash」。再经过一次跨项目整理,变成「项目禁止 lodash」。三个月后,在一个完全无关的新项目里,Agent 拒绝使用 lodash,理由是「团队规范」。

每一跳都只丢了一点限定词,每一跳看起来都合理。问题在于摘要模型会合理化:它倾向于把带条件的、犹豫的、有例外的表述,压缩成确定的、通用的结论。限定词最先被丢,因为它们在摘要里显得啰嗦。

自我总结还会制造一致性。历史里有矛盾,模型不会保留矛盾,它会选一个看起来更合理的版本写下来,于是不确定性被抹平,错误变成了共识。

还有一个隐蔽的放大器:引用次数被当成可信度。一条记忆被召回十次,只说明它容易被匹配,不说明它是对的。如果系统按引用频率排序或加权,错误会被越推越前,形成正反馈。正确的排序依据应该是来源的可靠性、时间的新旧、人工确认的标记,而不是它被用过多少次。用得多不等于用得对,这个区别在记忆系统里格外重要,因为模型每次都会「确认」它一次,看起来就像一次投票。

几条对抗措施,按重要性排:

每条记忆带来源。 哪次对话、哪个文件、哪一行。来源不是给模型看的,是给人看的。出问题时能回到原文,才知道限定词是怎么丢的。

只让可验证的事实进长期记忆。 命令、路径、配置、明确的用户指令,这些能核对。模型的推断、总结、猜测,最多进「待验证」区,不能和事实混在一起。

控制自动总结的频率。 每次会话都总结一次,漂移速度是每周一次的好几倍。经验类记忆应该按任务归档,而不是按轮次累积。

定期人工审阅。 不用每天看,一个月一次,重点看「教训」段和最近新增的条目。审阅的目标不是改措辞,是删掉不再成立的和来源不明的。

保留原文,摘要只做索引。 一条经验的详情放在文件里,记忆库里只存一句摘要加路径。摘要错了还能回到原文,原文丢了就真的没了。

还可以给记忆加置信度,而不是非真即假。用户明确说的、从仓库配置读到的,标 high;模型观察推断的,标 medium;一次任务里的偶然结论,标 low。读取时按置信度排序,冲突时高置信度优先,low 的条目只在没有更高依据时才使用。这比把所有记忆一视同仁要安全得多,因为模型能看出哪条是「确定的规范」,哪条只是「上次看起来是这样」。

写入之后还要能验证。一条记忆如果声称「测试命令是 make test-unit」,下次执行前应该真的能跑通;跑不通就说明它过期了,应该标记而不是继续用。把记忆和可执行的动作绑在一起,是发现污染最有效的方式。纯描述性的记忆做不到这一点,所以它们应该更少、更短、更依赖人工审阅。

七、隐私、删除与团队边界

记忆系统会持续收集信息,这决定了它天然是一个隐私风险点。几条底线:

不落盘的内容:密钥、token、密码、身份证号、银行卡、客户个人信息、未公开的财务数据、医疗信息。这些不该进记忆,也不该进上下文。判断标准很简单:如果这个文件被误提交到公开仓库,会不会出事。会,就不要写。

脱敏后再存:绝对路径里的用户名、内部域名、工单号、客户名称。存「配置在项目根目录的 .env.local」,不存「配置在 /Users/zhangsan/...」。

删除要彻底。提供明确的 forget 操作,删文件、删索引、删备份,三步都要做。只删 Markdown 不删向量索引,下次还会被召回;只删主库不删备份,三个月后恢复环境又回来了。删完要验证:全文搜一遍关键词,确认没有残留。

团队共享要有边界。个人偏好不进团队库,否则一个人的习惯会变成所有人的规范。团队库只放项目事实和团队约定,每条有 owner,有人负责过期清理。权限跟着现有体系走,不要另建一套。成员离职或转岗,要有清理流程,否则他的个人记忆会一直留在共享库里。

合规问题提前想。数据能不能出境、保留多久、要不要审计日志,这些不是技术选型能兜住的。记忆里如果有客户数据,删除请求(比如用户要求删除个人信息)必须能覆盖到记忆层,而不只是主库。

审计日志是最后一层保险。谁在什么时候写入、修改、删除了哪条记忆,应该有一条不可篡改的记录。平时用不上,出事时它是唯一能还原「记忆是怎么变成现在这样」的东西。日志不用复杂,一行一条,带时间戳和操作者即可,但保留期限要提前定好,否则它自己也会变成隐私负担。

还有一条经常被忽略:用户要能看见记忆。如果记忆是黑箱,用户只会感到「它怎么知道这个」,却不知道该怎么改。提供查看、编辑、删除的入口,比任何算法优化都更能建立信任。查看要能按主题分组,编辑要能改一句话就生效,删除要真的删干净。这三件事做到,用户才愿意让它记更多;做不到,再聪明的 Auto Memory 也只是在替用户做他不知情的决定。

八、一份不容易膨胀的模板

三段式是我用过最稳的结构:用户偏好、项目约定、教训。前两段短且稳定,第三段承载经验,需要设上限。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# MEMORY

## 用户偏好
- [2026-10-02] 回答与注释用简体中文;代码标识符用英文。
- [2026-09-18] 包管理统一用 pnpm,不生成 package-lock.json。
- [2026-11-05] 改完代码先跑 `make test-unit`,不要自动 git commit。

## 项目约定
- [2026-10-20] 本地启动:`make dev`,依赖 docker compose 的 pg 与 redis。
- [2026-10-20] `internal/gen/` 是生成代码,禁止手改,改 schema 后重新生成。
- [2026-11-01] 错误码集中在 `pkg/errcode`,新增错误必须登记。

## 教训
- [2026-09-30] 迁移脚本先在小数据集验证;上次全量执行锁表 40 分钟。
- [2026-10-12] e2e 依赖 UTC 时区,本地 CST 会偶发失败。

写法上有几条硬规则,能显著延缓膨胀。

一条一行,带日期。 日期不只是元数据,它是判断时效的依据。没有日期的记忆,你永远不知道它是不是三年前的。

只写结论和动作,不写背景故事。 「上次迁移锁表四十分钟」是背景,可以放在详情文件里;记忆文件里只需要「迁移先小批量验证」。故事会让文件迅速变成日记。

同类合并,不留同义条目。 三条关于注释风格的偏好,合并成一条。每次新增前先搜一遍,能改就不加。

给每段设上限。 偏好二十条,项目约定十五条,教训三十条。超了就按时间淘汰最旧的,或者合并同类项。上限不是形式主义,它强制你做取舍。

过期标记而不是直接删。 不确定是否还有效的条目,加 [待确认] 前缀,一个月后还没人认领就删。直接删会让用户觉得「它怎么忘了」,标记一下有个缓冲。

不放命令全文,放路径。 一段十行的部署脚本放进记忆,每次会话都要为它付 token。存「部署脚本在 scripts/deploy.sh」就够了,需要时再读。

整理任务本身要人审。 可以让 Agent 定期提议「这三条可以合并」「这条三个月没被引用」,但不要让它自动执行。整理是删除,删除是不可逆的,必须有人确认。

常见的坑

  • 把一次性指令当长期偏好。 「这次用 Python 写个脚本」被记成永久偏好,下次写服务端也给你 Python。
  • 记忆文件只增不减。 四百八十行的文件,真正还有效的不到八十行,其余全是噪声。
  • 自动总结直接覆盖原文。 限定词一跳一跳丢光,最后变成一句谁都没说过的「团队规范」。
  • 把模型推断当事实写入。 「这个函数应该没被调用」进了记忆,后续所有判断都建立在猜测上。
  • 全局偏好与项目约定没有优先级。 两条都注入,模型每次随机选一条,行为不稳定。
  • 按文本相似度去重。 「单测命令」和「测试命令」并存,模型读到两条相似但不同的记录。
  • 记忆里放密钥或客户数据。 文件被同步、备份、误提交,风险远超收益。
  • 向量库召回不可解释。 记错了无法定位,只能整库重建。
  • 团队共享记忆没有 owner。 谁都能写,没人清理,半年后没人敢删。
  • 删除只删文件不删索引和备份。 下次重建索引,遗忘的内容全回来了。

检查清单

  • 三类记忆分开放:偏好全局、项目事实进仓库、经验进带标签的库。
  • 每条写入前过四道测试:可复用、稳定、非显而易见、有代价。
  • 每条记忆带日期、来源,必要时带过期时间。
  • 自动写入先进待审区,批量确认后再生效。
  • 常驻记忆控制在窗口的 10% 以内,超了就改按需检索。
  • 常驻内容放在上下文前部,保持稳定,别频繁重排。
  • 冲突按优先级处理:显式高于推断、就近高于全局、新记录保留旧记录。
  • 用 scope + key 做主题键去重,不靠文本相似度。
  • 摘要只做索引,原文另存,保证可回溯。
  • 每月人工审阅一次,重点清理无来源、已过期、长期未引用的条目。
  • 密钥与个人敏感信息永不落盘;删除要覆盖文件、索引、备份。
  • 团队库有 owner、有权限边界、有离职清理流程。

记忆系统的价值不在「记得多」,在「记得准」。一条错误的长效记忆,比十次重新询问的代价高得多,因为模型不会怀疑它,用户也很难发现它。

我现在维护记忆文件的方式,更像维护一份精简的运维手册:每条都有出处,每段都有上限,每个月删一次。删掉的东西比写进去的更值得关注,因为删掉的每一条,都是在给真正重要的那几条腾位置。

判断一个记忆该不该留,最后只需要问一句:如果它不在了,下次会不会做错事。会,留下;不会,删掉。

系列大纲与全部篇目见:Agent 原理与开发。

延伸阅读