如果你正在使用 Claude Code、Codex、Cursor 或 Windsurf 等 AI 编码 Agent，大概率遇到过同一个痛点：关掉窗口再打开，它就像"失忆"了一样——不知道上次做到哪、忘了你纠正过的错误。agent-md 是一个生产级编码 Agent 规范工具，它的 5 文件记忆系统（memory/ 目录）用五个 Markdown 文件给 Agent 装上了"长期记忆"，实现跨会话状态延续、任务进度可追溯、错误不重犯。

为什么 AI 编码 Agent 会"失忆"？

Agent 的记忆分两层，很多人搞混了：

agent-md 的核心规则写得很直白："Chat history is not durable memory"（聊天记录不是持久记忆）。所以它要求 Agent 在每次会话开始时主动读取记忆文件，工作过程中随时更新它们。这个设计就定义在 AGENT.md 的 "Persistent State" 章节。

5文件记忆系统：各司其职的五份档案

安装 agent-md 后，项目根目录会出现memory/目录，里面有五个文件。它们的分工可以用一句话概括：

一个管"环境"、一个管"设计"、一个管"进度"、一个管"验收"、一个管"教训"。

1️⃣ agents.md —— 环境与工具登记册

memory/agents.md 记录项目当前的"硬件配置"：

• 活跃子 Agent：可以委派任务的子代理有哪些
• MCP / 外部服务：Agent 能调用哪些外部工具（如 Playwright 截图、数据库 MCP）
• 技术栈：运行时版本、语言、框架、测试与 Lint 工具
• 禁用模式：项目里明确不许写的代码写法

它相当于新会话的"入职手册"，避免 Agent 每次都要重新问一遍"这个项目用什么框架"。

2️⃣ plan.md —— 宏观设计与垂直切片

memory/plan.md 存放架构级的设计决策，核心是垂直切片（Vertical Slices）：

• Current Phase：当前所处阶段
• Vertical Slices：每个切片对应一个"用户可见的成果"，包含 UI、API、数据、测试、验收五要素
• Deferred / Out of Scope：明确"现在不做什么"，防止范围蔓延
• Open Questions：实现前必须和人确认的模糊点

它的作用是防漂移——Agent 不会在写了一半功能时突然跑去改数据库结构，因为设计方向已经白纸黑字写在文件里了。

3️⃣ progress.md —— 原子进度日志（时间锚点）

memory/progress.md 是整个记忆系统里最"刚性"的文件，它把自己称为"Your temporal anchor"（你的时间锚点），分为四个区块：

• In Progress：当前任务，同一时间只允许一个
• Completed (this session)：已完成任务 + 一行验证说明
• Backlog (next up)：接下来要做的
• Blocked：被阻塞的任务及原因

它的作用很关键：新会话开始时，Agent 打开这个文件就知道"上次做到哪、接下来干什么"，而不是让你重新复述一遍需求。

4️⃣ verify.md —— 完成定义（Definition of Done）

memory/verify.md 规定了任务"什么状态才算做完"，分五类验收标准：

1. 文本验证：类型检查、Lint、测试全部通过
2. 运行验证：代码真的跑过，不只是"写完了"
3. 视觉验证：UI 改动必须截图存证
4. 独立验证：不允许 Agent 自说自话"看起来对"
5. 任务专属标准：针对每个切片的自定义验收项

规则很硬：没满足 verify.md 的条目，progress.md 里就不许打勾。

5️⃣ gotchas.md —— 错误教训日志

memory/gotchas.md 记录"人纠正过的每一个错误"，格式为：

- **日期** — *犯了什么错* → **规则**

比如"假设环境变量存在、静默回退为空字符串"这样的坑，会被提炼成一条硬规则。新会话开始前必须先复习它，目标是把错误率压到零——同一个坑不摔第二次。

光写文件还不够：钩子强制执行

很多"记忆系统"死在 Agent 偷懒不改文件上。agent-md 的解法是把关键记忆文件升级为可执行契约：

• 状态钩子：state-enforcement.sh 会在 Agent 想"收工"时检查——如果源码文件变了但memory/progress.md没更新，直接拦截、不许结束
• 完成校验：stop-verify.sh 在收尾时跑类型检查、Lint 和测试，不通过就拦住
• 行为边界：block-destructive.sh 硬性阻断危险命令

对应的行为测试可以看 tests/state-enforcement.bats，里面明确验证了"源码改了但 progress.md 没动 → 拦截"这条规则。简单说：想忘记？系统不让你忘。

快速上手：三步装好记忆系统

git clone https://gitcode.com/gh_mirrors/cla/agent-md cd agent-md ./install.sh --agent=claude /path/to/your-project

安装器默认支持 Claude Code、Codex、Cursor 和 Windsurf（详见 README.md 和 install.sh）。两个值得注意的细节：

• ✅已有记忆永不覆盖：installer 只补全缺失的memory/*.md，你已有的进度、计划原样保留（见 install.sh 中的逻辑）
• ⚙️可选确定性校验：把 agent-md.toml.example 复制为agent-md.toml，显式声明 typecheck / lint / test 命令，避免钩子靠猜

使用建议：让记忆系统真正转起来

1. 会话开始先读，会话结束必写：这是 AGENT.md 对 Agent 的硬性要求，人也要监督
2. gotchas.md 要当真的记：每次纠正 Agent 后花 10 秒补一条，是投入产出比最高的动作
3. progress.md 的任务保持原子化：一条任务一行，太大就拆，这是钩子能精准拦截的前提
4. 验收标准前置：动手前先把这条切片的完成标准写进 verify.md，避免"做完了但没人认"

小结

agent-md 的 5 文件记忆系统本质上是把"人脑里的项目状态"外化成五个职责单一的 Markdown 文件，再配合钩子强制执行：

下次再开新会话，Agent 打开这五份档案就能无缝接上进度——不忘事、不漂移、少重复犯错，靠的不是更大的上下文窗口，而是这套朴素但可靠的文件契约。