分层记忆模板 diancangdu/dsh-agent-memory-public

dsh-agent-memory

分层长期记忆模板：让 AI coding agent 跨会话记住该记的东西。

当前版本：v1.0.0 —— 变更历史见 CHANGELOG.md，安装见 INSTALL.md。

AGENTS.md 同时充当两种角色：给 agent 的指令 和 跨会话的长期记忆本体。
它在每个会话的第一次请求时被自动注入，改它即刻对后续会话生效。
本仓库提供这套机制的可复用模板。

这是 public 版：只含机制与占位符示例，不含任何具体的机器路径或环境细节。
原样（含本机信息）的版本另存于 private 版仓库。

为什么需要「分层」而不是一个大文件

因为注入是有预算的（典型 64 KiB），而且它每次会话都注入。

写得越长，越浪费上下文，也越容易让真正重要的约束被淹没。
所以这套设计的核心不是「多记」，而是记在哪、记多密：

| 层 | 位置 | 加载方式 | 放什么 | 体量约束 |
| 用户级 | /AGENTS.md | 自动注入，所有项目 | 跨项目硬规则、环境坑 | 每小节 ≤ 15 条 |
| 项目级 | /AGENTS.md | 自动注入 | 该项目约定、结构、选型 | ≤ 200 行 |
| 项目日志 | /memory/YYYY-MM-DD.md | 按需读、必须写 | 逐轮流水，append-only | 超 30 天归并后删 |
| 历史会话 | — | 主动检索 | 更早对话的细节 | — |

判据：一个问题如果只有这个项目关心 → 项目级；如果换个项目还会踩 → 用户级。
两者都不满足（只是一次性的过程细节）→ 别记。

三个最容易被做错的地方

1. 只记结论，不记过程。
条目写成 - 事实。判据或原因。（日期）。过程留在日志里。
记忆本体被注入，日志不被注入 —— 把过程写进本体等于每次都浪费预算。

2. 同一件事有更新就改写原条目，不要追加第二条。
否则同一事实会出现多个互相矛盾的版本，而 agent 无从判断哪个最新。

3. 「记住了」和「真的在起作用」是两件事。
把一条规则写进文件，只证明文件里有它；要证明它生效，需要独立旁证（一次被拦下的操作、一条日志、一次失败）。这条在模板的「踩过的坑」里也留了示例。

使用

1. 把 AGENTS.template.md 复制成 AGENTS.md，放到对应的层级：
- 用户级：/AGENTS.md
- 项目级：/AGENTS.md
2. 把所有 占位符换成你自己的值。
3. 删掉「示例」性质的条目，那是给你看格式用的。
4. 在项目根建 memory/ 目录，当轮就开始写 YYYY-MM-DD.md。

文件名必须是 AGENTS.md，位置必须是上面两处 —— 宿主是按约定路径自动扫描注入的，换个名字或换个目录就不会被加载。

与自学习（经验库）的分工

两者容易混，边界是：

- 记忆（本仓库）：稳定的事实与约定 —— 这台机器什么样、这个项目的结构、用户的偏好。
- 经验库：过程性教训 —— 这次踩了什么坑、什么做法有效，可以按需检索而不是每次注入。

先记经验，同一流程反复出现后再升级为 Skill / 固化进记忆。
不是二选一，也不是同一件事记两遍。

已知边界

- 各宿主对「项目根到工作目录每一层」的扫描顺序可能不同，跨层同名文件请以更近的为准
- 自动注入有预算上限，超出部分会被截断 —— 这正是「每小节 ≤ 15 条」存在的理由
- 本仓库只是模板与说明，不含任何可直接生效的内容；生效靠你填进去的东西