记忆层构建器kiterunner1/agent-memory-hygiene

agent-memory-hygiene

中文 ·
English

让 AI 给你自己的环境搭一套记忆层。

这不是一篇讲道理的文章，是一个构建器。装进 agent 之后，它会：

1. 先探测你的环境——常驻契约在哪、多大、怎么注入；有没有知识目录；是不是 git 仓库；单项目还是多项目；有哪条必经之路可以挂检查。
2. 和你确认三个参数（常驻层预算、分层粒度、触发点），每个都给推荐值和理由。
3. 动手搭：常驻契约 + 知识层 + 派生索引生成器 + 体检闸门，并把检查挂到必经之路上。
4. 自己验收——量体积、跑生成器、跑体检脚本，并故意制造一个问题看它能否报出来。

已经有记忆层时走体检模式：按七项清单逐项查，每项给出证据和修法，默认方向是删而不是加。

适用于任何支持 Agent Skills 的 agent（Claude Code / Codex / Cursor / DSH / …），与具体 harness 无关。

为什么是「构建器」而不是「方法论」

方法论给的是通用建议，而你的环境是具体的：单项目和多项目的答案不一样，有 git 和没 git 的挂钩方式不一样，一次性任务根本不需要记忆层。

所以这个技能的核心是一条硬规则：先探测，再设计，绝不照搬模板。模板只是骨架，成品必须长在你的目录结构上。

它背后有三条反直觉的判断（详见 references/principles.md）：

- 「何时记」是伪问题——「这是不是最后一轮」判断不了，但「这一轮有没有产生值得留下的东西」是局部可判的。所以触发条件该是事件，不是会话边界。
- 平衡点不在读写频率，在副本数——同一事实只有一个写入点时写多少次都不会不同步；有多个写入点时写多少次都会不同步。
- 反异化最有效的手段是删除——给协作过程加一层自己的记录机制，它会自我维持、越滚越重。每一次想加规则，先问它能不能替换掉一条旧的。

装完会发生什么

你：帮我给这个仓库建立记忆层。

Agent（加载本技能后）：先看一下你的环境——找到 AGENTS.md（1.2k 字符）、docs/ 下 14 个文件、git 仓库干净、有 pre-commit 钩子。有三个参数要你拍板：常驻层预算（建议 2000 字符起）、哪些内容必须常驻、检查挂到哪个位置（你已经有 pre-commit，我建议挂那儿）。

……（确认后动手）

搭好了：AGENTS.md 精简到 1.4k，docs/ 按「环境 / 踩坑 / 流程」分了三层，INDEX.md 由 tools/build-index.mjs 生成（已挂进 pre-commit），tools/healthcheck.mjs 退出码非 0 时会挡住提交。我故意在索引里留了个坏引用，体检脚本正确报出来了。

里面有什么

agent-memory-hygiene/
├── SKILL.md                      # 主流程：探测 → 定参数 → 搭建四件套 → 挂钩子 → 验收 / 体检模式
├── references/
│   ├── principles.md             # 七条决策依据（为什么这么做）
│   ├── health-check.md           # 体检清单：七项，含怎么测、判定、修法
│   └── antipatterns.md           # 反模式：搭建 / 运行 / 收尾三个阶段
└── templates/
├── build-index.mjs           # 派生索引生成器骨架（Node，零依赖，改 CONFIG 即用）
└── healthcheck.mjs           # 体检脚本骨架（退出码非 0 = 不健康，可挂 CI/hook）

两个模板都是可直接运行的骨架，已验证：build-index.mjs 能扫目录生成索引，healthcheck.mjs 能检查常驻层体积、坏引用、未落盘、索引新鲜度并正确报错。

安装

方式一：skills CLI（DSH 未被 CLI 收录，借 cline 的目录映射落到 ~/.agents/skills/）
npx skills add kiterunner1/agent-memory-hygiene -g -a cline -y

方式二：手动
git clone https://github.com/kiterunner1/agent-memory-hygiene.git ~/.agents/skills/agent-memory-hygiene

各 agent 的技能目录：

| Agent | 项目级 | 用户级 |
| --- | --- | --- |
| DeepSeek Harness | /.dsh/skills/（rank 100）或 /.agents/skills/（rank 200） | ~/.dsh/skills/（rank 400）或 ~/.agents/skills/（rank 500） |
| Claude Code | /.claude/skills/ | ~/.claude/skills/ |
| Codex | /.codex/skills/ | ~/.codex/skills/ |
| 其它兼容 agent | 按该 agent 的技能目录约定 | 同上 |

怎么触发

装完不用记命令，直接说人话：

- 「帮我给这个项目建立记忆层」
- 「我的规则越写越多，但行为没变好」
- 「整理一下 AGENTS.md」
- 「记忆层体检」/「检查一下我的规则还有没有用」
- 「换个新项目，重新沉淀一套」

设计取舍

为什么带脚本模板。「派生索引」这一招最反直觉也最有效，但纯文字描述很难落地——大多数人会退回手写清单。给一个能跑的骨架，改 CONFIG 就能用，落地率完全不同。

为什么模板是 Node。零依赖、跨平台、几乎所有 agent 用户都有。你可以按环境换成任何语言，接口约定比实现重要：索引从结构派生，体检用退出码表达结论。

它不做什么。不替你决定预算和粒度（那是你的取舍），不往你的仓库里塞你不需要的东西（先探测、先问），也不假装能测出「内容是否过期」（那必须人来核对）。

可回滚。它的产物全是普通文件，放在你自己的 git 仓库里。不满意就 git checkout。

FAQ

Q：它会不会往我仓库里乱写？
会写文件——这是构建器，不产出文件就没有价值。但它先只读探测、再和你确认参数，产物都在版本控制里，可以随时回滚。

Q：我的环境很特殊，模板套不上怎么办？
那正是它的设计前提：模板只是骨架，主流程要求按你的目录结构改造。SKILL.md 里明确写了「不要照搬模板」。

Q：需要什么依赖？
技能本身零依赖（纯文本 + 两个可选脚本）。模板脚本需要 Node；不用 Node 就按同样的接口约定自己写一个。

Q：和「写一份 AGENTS.md」有什么区别？
写文件是结果，不是方法。这个技能关心的是：什么时候该写、写到哪一层、怎么让它半年后还成立、怎么知道它已经烂了。

License

MIT——见 LICENSE。