# 设计与调度原理

写给要改这个插件的人，以及想知道它为什么这样工作的人。日常使用看 [README](../README.zh.md) 就够。

## 三层记忆

| 层 | 文件 | 放什么 |
|---|---|---|
| L0 | `memory_management_sop.md` | 元规则，读写记忆时的判据 |
| L1 | `index.txt` | 只列存在性，条目标题与文件名 |
| L2 | `facts.md` | 环境事实，路径、配置、实测参数 |
| L3 | `sops/*.md` | 任务经验，前置条件、坑点、稳定步骤 |

L1 每轮都在模型上下文里，所以它只写库里有哪些东西，不写内容。模型看到标题，需要细节时再取。

## L1 为什么不裁剪

v0.6 之前 L1 按行数和热度裁剪，超出预算的条目会被挤出去。挤出去等于永久隐身，模型不会去搜一个它不知道存在的东西。现在 AUTO 段全量列出活跃条目名，预算单位是字符数（`l1MaxChars`），超预算只在工具返回值和维护报告里告警，由人来合并或归档。

索引内容没变化时不重写文件，这样不会把"刚检查过"误算成内容变化（维护自激），内容指纹也不会跟着修改时刻抖动。system prompt 的前缀缓存按请求内容匹配，与文件写没写无关。

## 反思提醒什么时候发

插件可以在一个回合结束时往会话里投一条整理提醒。这条提醒很容易变成骚扰，所以判定分两步。

第一步看冷却。距离上次提醒不到 `reflectCooldownTurns` 轮就不评估。

第二步看内容版本。计算记忆库的内容指纹，写进 `reflection-state.json` 的 `revision` 字段，再看这一版有没有结论。

- 已经检查过，结论是 `no_action` 或 `done`，不再提醒
- 已经就这一版提醒过一次，不再提醒
- 内容变了（新增或改写条目、索引超预算、出现合并候选），重新评估

指纹只取内容面，也就是 `facts.md`、`index.txt`、`memory-meta.json`、`sops/*`、`pending/*` 的体积与修改时刻。轮次计数、访问热度、报告时间这些每次都变的字段不进指纹，否则每检查一次就把自己标脏，又变成无限提醒。

维护跑完（自动周期维护或手动 `memory_maintain`）会把这一版内容的结论写回去，所以手动跑一次维护同样能让提醒停下来。

## 一致性边界

一致性靠流程保障。写入前先查重，同主题演进走 `memory_update`，旧版本连同溯源元数据一起快照进 `.history/`（正文与证据、来源、关联成对，`memory_rollback` 一起恢复）。重复判定与检索归一化分开，只把同名同内容的重复段自动无损合并；跨条目内容一致或高度相似的条目由 `memory_maintain` 产出候选，语义确认后才合并或归档。条目自带 `updatedAt` 和证据，跨条目矛盾在读取时按时间线裁决。一轮多文件写（快照、正文、元数据、索引）持命名空间写锁，锁内重新读取再提交。

## 四条公理

1. **行动验证。** 没有成功执行过的信息不写进记忆，`memory_write` 的 evidence 必填
2. **不物理丢弃。** 已验证的事实可以压缩、迁移、supersede、archive，但不删除
3. **不存易变状态。** 时间戳、PID、临时路径不进记忆
4. **最小充分。** L1 只写存在性，细节按需取