# Agent Memory Hygiene

> 为使用者自己的环境现场构建 agent 长期记忆层：先探测环境，再搭常驻契约、知识层、派生索引与体检闸门，并挂到必经之路上；已有记忆层时走体检模式。当用户说"帮我建立记忆层""规则越写越多但没用""整理一下 AGENTS.md""换个项目重新沉淀"，或你想为一个仓库建立长期协作机制时使用。Build or health-check an agent's long-term memory layer, tailored to this environment.

- Skill: `kiterunner1/agent-memory-hygiene` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kiterunner1/agent-memory-hygiene`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kiterunner1/agent-memory-hygiene/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kiterunner1 (https://skillmd.com/u/kiterunner1)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kiterunner1/agent-memory-hygiene

---


# 给这个环境搭一套记忆层

你在**动手为使用者的具体环境搭建**，不是讲方法论。方法论是决策依据（见 `references/principles.md`），**能跑起来的产物才是交付**。

## 绝对前提

**先探测，再设计。**不要先讲原理，也不要照搬模板——同一套做法在「单项目 / 多项目」「有版本控制 / 没有」「一次性任务 / 长期协作」下答案完全不同。

## 第一步：探测（只读，什么都别改）

按顺序查，把结果写下来：

1. **常驻契约**：有没有 `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / 项目指令文件？路径、体积（字符数）、是每轮注入全文还是只注入索引？
2. **已有沉淀**：有没有知识目录（`docs/`、`kb/`、`notes/`、`adr/`）？文件数、最近修改时间、有没有明显很久没人读的？
3. **版本控制**：是 git 仓库吗？根在哪？有多少未提交改动？
4. **工作形态**：单项目还是多项目？任务是一次性还是长期反复？
5. **已有的必经之路**：git hooks、CI、启动脚本、任务运行器、发布流程？
6. **工具链**：有 `node` 吗？有 `git` 吗？（决定生成器/体检脚本用什么写）

只读探测，别顺手改东西：

```bash
# 常驻契约与知识目录（有哪个看哪个）
ls -la AGENTS.md CLAUDE.md .cursorrules .cursor/rules 2>/dev/null
ls -d docs kb notes adr 2>/dev/null

# 常驻层体积
wc -c AGENTS.md CLAUDE.md 2>/dev/null

# 版本控制状态
git rev-parse --show-toplevel && git status --porcelain | wc -l

# 工具链
node --version; git --version
```

Windows 上用 `pwsh`：`Get-ChildItem AGENTS.md,CLAUDE.md`、`(Get-Content AGENTS.md -Raw).Length`、`git status --porcelain | Measure-Object`。命令按平台换，**探测项目的一样**。

## 第二步：定三个参数（一次问完，别来回问）

这三件事不要替用户拍板，但**必须给出推荐值和理由**：

1. **常驻层预算**：常驻注入每轮都在花 token。建议 1000–2000 字符起步，先说清这个数字是"上限"而不是"目标"。
2. **分层粒度**：哪些必须常驻（判据、硬触发、指针），哪些放可检索层（细节、手册、历史教训）。
3. **触发点**：这条必经之路在哪（提交前？安装前？启动前？）。如果环境里一条都没有，建议先建一个最简单的。

## 第三步：搭建四件套

按顺序产出，每件都落成文件。

### 1. 常驻契约（一个文件）

只放三类内容：**判据**（遇到 X 怎么决策）、**硬触发**（必须做什么）、**指针**（细节去哪找）。

不放：教程、完整清单、历史记录、任何能被派生的内容。

### 2. 知识层（目录 + 分层）

按**问题类型**分（环境 / 踩坑 / 流程 / 工具），不要按时间分。每个文件第一行必须回答「何时用」：

```markdown
# <名字> —— 是什么 / 何时用：<触发条件>
```

没有「何时用」的文件等于不会被读，因为路由只能靠这一行。

### 3. 派生索引（生成器脚本）

**绝不手写清单。**写一个脚本扫结构生成索引，骨架见 `templates/build-index.mjs`，按你的目录结构改。

判据：**这个索引的维护成本必须为 0**。需要人工同步的索引一定会腐烂，而它腐烂时没有任何告警。

### 4. 体检闸门（体检脚本）

骨架见 `templates/healthcheck.mjs`，检查项见 `references/health-check.md`。

约定：**退出码非 0 = 不健康**，这样它能挂进 CI 或 git hook，而不是一个"记得去跑"的脚本。

## 第四步：把规则挂到必经之路

**需要"记得跑"的检查等于不存在。** 找出这个环境里一定会发生的事件，把检查挂上去：

- git 仓库 → `pre-commit` 钩子（或提交前明确的一步）
- 有 CI → 加一个 job
- 有启动脚本 → 启动时跑一次
- 都没有 → 至少把「什么时候该跑」写进常驻契约的硬触发段

一条约束如果能做成代码（断言、钩子、脚本），就不要写成散文。同一条约束，做成守卫和写成文档，实际执行率的差距是数量级的。

## 第五步：验收（自己验，不要问用户"这样可以吗"）

- 常驻契约在预算内（跑 `wc -c` 或等价命令，把数字报出来）
- 生成器能跑通，产物已进版本控制
- 体检脚本能跑通，**并且能正确报出至少一个你故意制造的问题**（不验这个就等于没验）
- 每一层至少有一个文件，且每个文件首行有「何时用」
- 没有手写清单残留（搜一下有没有那种需要手动加行的列表）

## 体检模式（已经有记忆层时）

用户说「体检 / 整理 / 检查记忆层」时走这条路，**不要重新搭建**：

1. 按 `references/health-check.md` 的七项逐项查。
2. 每项给出：结论 + 证据（跑的命令和输出）+ 修复动作。
3. **只删不加**：修法的默认方向是删掉、或改写成代码，而不是再加一条规则。
4. 最后回答一个问题：**维护这套机制的成本占比，是在升还是在降？**如果是升而任务产出没变，那本身就是最严重的问题。

## 不要做什么

完整清单见 `references/antipatterns.md`。最容易犯的三条：

- 先讲一堆原理再动手（用户要的是能跑的东西）。
- 照搬模板不看环境（单项目和多项目的答案不一样，多项目还多一层"跨项目沉淀放哪"）。
- 把该做成代码的约束写成散文，然后指望以后记得跑。