编程 Agent 的记忆问题，很容易被误解。
很多人以为“记忆”就是让模型永远记住所有对话。真实情况不是这样。模型本身不会自动带着你上周的项目细节进入今天的任务。Harness 必须把需要保留的信息，以某种形式重新加载进上下文。
所以，Agent 记忆不是玄学，而是上下文工程。
三类记忆
在工程实践里，可以把 Agent 记忆分成三类。
第一类是短期上下文。它存在于当前会话里，包括用户任务、对话历史、文件内容、工具输出、测试结果。会话结束后，它通常不会自动进入下一次任务。
第二类是长期规则。比如 CLAUDE.md、AGENTS.md、Cursor Rules。这些文件记录项目约定、构建命令、代码风格、架构边界，每次会话开始时加载。
第三类是项目知识。比如代码图谱、文档索引、历史故障记录、接口说明、设计决策。这类知识通常不应该全部塞进上下文，而应该按需检索。
这三类记忆不能混用。把所有项目知识都塞进长期规则，会让上下文变脏；把关键团队规范只放在对话里，下次就会丢。
短期上下文：任务现场
短期上下文是 Agent 当前正在处理的现场。
比如你让它修一个 bug，它会逐步收集：
- 报错信息；
- 相关文件；
- 测试输出；
- Git diff；
- 用户补充说明；
- 中间计划。
短期上下文适合放当前任务相关的信息，不适合承载长期规范。
一个常见问题是长任务做着做着上下文满了。Harness 会压缩或摘要旧内容，但摘要一定会丢细节。重要规则如果只在对话开头说过，后面可能不再可靠。
解决方法是：长期规则写进规则文件，任务关键点阶段性复述，复杂任务拆小。
长期规则：团队约定
长期规则的价值，是减少重复解释。
比如：
本项目后端使用 Java 21 和 Spring Boot。
数据库迁移脚本放在 sql/migration。
所有接口错误返回 ApiError。
提交前必须运行 mvn test。
不要修改 generated 目录。
这些信息每次任务都可能有用，适合写进 CLAUDE.md、AGENTS.md 或 .cursor/rules。
但长期规则要克制。Claude Code 官方文档也提醒，CLAUDE.md 内容越具体、越简洁，越容易被遵守；太大、冲突或模糊都会降低效果。
一个经验是：项目级规则控制在 100-200 行以内。超过这个长度，就应该拆成路径规则或 Skills。
项目知识：按需召回
项目知识往往很大。
比如：
- 全部 API 文档；
- 历史 PR；
- 事故复盘；
- 代码调用图；
- 数据库表结构；
- 产品需求；
- 设计稿说明。
这些信息不能每次都加载。正确方式是索引起来，任务需要时按需召回。
这就是 CodeGraph、Understand-Anything、RAG、MCP 文档服务的价值。它们不只是“存资料”，而是帮助 Agent 在合适时间找到相关知识。
记忆污染
记忆不是越多越好。
记忆污染常见于三种情况。
第一，旧规则没删。项目已经从 npm 切到 pnpm，但规则里还写 npm。
第二，个人偏好混进团队规则。某个开发者喜欢某种写法，不代表团队都应该遵守。
第三，临时结论变成长期事实。一次排障时的猜测被写进记忆，下次 Agent 当成真相。
所以记忆需要维护。规则文件要像代码一样 Review，过期内容要删，冲突规则要合并。
真实落地方式
一个团队可以这样组织记忆：
AGENTS.md
通用 Agent 指令，供多种工具读取
CLAUDE.md
Claude Code 专用补充
.cursor/rules/
Cursor 路径级规则
docs/architecture.md
架构说明，按需引用
.codegraph/
代码索引，本地生成
规则里只写长期稳定的事。复杂流程放 Skills。大量知识放索引系统。临时任务信息留在会话里。
什么时候该写入记忆
可以用四个判断标准。
第一，Agent 第二次犯同样错误。
第二，Code Review 提醒了某个项目规则。
第三，新人也需要知道这条信息。
第四，这条信息未来多个任务都会用到。
如果只对当前任务有用，不要写进长期规则。
总结
Agent 记忆的核心不是“让模型什么都记住”，而是把信息放到正确位置。
当前任务信息：放短期上下文
团队稳定约定：放长期规则
大量项目资料：放知识索引
必须强制执行：放权限和 hooks
记忆系统做得好，Agent 会越来越懂项目；做得差，它只会越来越混乱。
