agent-memory

Agent Memory——晋升靠 earned，而非自称

**可移植性：**仅使用标准库。无需数据库、嵌入、网络或 LLM 调用。

问题

项目的 CLAUDE.md 是一个只有单层、不会淘汰内容的记忆系统：每条持久事实和每个一时偏好都会进入同一个始终加载的文件，直到重要内容被偶然信息稀释。会话中途学到的事实会在会话结束时消失，除非有人把它们写下来。

**解决方法不是增加存储，而是建立晋升阶梯。**一条主张通过反复出现，逐步进入始终加载的上下文；最后一步由人确认。

四个层级

层级由注入策略区分，而非存储格式。

层级	保存内容	注入时机	是否提交
L0	原始会话记录	从不	否（已在磁盘上）
L1	候选原子	在提示词生成时，按相关性注入	否（被 gitignore 忽略）
L2	当前项目的上下文	每次会话开始时	是，采纳后
L3	跨项目的稳定角色信息	始终	是，采纳后

晋升关卡

不会因为某条信息听起来重要就让它晋升。只有反复出现，它才会晋升。

• L0 → L1——明确标记触发（指令、纠正、明确表达的偏好、具名经验、可复现的故障）。基于规则，精确率高，刻意降低召回率。
• L1 → L2——至少跨越 2 个不同日历日，出现在至少 3 个不同会话中。明确陈述的主张需要 2 个会话；不同日期的规则仍然适用。经验证的主张在观察到一次后即可晋升，且这是唯一不受日期限制的路径。
• L2 → L3——存在于至少 2 个不同项目中，已存续至少 30 天，且没有争议。

**两道关卡会拒绝，而非猜测。**文本被脱敏改动的主张不会仅凭证据晋升——标记触发说明来源可能包含敏感内容，而词法过滤器发现一个秘密，并不能证明它发现了所有秘密。存在未解决矛盾的主张会冻结在 L1，直到有人解决；现有主张绝不会被悄悄覆盖。

使用方法

# what is remembered, and what is blocking the next promotion
python3 scripts/memory_inspect.py --tier L1

# where did this line come from — sessions, days, transcript, quoted source
python3 scripts/memory_inspect.py --why "PR base branch is dev"

# every claim with an open contradiction, both directions of the join
python3 scripts/memory_inspect.py --contested

# dry-run the promotion pass; writes nothing
python3 scripts/memory_promote.py

三个钩子会无人值守地运行整个流程：SessionStart 注入 L2 + L3，UserPromptSubmit 召回相关的 L1 原子，SessionEnd 捕获并暂存内容。每个钩子都可单独禁用：AGENT_MEMORY_SESSIONSTART=0、AGENT_MEMORY_USERPROMPTSUBMIT=0、AGENT_MEMORY_SESSIONEND=0。每个钩子都会以开放失败方式运行：记忆系统出故障只会让你损失记忆，绝不会中断会话。

硬性规则

1. **先脱敏，再写入。**每个原子在写入磁盘前都会经过过滤器。任何被改动的内容都会被隔离，无法晋升。
2. **只提议，不应用。**晋升内容会写入 .memory/staged/。只有显式执行 /cs-memory adopt 才会修改 CLAUDE.md，而且会先备份两份文件。
3. **引用，不编造。**每个原子都包含指向生成它的记录行的反向指针。若 --why 的解析结果为 ambiguous，就不输出任何内容，而不是猜测：错误引用比缺少引用更糟。
4. **绝不把有争议的主张当作事实展示。**它仍会被注入——隐瞒冲突更糟——但始终会带有标记。
5. **已提交的层级不包含路径。**晋升时会剥除反向指针前缀，其中包含操作系统用户名。

反思问题

在信任此存储库之前，请逐条思考以下问题。

1. 你采取行动之前，最近一次实际阅读 CLAUDE.md 中的哪一行？
2. 你更愿意让 Agent 忘记真实的信息，还是记住错误的信息？
3. 两条已记忆的规则发生冲突时，由谁决定——又在何时决定？
4. 什么情况会让你彻底删除 .memory/？

设计依据、待决事项和字段架构：../../DESIGN.md。