@modusensus/dsh-mneme 0.8.6 → 0.8.7

package/lib/maintenance.js

@@ -0,0 +1,142 @@
+// #275 存储生命周期第一批：无损回收的维护入口。
+//
+// 为什么是「手动入口 + dry-run + receipt」而不是后台任务：这两步都是不可逆的内容
+// 丢弃（历史 run 的输入快照置空、归档行的向量置空），该由人在看得见数字的时候按下
+// （维护者 2026-09-23 拍板：不挂启动自动跑，VACUUM 约 0.8s 说明它就该是个随手跑的
+// 东西）。所以模块里没有任何定时器，挂点只有两个：standalone 数据面的
+// `POST /maintenance/reclaim` 与它上面的 `dsh-mneme reclaim` 子命令。
+//
+// 两项都零价值判断、零条数变化：
+//   A `dream_runs.input` 置空。这一列的含义按 run_type 分叉：auto / sleep 的 run 存的
+//     是当时的记忆库快照，可由记忆库重建；**organize 的 run 存的是 apply 的重放载荷**，
+//     置空会让那次 apply 静默空转并把报告锁死，所以 organize 行不在可清范围内（谓词
+//     在 store.dreamRunInputStats / clearDreamRunInputs 里）。run 的骨架、LLM 决策原文
+//     与 receipt 一律保留，行永不删（拍板 3：裁列同意、删行不同意）。
+//   B 归档行向量置空：检索 SQL 恒带 `archived = 0`，这部分向量按定义不可达。它不是
+//     单程票——取消归档时 service 会重新排队嵌入（archiveMemory 的还原分支）。
+//
+// 报告口径（拍板 2）：收益按 VACUUM 前后体积量，不按列字节估——实际释放来自溢出页与
+// 索引页回收，列文本大小只是上界，所以两个数分开报，不混成一个「省了多少」。
+//
+// 与 #254 的分界（拍板 4）：本入口止体积、不止重复。归档区里同主题堆积是出口问题，
+// 归 #254 的写入准入与后续的整理动作面，这里一条记忆都不碰。
+export const RECLAIM_TRIGGER_SOURCE = "maintenance";
+export const RECLAIM_OPERATION_TYPE = "storage_reclaim";
+// 输入快照的默认保留窗口：7 天内仍可能被离线回放（近期 run 的决策上下文），更早的
+// 重建成本低于留存成本。窗口由调用方显式给，不做成配置键——配置键意味着有个周期性
+// 消费者，而本批次刻意不接周期动作。
+export const DEFAULT_INPUT_RETENTION_DAYS = 7;
+
+/**
+ * 无损回收（#275 第一批）。返回一个函数：同一条代码路径跑 dry-run 与执行，dry-run
+ * 只是不落 UPDATE/VACUUM，所以「报出来的数字」与「执行时的数字」出自同一处统计。
+ *
+ * @param {object} deps
+ * @param {object} deps.store 存储层（dreamRunInputStats / clearDreamRunInputs /
+ *   archivedEmbeddingStats / clearArchivedEmbeddings / storageStats / vacuum / saveLlmAudit）
+ * @param {object} [deps.config] 已解析配置（读 llmAudit.enabled：关掉 audit 时不落 receipt）
+ * @param {object} [deps.logger]
+ * @param {() => number} [deps.now] 时钟注入（测试用）
+ */
+export function createMaintenance({ store, config, logger, now = Date.now } = {}) {
+  const warn = (msg) => {
+    try {
+      logger?.warn?.(msg);
+    } catch { /* 日志故障不能影响回收本身 */ }
+  };
+
+  /** receipt 落到 llm_audit_logs（既有 bookkeeping 表，不触发写钩子）。 */
+  function writeReceipt(report) {
+    if (config?.llmAudit?.enabled === false) return null;
+    try {
+      const row = store.saveLlmAudit({
+        trigger_source: RECLAIM_TRIGGER_SOURCE,
+        operation_type: RECLAIM_OPERATION_TYPE,
+        // 不是模型调用，但该列 NOT NULL——用显式占位串，免得混进按路由分组的花费统计。
+        model_id: "-",
+        status: "success",
+        metadata: {
+          older_than_days: report.olderThanDays,
+          cleared: report.cleared,
+          size_before: report.size.before_bytes,
+          size_after: report.size.after_bytes,
+          vacuum: report.vacuum.ran,
+          duration_ms: report.duration_ms
+        }
+      });
+      return row?.id ?? null;
+    } catch (e) {
+      // 回执失败只 warn：清理已经发生了，不能因为记不上账就当作没发生（也不能反噬）。
+      warn(`[dsh-mneme] storage reclaim receipt failed: ${String(e)}`);
+      return null;
+    }
+  }
+
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.olderThanDays] 输入快照的保留窗口（天）；0 = 清掉全部快照
+   * @param {boolean} [opts.vacuum] 是否在清理后 VACUUM（默认否：它要排他锁，由人决定）
+   * @param {boolean} [opts.dryRun] 默认 true——只报数字，不改一个字节
+   * @returns {object} 报告（dry-run 与执行同形状，执行时多 receipt 字段）
+   */
+  function reclaim({ olderThanDays = DEFAULT_INPUT_RETENTION_DAYS, vacuum = false, dryRun = true } = {}) {
+    const days = Number.isFinite(olderThanDays) && olderThanDays >= 0 ? olderThanDays : DEFAULT_INPUT_RETENTION_DAYS;
+    const cutoff = new Date(now() - days * 86400000).toISOString();
+    const started = now();
+    const before = store.storageStats();
+    const inputs = store.dreamRunInputStats(cutoff);
+    const embeddings = store.archivedEmbeddingStats();
+    const report = {
+      dryRun,
+      olderThanDays: days,
+      cutoff,
+      // planned = 这次会动几行；cleared = 实际动了几行（dry-run 恒 0）
+      planned: { dream_run_inputs: inputs.runs, archived_embeddings: embeddings.rows },
+      // 列文本大小：上界，不是回收量（真实释放看下面的 size 差值）
+      column_bytes: { dream_run_inputs: inputs.bytes, archived_embeddings: embeddings.bytes },
+      cleared: { dream_run_inputs: 0, archived_embeddings: 0 },
+      size: {
+        before_bytes: before.fileBytes,
+        after_bytes: before.fileBytes,
+        // 空闲页就是「现在 VACUUM 能立刻收回来的那部分」，带上它 dry-run 才有个能
+        // 参照的量（真实数字仍然只有做完才知道）
+        freelist_pages: before.freelistCount,
+        freelist_bytes: before.freelistCount * before.pageSize,
+        page_count: before.pageCount
+      },
+      vacuum: { requested: vacuum === true, ran: false, duration_ms: null, error: null },
+      receipt: null,
+      duration_ms: 0
+    };
+    if (dryRun) {
+      report.duration_ms = now() - started;
+      return report;
+    }
+    report.cleared.dream_run_inputs = store.clearDreamRunInputs(cutoff);
+    report.cleared.archived_embeddings = store.clearArchivedEmbeddings();
+    if (report.vacuum.requested) {
+      // VACUUM 失败不能把前面的清理一起吞掉：两个 UPDATE 已经各自提交了，此时抛出去
+      // 就是「数据已经不可逆地清了，但没有任何回执」。所以失败记进报告、回执照写，
+      // 让调用方看到「清了 N 行，VACUUM 没跑成」——锁被别的进程占着（SQLITE_BUSY）是
+      // 最常见的成因，重跑一次 --apply --vacuum 即可（清理是幂等的）。
+      try {
+        const result = store.vacuum();
+        report.vacuum.ran = true;
+        report.vacuum.duration_ms = result.duration_ms;
+      } catch (e) {
+        report.vacuum.error = String(e);
+        warn(`[dsh-mneme] storage reclaim vacuum failed: ${String(e)}`);
+      }
+    }
+    const after = store.storageStats();
+    report.size.after_bytes = after.fileBytes;
+    report.size.freelist_pages = after.freelistCount;
+    report.size.freelist_bytes = after.freelistCount * after.pageSize;
+    report.size.page_count = after.pageCount;
+    report.duration_ms = now() - started;
+    report.receipt = writeReceipt(report);
+    return report;
+  }
+
+  return { reclaim };
+}

package/lib/mirror.js

@@ -2,17 +2,37 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "node
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { STR, langOf } from "./lang.js";
+import { PACKAGE_VERSION } from "./version-check.js";
 
 export const TYPE_FILE = {
   preference: "preferences.md",
   project: "projects.md",
   decision: "decisions.md",
   history: "history.md",
-  summary: "summary.md"
+  summary: "summary.md",
+  pitfall: "pitfalls.md",
+  constraint: "constraints.md",
+  rejected_solution: "rejected-solutions.md",
+  pattern: "patterns.md",
+  document: "documents.md"
 };
 
+// 不落镜像的 type。现在是空集：document 由 #296 第二批收进来——第一版排除它的
+// 理由是「镜像块渲染的字段里没有 doc_path，落一个 documents.md 会得到看着完整、
+// 其实找不到文件的视图」，doc_path 进指针行以后这条理由不再成立。这个集合由
+// test/mirror-types.test.js 钉死（TYPES \ TYPE_FILE 必须恰好等于本集合）：将来
+// 新增 type 时必须显式决定它落不落镜像，静默漏掉才是 #278 要修的那种盲区。
+export const MIRROR_EXCLUDED_TYPES = new Set([]);
+
+// 只读视图（#296）：document 的镜像只有指针行（id + 标题 + 摘要首句 + doc_path），
+// 没有可编辑的正文，所以它不参与 readHumanEdits 的人改合并，手工改动一律被下次
+// 同步覆盖；导出/导入也不带它（那两个是 round-trip 通道，见 api.js）。
+export const MIRROR_READONLY_TYPES = new Set(["document"]);
+
 const ESCAPE = /([\\`*_[\]{}()#+.!|>~-])/g;
 const UNESCAPE = new RegExp("\\\\" + ESCAPE.source, "g");
+// 只读视图里摘要首句的字符上限（#296）：够定位就行，长摘要不该把一行撑成一段。
+const POINTER_MAX = 120;
 
 function esc(text) {
   return String(text).replace(ESCAPE, "\\$1");
@@ -22,6 +42,36 @@ function unescape(text) {
   return String(text).replace(UNESCAPE, "$1");
 }
 
+// 元数据标签的唯一来源是 STR.mirrorLabel（lang.js）：渲染按实例语言取，解析两套
+// 都认。下面的正则从那张表现算——旧实现把手写正则与 lang.js 的两处文案分开维护，
+// 加一个字段要改三处，漏改一处那一行就会随 /import 写进 entry 的 content。
+const META_LABELS = [];
+for (const language of Object.keys(STR.mirrorLabel)) META_LABELS.push(...Object.values(STR.mirrorLabel[language]));
+
+function reEsc(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// 元数据行的值必须单行：值里带换行会多出一行，轻则破坏「整段元数据行」的解析契约，
+// 重则伪造出一个条目头（sensitivity 是调用方传入的任意字符串，属信任边界）。
+function oneLine(text) {
+  return String(text).replace(/\s+/g, " ").trim();
+}
+
+// 结构头锚：ID 行紧跟类型行才算条目头（正文里机器格式的 ID 行不会切开块）。
+const ANCHOR_RE = new RegExp(
+  "^- \\*\\*ID\\*\\*: `([^`]+)`\\n- \\*\\*(?:" +
+    [STR.mirrorLabel.zh.type, STR.mirrorLabel.en.type].map(reEsc).join("|") +
+    ")\\*\\*:", "gm"
+);
+// 渲染出的整段元数据行（加字段只需改 lang.js 的 mirrorLabel）。
+const META_RUN_RE = new RegExp(`^(- \\*\\*(?:${META_LABELS.map(reEsc).join("|")})\\*\\*:.*\\n?)+`);
+// 三方合并用的版本令牌（service.syncMirror 比对并发写）。
+const UPDATED_RE = new RegExp(
+  "- \\*\\*(?:" + [STR.mirrorLabel.zh.updated, STR.mirrorLabel.en.updated].map(reEsc).join("|") +
+    ")\\*\\*: ([^\\n]+)"
+);
+
 function renderMemory(m, language = "zh") {
   // last-rendered digest baseline: sha256(title \x00 content). service.js
   // compares the file hash against this to tell "untouched by a human" (machine
@@ -40,6 +90,12 @@ function renderMemory(m, language = "zh") {
   lines.push(`- **${ML.tags}**: ${m.tags.map((t) => `\`${esc(t)}\``).join(" ")}`);
   lines.push(`- **${ML.updated}**: ${m.updated_at}`);
   if (m.source) lines.push(`- **${ML.source}**: ${esc(m.source)}`);
+  // scope / sensitivity 是只读展示字段（#278：sensitivity 的过滤语义另有归属，见
+  // 那条讨论；这里只把值摆出来）。只在真有值时渲染——本机 2843 条里只有 37 条带
+  // scope 标签，无条件渲染会给每条目多添两行空字段。
+  const scopeText = [m.agent_scope, m.workspace_scope].filter(Boolean).map(oneLine).join(" / ");
+  if (scopeText) lines.push(`- **${ML.scope}**: ${scopeText}`);
+  if (m.sensitivity) lines.push(`- **${ML.sensitivity}**: ${oneLine(m.sensitivity)}`);
   lines.push("");
   lines.push(`<!-- mirror-digest: ${digest} -->`);
   lines.push(m.content);
@@ -49,22 +105,76 @@ function renderMemory(m, language = "zh") {
   return lines.join("\n");
 }
 
+/**
+ * 文件头 frontmatter（#278 第一批）。按 type 分文件时一个文件装 N 条，所以
+ * frontmatter 只能落在文件级；条目级元数据仍是块内的 `- **字段**:` 行（见
+ * renderMemory）。
+ *
+ * `covered` / `coverage` 是覆盖范围的自述，必须与这份文本**实际包含的行集**一致：
+ * 磁盘镜像写活跃集（active-only），/export 的文档写全表（all）。说一套写一套比
+ * 没有这个字段更糟——外部工具会照着它聚合条数与标签。
+ *
+ * 键名对齐 OKF v0.2：`type` 是 §4.1 唯一必填键，`tags` 是 §4.1 的推荐键，
+ * `generated.by` / `generated.at` 是 §5.2 的 trust 族。`generated.by` 按 §7 的
+ * actor 约定写 `<producer>/<version>`（所以带版本号）；`generated.at` 按 §5.2 的
+ * 语义只记「内容上次真正变化」，sync 因此只在正文变化时才落盘。v0.2 已用
+ * `generated.at` 取代 v0.1 的 `timestamp`，没有 `updated` 这个顶层键。
+ * `covered` / `coverage` 是 §4.1 允许的 producer 自定义扩展。
+ */
+export function renderFileHeader(type, items, coverage = "active-only") {
+  const tags = [...new Set(items.flatMap((m) => (m.tags ?? []).map(String)))].sort();
+  return [
+    "---",
+    `type: ${type}`,
+    `generated.by: dsh-mneme/${PACKAGE_VERSION}`,
+    `generated.at: ${new Date().toISOString()}`,
+    `covered: ${items.length}`,
+    `coverage: ${coverage}`,
+    `tags: [${tags.map((t) => JSON.stringify(t)).join(", ")}]`,
+    "---",
+    ""
+  ].join("\n");
+}
+
+/**
+ * document 的只读视图一行（#296）：一句话定位 + 文件指针，正文按 doc_path 去读。
+ * 摘要首句按句末标点切，切不出来就整段（超长再按字符数兜底），保证「一行一个
+ * 文档」的形态不被长摘要撑破。
+ */
+function renderPointer(m) {
+  const flat = String(m.content ?? "").replace(/\s+/g, " ").trim();
+  // 句末标点切首句：中文的。！？ 后面通常不跟空格，不能像英文那样要求一个空白
+  // （要求了就一句都切不出来，整段摘要被当成「首句」塞进视图）。英文的 . 仍要求
+  // 后接空白或结尾，免得把 e.g. / v1.2 这类点号当成句末。
+  const first = flat.match(/^.*?(?:[。！？]|[!?]|[.](?=\s|$))|^.*$/s)?.[0] ?? flat;
+  // 按码点切，不按 UTF-16 码元：后者会在 emoji / 代理对中间落刀，落盘成 U+FFFD。
+  const chars = [...first];
+  const summary = chars.length > POINTER_MAX ? `${chars.slice(0, POINTER_MAX).join("")}…` : first;
+  const where = m.doc_path ? ` · \`${oneLine(m.doc_path)}\`` : "";
+  return `- \`${m.id}\` **${oneLine(m.title)}**：${oneLine(summary)}${where}\n`;
+}
+
 /**
  * Render one type's memories into exactly the mirror-file text (header +
  * per-memory blocks, updated_at DESC like sync). sync() writes this to disk;
- * the /export endpoint returns the same text, so an exported markdown is
- * byte-compatible with a mirror file and can be fed straight back through
- * parseHumanEdits → mergeHumanEdits. Unknown type → undefined.
+ * the /export endpoint reuses the same entry blocks for its per-type sections,
+ * so an exported markdown round-trips back through parseHumanEdits →
+ * mergeHumanEdits. Unknown type → undefined.
+ *
+ * `fileHeader: false` 供 /export 用：一个文档只能有一个 frontmatter 块（在文档
+ * 最前，见 api.js 的 /export），所以分节不再各自带文件头。只读 type（#296 的
+ * document）只走磁盘镜像这一条：渲染指针行 + 只读文件头，导出侧不取它。
  */
-export function renderMirrorText(type, memories, language = "zh") {
+export function renderMirrorText(type, memories, language = "zh", { fileHeader = true } = {}) {
   const name = TYPE_FILE[type];
   if (!name) return undefined;
   const items = (memories ?? [])
     .slice()
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-  const header = STR.mirrorHeader[language](name);
-  const body = items.map((m) => renderMemory(m, language)).join("\n");
-  return header + body;
+  const readonly = MIRROR_READONLY_TYPES.has(type);
+  const header = readonly ? STR.mirrorReadonlyHeader[language](name) : STR.mirrorHeader[language](name);
+  const body = items.map((m) => (readonly ? renderPointer(m) : renderMemory(m, language))).join("\n");
+  return (fileHeader ? renderFileHeader(type, items) : "") + header + body;
 }
 
 /**
@@ -91,7 +201,7 @@ export function parseHumanEdits(text) {
   // A body line like "- **ID**: `x`" is not, so it never splits the block
   // or produces a ghost entry.
   // 解析同时接受两种语言的标签：切换语言前渲染的镜像文件仍能合并。
-  const anchors = [...normalized.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*(?:类型|Type)\*\*:/gm)];
+  const anchors = [...normalized.matchAll(ANCHOR_RE)];
   let prevEnd = 0;
   for (let i = 0; i < anchors.length; i++) {
     const anchor = anchors[i];
@@ -109,7 +219,7 @@ export function parseHumanEdits(text) {
     let body = normalized
       .slice(blockStart, blockEnd)
       .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
-      .replace(/^(- \*\*(?:类型|重要性|标签|更新时间|来源|Type|Importance|Tags|Updated|Source)\*\*:.*\n?)+/, "")
+      .replace(META_RUN_RE, "")
       .replace(/^<!-- mirror-digest: [a-f0-9]+ -->\n?/m, "");
     const separators = [...body.matchAll(/^---\s*$/gm)];
     const lastSep = separators[separators.length - 1];
@@ -120,7 +230,7 @@ export function parseHumanEdits(text) {
     // render time — the version token for detecting a concurrent store write
     // during a three-way merge of human edits (see service.syncMirror).
     const block = normalized.slice(blockStart, blockEnd);
-    const updatedMatch = block.match(/- \*\*(?:更新时间|Updated)\*\*: ([^\n]+)/);
+    const updatedMatch = block.match(UPDATED_RE);
     const digestMatch = block.match(/<!-- mirror-digest: ([a-f0-9]+) -->/);
     edits.push({
       id: anchor[1],
@@ -136,6 +246,15 @@ export function parseHumanEdits(text) {
   return edits;
 }
 
+/**
+ * 判断「这份文本的内容有没有变」时忽略 generated.at：它每次渲染都是新时间戳，
+ * 带上它就永远判为变化。其余字节必须逐字相同才算没变——镜像的幂等性（同样的库
+ * 渲染两次得到同样的文件）才是可断言的。
+ */
+function stripGeneratedAt(text) {
+  return String(text).replace(/^generated\.at: .*$/m, "");
+}
+
 export function createMirror(dir, language = "zh") {
   mkdirSync(dir, { recursive: true });
 
@@ -150,7 +269,10 @@ export function createMirror(dir, language = "zh") {
    * this wrapper only owns the "read file → text" side.
    */
   function readHumanEdits(type = undefined) {
-    const types = type ? [type] : Object.keys(TYPE_FILE);
+    // 只读 type 不参与人改合并（#296）：它们的文件里没有可编辑的正文，解析出来的
+    // 指针行文本若被当成「人改」写回库，会污染摘要。整类跳过，包括 type 指定的
+    // 那条调用路径。
+    const types = (type ? [type] : Object.keys(TYPE_FILE)).filter((t) => !MIRROR_READONLY_TYPES.has(t));
     const edits = [];
     for (const t of types) {
       const file = filePath(t);
@@ -182,9 +304,19 @@ export function createMirror(dir, language = "zh") {
           // memories do not "resurrect" via readHumanEdits
           rmSync(file, { force: true });
         } else {
-          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径），磁盘镜像
-          // 与导出文本永远同构。
-          writeFileSync(file, renderMirrorText(type, items, language), "utf8");
+          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径）。
+          const text = renderMirrorText(type, items, language);
+          // 内容没变就不落盘。generated.at 每次渲染都新，无脑写会让编辑器、同步盘
+          // 与 git 在每次业务写后看到全部镜像文件「被外部修改」，而内容其实一字未
+          // 变；按 OKF 的语义它只该记内容变化，未变就保留旧值。这也是同步读 9 个
+          // 小文件的代价，比无谓写 9 次盘便宜。
+          let prev = null;
+          try {
+            prev = readFileSync(file, "utf8");
+          } catch { /* 首次写：读不到就是没有旧文件 */ }
+          if (prev === null || stripGeneratedAt(prev) !== stripGeneratedAt(text)) {
+            writeFileSync(file, text, "utf8");
+          }
         }
         results[type] = { ok: true };
       } catch (error) {

package/lib/recall-stats.js

@@ -5,6 +5,8 @@
 // 新内聚块从第一行就落在自己的文件里，service.js 保留 barrel 出口、调用方零改动。
 // 纯读不写，绝不触发任何 write hook。
 
+import { scopeKeyOf } from "./scope.js";
+
 /**
  * 口径（issue #217 评论 2026-09-18，锚 5bd2dab）：
  *  - Top-N：窗口内 recall_runs.candidates（最终返回集）按 id 计数，join
@@ -20,6 +22,17 @@
  *  - coverage：recallRecordDefault 开启前的窗口算不到，earliestRunAt 为
  *    null（窗口内无回执）或早于窗口起点时，前端标注可信度；扫描行数有
  *    上限，超出标 truncated（degraded 口径），不静默少算。
+ *  - archive（#275 拍板的第五指标，与上面几项同位）：
+ *    · total = 归档区现有行数；addedInWindow / perDay = 窗口内进入归档区的行数
+ *      与其日均（净增速率）。归档时刻只能取 updated_at（setArchived 翻标志位时刷
+ *      它）——这是代理口径：对已归档行做一次 memory_update，或对同一行重复调
+ *      setArchived(…, true)，都会被算成「本窗口新进归档」，perDay 因此偏高。精确
+ *      口径要一个 archived_at 列（schema 变更，属第二批题材），本版不加；真正的
+ *      「净」增本来也要跨快照比 total（物理删除落地后，差值才会由负向变化体现）。
+ *    · compressible = 可压掉行数：同 type、同 scope 三维且内容哈希完全相同的归档
+ *      行里，多出来的那些（每组留一行）。用内容哈希而不是向量近重复，是因为回收
+ *      动作本身会清掉归档行向量（clearArchivedEmbeddings）——指标不能建在它自己
+ *      的输入会被回收掉的数据上；精确重复与 #254 的计量口径同一把尺。
  *
  * @param {object} store - createStore 产物（只调用 listRecallRunsSince / all）
  * @param {{ windowDays?: number, exemptDays?: number }} [options]
@@ -36,7 +49,8 @@ export function recallStats(store, options = {}) {
   const rawSlots = Number(options.maxInjectSlots ?? 5);
   const maxInjectSlots = Number.isInteger(rawSlots) && rawSlots >= 1 ? rawSlots : 5;
   const now = Date.now();
-  const since = new Date(now - windowDays * 86400000).toISOString();
+  const sinceMs = now - windowDays * 86400000;
+  const since = new Date(sinceMs).toISOString();
 
   const { rows: runs, total } = store.listRecallRunsSince(since);
   const hits = new Map(); // id -> { count, title, source }
@@ -67,8 +81,29 @@ export function recallStats(store, options = {}) {
   let activeCount = 0;
   let zombieCount = 0;
   let exemptCount = 0;
+  // 第五指标（#275）：归档区一侧单独累计，分组键与 #254 的去重候选集同构
+  // （type + 哈希 + scope 三维）——可压掉的必须是「本来就会被判成同一件事」的行。
+  let archivedTotal = 0;
+  let archivedInWindow = 0;
+  const hashGroups = new Map();
   for (const m of memories) {
-    if (m.archived || m.forgotten) continue;
+    if (m.archived) {
+      archivedTotal += 1;
+      const archivedMs = Date.parse(m.updated_at ?? "");
+      if (Number.isFinite(archivedMs) && archivedMs >= sinceMs) archivedInWindow += 1;
+      if (m.content_hash) {
+        const key = [
+          m.type ?? "",
+          m.content_hash,
+          scopeKeyOf(m.agent_scope) ?? "",
+          scopeKeyOf(m.workspace_scope) ?? "",
+          scopeKeyOf(m.sensitivity) ?? ""
+        ].join("\u0000");
+        hashGroups.set(key, (hashGroups.get(key) ?? 0) + 1);
+      }
+      continue;
+    }
+    if (m.forgotten) continue;
     const createdMs = Date.parse(m.created_at ?? "");
     // created_at 解析不了时无法证明已过机会期 → 归入豁免，宁漏勿误伤
     if (!Number.isFinite(createdMs) || now - createdMs < EXEMPT_MS) {
@@ -98,6 +133,14 @@ export function recallStats(store, options = {}) {
     .sort((a, b) => b.count - a.count || a.id.localeCompare(b.id))
     .slice(0, 10);
 
+  let compressibleGroups = 0;
+  let compressibleRows = 0;
+  for (const n of hashGroups.values()) {
+    if (n < 2) continue;
+    compressibleGroups += 1;
+    compressibleRows += n - 1;
+  }
+
   return {
     windowDays,
     generatedAt: new Date(now).toISOString(),
@@ -113,6 +156,13 @@ export function recallStats(store, options = {}) {
       slotFillRate: injectRuns > 0 ? injectedCount / (injectRuns * maxInjectSlots) : null
     },
     topRecalled,
+    // #275 第五指标：归档净增速率 + 可压掉行数（口径见文件头）
+    archive: {
+      total: archivedTotal,
+      addedInWindow: archivedInWindow,
+      perDay: Math.round((archivedInWindow / windowDays) * 100) / 100,
+      compressible: { rows: compressibleRows, groups: compressibleGroups }
+    },
     zombie: {
       activeCount,
       zombieCount,

package/lib/scope.js

@@ -34,12 +34,7 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
   };
 
   return function resolveWriteScope(exec) {
-    let session = null;
-    try {
-      session = exec?.agent?.session ?? null;
-    } catch {
-      session = null;
-    }
+    const session = sessionOf(exec);
 
     // 持久化 header（issue #17 的身份契约）：session.header 是创建时冻结的
     // SessionHeader（含 agentPreset/cwd）。⚠️ 不能先读 requestHeader()——那返回
@@ -83,6 +78,39 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
   };
 }
 
+/**
+ * 工具 exec 上的会话对象。宿主 ctx 是 Proxy（cordis 4），裸读未 inject 的属性会
+ * 抛错——所以取值恒包在 try 里，取不到返回 null。scope 解析与写入准入的会话键
+ * 共用这一处取值口径。
+ * @param {object} exec
+ * @returns {object|null}
+ */
+export function sessionOf(exec) {
+  try {
+    return exec?.agent?.session ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 写入准入的会话键（#254 G1 会话写入预算的计数单位）。session_id 在这里只作
+ * 「同一段对话」的标识，不作为作用域键（见文件头：记忆挂在持久化身份标签上）；
+ * 取不到会话身份（系统写入）返回 null = 不进预算。
+ * @param {object} exec
+ * @returns {string|null}
+ */
+export function sessionKeyOf(exec) {
+  // 整个取值（含 .id）都在 try 里：宿主 session 可能是会抛错的 accessor，而这个
+  // 函数在 memory_save 的保存之前被调用——抛出去就是一次工具调用直接失败。
+  try {
+    const id = sessionOf(exec)?.id;
+    return id == null ? null : String(id);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * v0.8.1 底座（issue #170）：显式 scope 参数（memory_save / memory_update /
  * 面板编辑）的归一化。约定：