@modusensus/dsh-mneme 0.8.14 → 0.8.16

package/docs/STORAGE.md

@@ -0,0 +1,98 @@
+# dsh-mneme 存储无损回收（#275 第一批）
+
+## 概览
+
+库大了以后有两类内容占着体积却零信息增量：
+
+- `dream_runs.input`：每次巩固时的**记忆库快照**，可由记忆库重建；
+- 归档行的向量：检索 SQL 恒带 `archived = 0`，按定义不可达。
+
+这个入口把这两样回收掉。一条记忆都不删、一次价值判断都不做。
+
+> #399 起多回收第三样：`distill_records`（蒸馏原文留存，默认关）。它同样是「留着只占体积」——原文的回查价值随保留期衰减，但**溯源链接刻意不删**（链接是记忆的元数据，原文才是可弃的缓存）。见 [蒸馏原文留存](DISTILL.md)。
+
+它**不自动跑**：几项都是不可逆的内容丢弃，只在人看得见数字的时候按下（维护者 2026-09-23 拍板：不挂启动路径、不开 `auto_vacuum`）。
+
+## 用法
+
+```bash
+dsh-mneme reclaim                              # dry-run：会清几行、库多大，一个字节都不改
+dsh-mneme reclaim --apply                       # 执行清理（不带 --vacuum 文件不会变小）
+dsh-mneme reclaim --apply --vacuum              # 清理 + 整库 VACUUM
+dsh-mneme reclaim --older-than 30 --apply       # 输入快照保留窗口 30 天（默认 7；0 = 全部）
+dsh-mneme reclaim --json                        # 原始 JSON，给脚本用
+```
+
+前置：插件设置里打开「外部 API」（默认 `http://127.0.0.1:8790`），token 用 `dsh-mneme config set <url> <token>` 配一次。命令走 standalone 数据面 `POST /maintenance/reclaim`；服务端要求显式 `confirm`，不带就是干跑。
+
+## 清什么、不清什么
+
+| 对象 | 动作 | 为什么零损失 |
+|---|---|---|
+| `dream_runs.input`（窗口外） | 置空 | 它是当时的记忆库快照，可由记忆库重建 |
+| `dream_runs` 的骨架 / `decisions` / `outcome` / `receipt` | 不动 | 不可重建：拆了就回放不了那次裁决 |
+| `memories.embedding`（`archived = 1`） | 置空 | 检索恒带 `archived = 0`，按定义不可达 |
+| `memories` 的行 | 一条不删 | 本入口止体积不止条数；条数与重复归 #254 与整理动作面 |
+| 活跃行的向量 | 不动 | 检索正在用 |
+| `distill_records`（窗口外，#399） | 删行 | 蒸馏原文留存是 opt-in 旁路索引；到期即弃。**`memory_provenance` 链接保留**指向空区间（面板显示「来源已过期」），记忆与链接都不删——原文本就是「回查用」的，保留期到了就该走 |
+
+`distill_records` 只在 `distillRecords.enabled=true` 时才有行（默认关，连收集都不做），所以对大多数库这一项恒为 0。
+
+取消归档时（`memory_archive` 还原）服务端会重新排队嵌入，所以被回收的向量能拿回来。
+
+## 代价与实测
+
+VACUUM 是 O(库大小)，且需要排他写锁：库越大越慢，期间的写要等锁。
+
+实测方法：把一份真实库**复制**到临时目录后跑本入口（不动活库），命令即 `reclaim` 的 dry-run 与 `--apply --vacuum`。样本是一次单机实测，不代表全部用户。
+
+| 项 | 读数 |
+|---|---:|
+| 清理前磁盘足迹（主文件 65.5 MiB + WAL 3.9 MiB） | 69.5 MiB |
+| 清 `dream_runs.input` | 177 个 run，列文本 7.24 MiB |
+| 清归档行向量 | 295 行，列文本 3.04 MiB |
+| 清理 + VACUUM 后足迹 | 50.8 MiB（降 18.66 MiB，约 27%；页数 16800 到 12983） |
+| VACUUM（含收尾 checkpoint） | 1.2 s |
+| dry-run | 48 ms |
+
+两点值得注意：体积降幅**大于**列文本合计（7.24 + 3.04 MiB），差额来自溢出页与索引页的回收——这就是报告口径按「VACUUM 前后体积」而不按列字节估的原因；另外体积量的是**磁盘足迹**（主文件 + `-wal` + `-shm`），WAL 模式下只量主文件会量到「还没落盘」的旧值。
+
+报数字以自己这次的 dry-run 与 apply 输出为准（dry-run 里的列文本大小只是上界，空闲页字节是「立刻能收回来」的那部分）。
+
+## 已知坑
+
+- `--vacuum` 必须配 `--apply`：dry-run 不改数据，也就没有可回收的页。
+- 只清理不 VACUUM，文件不会变小（空闲页留在文件里）；体积收益要等一次 VACUUM。VACUUM 内部收尾会跑一次 `wal_checkpoint(TRUNCATE)`，否则 WAL 模式下主文件可能一动不动。
+- VACUUM 拿不到排他锁（别的进程占着库）会失败：**清理已经完成且不可逆**，命令会照旧打印「清了 N 行」并把失败原因写进报告与回执，重跑一次 `reclaim --apply --vacuum` 即可（清理幂等）。
+- 窗口是每次调用各自按当时的时间算的：`--older-than 0` 这类窗口在 dry-run 与 apply 之间新建的 run 也会被算进去。要严格对齐就先看数字、紧接着执行。
+- 还原归档行后需要一次重嵌入才回到向量检索（排队的语义与写入路径一致：事务中或嵌入器未就绪会延后）。
+- `llmAudit.enabled=false` 时回执不落库（那个开关连审计行的启动期清理一起关掉），但清理照做。
+- 窗口内（默认 7 天）的输入快照不动：近期 run 仍可能在离线回放里被用到。
+- `distill_records` 的窗口用同一个 `--older-than`（默认 7 天），但它的**保留期另有一处**：`distillRecords.retentionDays`（默认 90）在插件启动时裁剪。两处不冲突（启动裁剪是常态、reclaim 是手动瘦身），但别指望只调其中一个就能同时改两边——想一次对齐就把 `--older-than` 显式传成与 `retentionDays` 相同的值。裁剪只删原文，溯源链接留着（详见 [蒸馏原文留存](DISTILL.md)）。
+- `run_type='organize'` 的行任何窗口都不清：它们的 `input` 存的是 apply 的重放载荷（`src/organize.js` 直接读它重建候选索引），不是可重建的快照。置空会让那次 apply 静默空转并把报告锁死。
+
+## 升格吸收的 evidence（#230 × #275）
+
+`memory_register_document` 注册成功后，这份文档引用的 evidence 行会**在同一事务里**翻成归档（absorbed）。一次吸收 20 条，活跃面就少 20 行——而不是「21 行不是 1 行」。
+
+- 只翻标志位：内容、`content_history`、审计行一条不删，随时可以还原；
+- `constraint` / `preference` 永不自动归档（#249 的逐字保真池），要归档得手动来；
+- 只吸收**原子条**：别的 `document` 行与 `summary` 行不碰——前者本体是磁盘上的文件（归档它会让同一路径下次注册留下第二行），后者是 dream 总览与叙述（按 source 身份去重、按注入档位常驻）；
+- 想保留活跃面：工具带 `keep_evidence_active: true`（注册器参数是 `archiveEvidence: false`）；
+- 重注册同一份文档（出新版）时，那些已归档的 evidence 行仍可为**它所属的那份文档**背书；换个文档拿归档 id 当证据，照旧按捏造拒绝。
+
+## 第五指标：归档净增速率 + 可压掉行数
+
+面板「记忆复用」卡与 `GET /api/dsh-mneme/recall-stats` 的返回里多了一个 `archive` 块（#275 拍板：与既有指标同位）：
+
+- `total` / `addedInWindow` / `perDay`：归档区现有行数、窗口内新进的、以及日均净增速率。归档时刻取**精确列 `archived_at`**（#275 第二批落地）：`setArchived` 只在「活跃 → 归档」那一次落值，取消归档清 `NULL`，重复归档不刷新（幂等）——重复归档不是新一次归档，刷新它就会让「对同一行反复调 `setArchived(true)`」又变成一次净增。本指标 v1 曾用行的 `updated_at` 代理（`setArchived` 翻标志位时刷它），偏差方向是**偏高**：对已归档行做一次普通更新，或重复归档，都会被算成「本窗口新进」。`archived_at` 就是为消灭这两个假阳性而加的，读侧**不要**再退回 `updated_at`，也不要写 `archived_at ?? updated_at` 兜底；
+- `undated`：`archived_at` 为 `NULL` 的归档行数——本列落地前就已归档的**存量行**，时刻不可追溯。**刻意不计入 `addedInWindow`**：迁移当刻，窗口内的存量归档行同样是 `NULL`，既无法证明它在窗口内、也无法证明在窗口外。三种处置里选了这个：用 `updated_at` 顶替 = 走回被推翻的代理口径；按 0 充数 = 把「不知道」伪装成「没有」；单列计数让读侧自判可信度，宁少不脏。迁移**不回填**存量行，理由同上——回填等于把代理口径的偏差（偏高）固化成看不见的脏数据，留在 `NULL` 至少是「已知的不可知」；
+- `compressible.rows` / `.groups`：**可压掉行数**——同 type、同 scope、内容归一化后逐字节相同的归档行里，每组留下的那一行之外的那些。判据用内容哈希（与写入准入同一把尺），**不**建在向量近重复上：回收动作本身就会清掉归档行的向量，指标不能指望自己的输入还在。
+
+`archived_at` 只在 `setArchived` 与「入库即归档」（`store.save({archived:true})`，时刻 = 入库时刻）两处落值；`update()` 的 patch **不能**写它（否则给精确口径开了绕过幂等/清空语义的后门）。`updated_at` 的既有语义不动——它仍是「最后一次写」，面板排序、快照哈希、CAS 都读它。
+
+这是观察口，不是动作触发：真删仍属第二批（未立项）。
+
+## 与 #254 的分界
+
+本入口止体积、不止重复。归档区里同主题条目堆积是**出口**问题，归 #254 的写入准入与后续整理动作面；这里一条记忆都不碰（维护者拍板 4）。