@modusensus/dsh-mneme 0.8.6 → 0.8.7

package/lib/service.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { TYPE_FILE } from "./mirror.js";
+import { TYPE_FILE, MIRROR_READONLY_TYPES } from "./mirror.js";
 import { updatedAtBounds } from "./store.js";
 import { normalizeExplicitScope, scopeKeyOf } from "./scope.js";
 import { STR, langOf } from "./lang.js";
@@ -29,7 +29,9 @@ const CODING_MEMORY_TYPES = new Set(["rejected_solution", "pitfall", "constraint
 // 注意 constraint 同时属于 CODING_MEMORY_TYPES，非编码任务里已被 codingGate
 // 滤掉，pin 池同样拿不到它；是否豁免该门控是待维护者拍板的口径问题，本批次
 // 不动既有门控（不放大行为面）。
-const PINNED_MEMORY_TYPES = new Set(["constraint", "preference"]);
+// 导出给写入准入（#254 的穿透口）与注入侧共用一份定义：两处各写一份 list 迟早
+// 漂移成「pin 池豁免了、预算没豁免」这类两套口径。
+export const PINNED_MEMORY_TYPES = new Set(["constraint", "preference"]);
 
 /**
  * 判断一段文本是否编码类任务（关键词匹配，codingRetrospect 读取侧门控）。
@@ -167,7 +169,7 @@ export function computeRetrievalMetrics(actualIds, expectedIds) {
   };
 }
 
-export function createService({ store, mirror, config, onWrite, logger }) {
+export function createService({ store, mirror, config, onWrite, logger, documentIndex, writeAdmission }) {
   const language = langOf(config);
   // Optional dream scheduler hook, installed via setDreamHook after creation
   // (the scheduler holds a reference back to the service, so it cannot be
@@ -876,12 +878,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           mode,
           topK: lim,
           threshold: threshold ?? null,
+          // Per-source 信号随回执落盘（fuseRecall 本就无条件计算，此前只服务
+          // signalTransparency 展示）：复用侧查询画像（query 型 → 各路权重的
+          // 离线聚合，AssoMem arXiv 2510.10397 消融所示收益大头）需要这份原料。
+          // 纯加字段——recall_runs 无 schema 变更，旧行 candidates 缺该键照常读。
           candidates: result.map((m) => ({
             id: m.id,
             title: m.title,
             content: m.content,
             score: m.score ?? null,
-            source: m.source ?? "keyword"
+            source: m.source ?? "keyword",
+            signals: signals.get(m.id) ?? {}
           })),
           createdAt: new Date().toISOString()
         });
@@ -1243,6 +1250,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       scheduleEmbed(result);
       return { action: "merged", memory: result };
     }
+    // #254 写入准入（第一阶段只计量）：决策恒 allow、不拦写入，只把两个闸门的
+    // 测量点算出来。放在 store.save 之前——第二阶段要在这里拦下写入，接缝先摆好。
+    // 计量是旁路：任何一环失败只 warn，绝不反噬写入（与质量打分同款容错）。
+    let admission = null;
+    if (writeAdmission) {
+      try {
+        admission = writeAdmission.evaluate({ memory, sessionKey: memory._sessionKey });
+      } catch (e) {
+        try { logger?.warn?.(`[dsh-mneme] write admission evaluate failed: ${String(e)}`); } catch { /* 不反噬 */ }
+      }
+    }
     const created = store.save({
       type: memory.type,
       title: memory.title,
@@ -1263,6 +1281,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       ...(quality ? { quality_score: quality.score } : {})
     });
     const result = applyQualityDisposition(created, quality, qf);
+    if (admission) {
+      try {
+        writeAdmission.record({
+          sessionKey: memory._sessionKey,
+          verdict: admission,
+          memoryId: created.id
+        });
+      } catch (e) {
+        try { logger?.warn?.(`[dsh-mneme] write admission record failed: ${String(e)}`); } catch { /* 不反噬 */ }
+      }
+    }
     afterSync("write");
     notifyWrite();
     scheduleEmbed(result);
@@ -1560,6 +1589,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * Only content/title are taken; structure fields stay machine-owned.
    */
   function mergeHumanEdits(type, edits) {
+    // #296：只读 type 的结构性守卫。调用点（启动合并 / reconcileHumanEdits）都已
+    // 跳过它们，但这条不变量属于「人改回填」本身——将来多一个调用点不该重开这个口
+    // （指针行文本被当正文写回 document 行会污染摘要）。
+    if (MIRROR_READONLY_TYPES.has(type)) return 0;
     let applied = 0;
     for (const edit of edits) {
       if (!edit.id) continue; // corrupt/malformed edit: skip it, keep merging the rest
@@ -1787,6 +1820,26 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * non-forgotten memories are mirrored: forgotten entries must not reach the
    * human-editable file (a human "edit" could otherwise resurrect them).
    */
+  // #296 第二批：documentDir/index.md 的写后语。与注册入口共用同一个
+  // documentMemoryEnabled 闸（默认关）：闸开时只列活跃指针行（正文永远不进这个
+  // 文件），闸关时把索引删掉——document 子系统整体退出，留一份陈旧索引会列出已
+  // 归档的行，正是镜像侧 documents.md 在闸关时被删掉要避免的那种「看着还在、其实
+  // 已关」的视图。两步都只 warn：索引是机器产物，不能让触发它的业务写失败。
+  function syncDocumentIndex() {
+    if (!documentIndex) return;
+    if (config?.documentMemoryEnabled !== true) {
+      const removed = documentIndex.remove();
+      if (!removed?.ok) logger?.warn?.("document index remove failed:", removed?.error);
+      return;
+    }
+    try {
+      const result = documentIndex.sync(store.list({ type: "document", limit: null }));
+      if (!result?.ok) logger?.warn?.("document index sync failed:", result?.error);
+    } catch (error) {
+      logger?.warn?.("document index sync failed:", error);
+    }
+  }
+
   // syncMirror: 同步 mirror，并在失败/成功时持久记录 dirty 状态；保证自身不抛出。
   // v0.3.6（audit peer 4 阻断）：
   //   - 开始时 incrementGeneration 绑定本次期望轮次 gen；成功用
@@ -1796,7 +1849,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   //   - 逐 type 用 setTypeStatus 记录部分成功/失败（type_status JSON）；
   //   - 所有 store 状态写入各自 try/catch，失败只 warn，绝不向外抛（F-NEW-03）。
   function syncMirror() {
-    if (txDepth > 0 || !mirror) return { success: true, deferred: true }; // deferred to the transaction's commit
+    if (txDepth > 0) return { success: true, deferred: true }; // deferred to the transaction's commit
+    // #296 第二批：documentDir/index.md 走同一条写后语——它与镜像一样是「从库渲染
+    // 的机器产物」，同样只在内容变化时落盘、同样自己吞掉失败。放在 !mirror 短路
+    // 之前：索引在不在，不该取决于镜像是否装配（无镜像的宿主与测试同样要有它）。
+    syncDocumentIndex();
+    if (!mirror) return { success: true, deferred: true };
     const now = new Date().toISOString();
     let gen;
     try {
@@ -1812,8 +1870,20 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // 合法的空 Set 可迭代，保证 syncMirror 自身绝不抛（fail-safe）。
     const coveredTypes = new Set();
     try {
-      // 预先获取本次要覆盖的 type 集合（只调一次 store.list）
-      const list = store.list({ limit: 500, includeForgotten: false });
+      // 预先取本次要覆盖的全部活跃行（只读一次）。这里曾经是
+      // store.list({ limit: 500 })——活跃集超过 500 时镜像会静默少掉尾部记忆，
+      // 而文件本身没有任何提示（#278 第一批）。store.list 的 limit 默认值只有
+      // 50，比原来显式传的 500 更小，所以改用 all() 并在这里做同一套过滤
+      // （forgotten/archived 都不进镜像，与 includeForgotten:false + 默认
+      // includeArchived:false 等价）。
+      // 代价是全表读，且落在每次业务写后的最热路径上（#202 自记 all() 5k 行
+      // 231ms → ~135ms）。要压这一层得换按 type 分页取，属另一批的事；
+      // 在这里退回任何截断都不行——「宣称覆盖活跃集」与静默截断不能共存。
+      const list = store.all().filter((m) => !m.forgotten && !m.archived
+        // #296 第二批：镜像里的 documents.md 与 index.md 共用 documentMemoryEnabled
+        // 闸。关掉时把 document 行也从渲染集里去掉——sync 对「空 type」的既有处理
+        // 会把陈旧的 documents.md 删掉，不留一个「看着还在、其实已关」的视图。
+        && (m.type !== "document" || config?.documentMemoryEnabled === true));
       for (const memory of list) {
         if (memory?.type && TYPE_FILE[memory.type]) {
           coveredTypes.add(memory.type);
@@ -2092,6 +2162,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   function archiveMemory(id, f) {
     const updated = store.setArchived(id, f);
     afterSync("write");
+    // #275 B 项：归档行的向量会被手动回收清掉（检索恒带 archived = 0，按定义不可达），
+    // 还原回活跃面时补一次嵌入——否则那行只剩关键词可检索，回收就成了单程票。
+    // 判据用真值（`!f`）而不是 `f === false`：store.setArchived 自己就是按真值归一
+    // （`archived ? 1 : 0`），API/工具传 0 或空串同样会把行放回活跃面，口径必须同一把尺。
+    // 排队语义与写入路径同一处（txDepth / 未就绪由 scheduleEmbed 自己挡）。
+    if (!f) scheduleEmbed(updated);
     return updated;
   }
 
@@ -2105,6 +2181,9 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     embedQuery,
     pushContentHistory,
     transaction,
+    // #275 拍板 5：升格吸收的 evidence 行随之归档，但 pinned 池（#249）永不自动归档
+    // ——注册器不 import 这个集合，方向反了会成环，所以在这里注入。
+    pinnedTypes: PINNED_MEMORY_TYPES,
     finalize: (rows) => {
       for (const row of rows) scheduleEmbed(row);
     }

package/lib/settings.js

@@ -45,7 +45,8 @@ const FEATURE_FLAG_BOOLEANS = [
   "hotMemoryEnabled",
   // Issue #239 第 5 项：注入条数的查询自适应（确定性强则收缩注入条数，默认关）。
   "injectUncertaintyAdaptive",
-  // Issue #249 第一批：能力说明（工具描述判断指引 + order 150 总则段，默认关）。
+  // Issue #249：能力说明（工具描述判断指引 + order 150 总则段）。第二批起它是
+  // 注入父开关 autoInject 的子项、默认开（父关时不生效，闸门见 config.js）。
   "injectGuidanceEnabled",
   "entityExtractionEnabled",
   // Issue #219：图召回轴——查询命中实体名时把挂联记忆并入检索融合池

package/lib/store.js

@@ -1,5 +1,7 @@
 import { DatabaseSync } from "node:sqlite";
 import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { contentHashOf } from "./content-hash.js";
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS memories (
@@ -13,6 +15,7 @@ CREATE TABLE IF NOT EXISTS memories (
   archived    INTEGER NOT NULL DEFAULT 0,
   source      TEXT,
   content_history TEXT,
+  content_hash TEXT,
   embedding   TEXT,
   epistemic_status TEXT NOT NULL DEFAULT 'subjective',
   last_accessed_at  TEXT,
@@ -192,7 +195,8 @@ CREATE TABLE IF NOT EXISTS llm_audit_logs (
   status            TEXT NOT NULL,          -- success | error | skipped
   error_message     TEXT,
   related_memory_ids TEXT,                  -- JSON: ids the call operated on
-  metadata          TEXT                    -- JSON: free-form extras
+  metadata          TEXT,                   -- JSON: free-form extras
+  session_key       TEXT                    -- #254 写入准入的会话键（LLM 调用行恒 NULL）
 );
 CREATE INDEX IF NOT EXISTS idx_llm_audit_timestamp ON llm_audit_logs(timestamp);
 CREATE INDEX IF NOT EXISTS idx_llm_audit_source ON llm_audit_logs(trigger_source);
@@ -405,6 +409,7 @@ function toRow(row) {
     type: row.type,
     title: row.title,
     content: row.content,
+    content_hash: row.content_hash ?? undefined,
     tags: parseTags(row.tags),
     importance: row.importance,
     forgotten: row.forgotten === 1,
@@ -607,7 +612,9 @@ function toLlmAudit(row) {
     status: row.status,
     error_message: row.error_message ?? undefined,
     related_memory_ids: parseJsonArray(row.related_memory_ids),
-    metadata
+    metadata,
+    // #254 写入准入的会话键；LLM 调用行恒 NULL。
+    session_key: row.session_key ?? undefined
   };
 }
 
@@ -711,6 +718,34 @@ export function createStore(path) {
   addColumn("memories", "workspace_scope_source", "ALTER TABLE memories ADD COLUMN workspace_scope_source TEXT");
   addColumn("memories", "scope_decided_at", "ALTER TABLE memories ADD COLUMN scope_decided_at TEXT");
 
+  // #254 计量信号：内容归一化哈希（口径与动机写在 content-hash.js 的文件头）。派生
+  // 列，不参与任何判定——只给「同一内容又被写了一次」当等值锚。索引建在加列之后：
+  // 老库打开时 SCHEMA 的 CREATE TABLE 对既有表不生效，列还不存在，把索引写进 SCHEMA
+  // 会直接报 no such column（与下方 llm_audit_logs.session_key 同理）。
+  addColumn("memories", "content_hash", "ALTER TABLE memories ADD COLUMN content_hash TEXT");
+  // 列序是 content_hash 打头：哈希几乎唯一，等值 seek 就已收窄到候选行，type 只当同
+  // 一次 seek 里的第二列过滤；反过来（type 打头）下面的存量回填就得全表扫——每次打开
+  // 都要把全部正文读一遍。
+  db.exec("CREATE INDEX IF NOT EXISTS idx_memories_content_hash ON memories(content_hash, type)");
+  // 存量回填：老库（含归档区）的行都没有值，而「归档行纳入去重候选集」这条口径正是
+  // 要靠既有归档行出数据。只算 NULL 行、幂等；改口径不是补 NULL 能修好的，要整列重算
+  // （见 content-hash.js 的文件头）。空标题空正文的行算不出锚，跳过不写——否则每次
+  // 打开都要为这些行再跑一遍 UPDATE。
+  {
+    const updates = db
+      .prepare("SELECT id, title, content FROM memories WHERE content_hash IS NULL")
+      .all()
+      .map((row) => [contentHashOf(row), row.id])
+      .filter(([hash]) => hash);
+    if (updates.length) {
+      const stmt = db.prepare("UPDATE memories SET content_hash = ? WHERE id = ? AND content_hash IS NULL");
+      // 一个事务包住整批：逐条自动提交是每行一次 WAL 提交，几千行的存量库上纯属浪费。
+      runAtomically(() => {
+        for (const [hash, id] of updates) stmt.run(hash, id);
+      });
+    }
+  }
+
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   addColumn("dream_runs", "policy_epoch", "ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
   addColumn("dream_runs", "run_type", "ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
@@ -724,6 +759,13 @@ export function createStore(path) {
   addColumn("mirror_state", "applied_generation", "ALTER TABLE mirror_state ADD COLUMN applied_generation INTEGER NOT NULL DEFAULT 0");
   addColumn("mirror_state", "type_status", "ALTER TABLE mirror_state ADD COLUMN type_status TEXT");
 
+  // #254 写入准入（第一阶段只计量）：准入决策行按会话聚合——「会话内新建了几行」
+  // 与「同话题重复间隔」都靠它算出来，所以会话键必须是可等值查询的列，而不是塞在
+  // metadata 里做 JSON 匹配。列可空且不带 DEFAULT（存量行零重写）。索引建在加列
+  // 之后：老库打开时列还不存在（SCHEMA 的 CREATE TABLE 只对新建库生效）。
+  addColumn("llm_audit_logs", "session_key", "ALTER TABLE llm_audit_logs ADD COLUMN session_key TEXT");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_llm_audit_session ON llm_audit_logs(session_key);");
+
   // Audit peer F: a legacy DB may hold a non-integer generation/applied_generation
   // (pre-v0.3.9 the JS gate truncated with Math.trunc and SQLite's CHECK only
   // enforced >= 0). Such a value is ambiguous — it cannot map to a real applied
@@ -942,6 +984,8 @@ export function createStore(path) {
     const importance = Number.isInteger(memory.importance) ? memory.importance : 3;
     const evidence = Array.isArray(memory.evidence) ? JSON.stringify(memory.evidence) : null;
     const docPath = typeof memory.doc_path === "string" && memory.doc_path.trim() ? memory.doc_path : null;
+    // #254 计量锚：由本行的 title/content 派生，调用方传什么都以这里算出的为准。
+    const contentHash = contentHashOf(memory);
     const embedding = Array.isArray(memory.embedding) && memory.embedding.length
       ? JSON.stringify(memory.embedding)
       : null;
@@ -952,8 +996,8 @@ export function createStore(path) {
       : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, content_hash, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         id,
         type,
@@ -976,6 +1020,7 @@ export function createStore(path) {
         normalizeOccurredAt(memory.occurred_at),
         evidence,
         docPath,
+        contentHash,
         now,
         now
       );
@@ -988,6 +1033,41 @@ export function createStore(path) {
     return getById(id);
   }
 
+  /**
+   * #254 计量：与本次写入「归一化内容哈希」相同的既有行（去重候选集）。
+   * 结构化锚先收窄成本：按哈希等值 seek（走 idx_memories_content_hash，哈希几乎唯
+   * 一，落在候选集上的行只有几条），再按 type 与 scope 三维过滤——不是全表扫、也不
+   * 逐行比哈希。scope 用 IS 比（NULL 安全）：未标注行互相匹配、与已标注行不匹配，
+   * 与 service.js 去重键（scopeKeyOf）同口径；入参先按 store 自己的 normalizeScopeText
+   * 归一，免得调用方传 " foo " 就漏配。
+   * 归档行与已遗忘行都在集内：#275 的分界是「出口止体积、不止重复」——被质量闸归档
+   * 的同一个事实必须仍能判成重复，否则同样的内容再写一次又是一条新行（#254 拍板：
+   * 归档行纳入去重候选集）。
+   * 排序即取舍：活跃行排在归档/遗忘行之前，再按 updated_at 倒序。LIMIT 先于调用方的
+   * 「活区优先」判断执行，而归档动作本身会顶 updated_at——纯按时间倒序时，同键命中一
+   * 旦超过窗口宽度，活跃行就被归档行挤出候选集，调用方只能看到归档命中，把「活跃重复」
+   * 误报成「归档重复」，恰好把这条信号要分流的两类弄反。
+   * @returns {Array<{id: string, archived: boolean, forgotten: boolean}>} 活跃行优先，其后按最近写入
+   */
+  function findContentHashMatches({ type, hash, agent_scope: agentScope, workspace_scope: workspaceScope, sensitivity, limit = 10 } = {}) {
+    if (!hash || !type) return [];
+    const lim = Number.isInteger(limit) && limit > 0 ? Math.min(limit, 50) : 10;
+    const rows = db.prepare(
+      `SELECT id, archived, forgotten FROM memories
+       WHERE type = ? AND content_hash = ?
+         AND agent_scope IS ? AND workspace_scope IS ? AND sensitivity IS ?
+       ORDER BY archived ASC, forgotten ASC, updated_at DESC, id LIMIT ?`
+    ).all(
+      type,
+      hash,
+      normalizeScopeText(agentScope),
+      normalizeScopeText(workspaceScope),
+      normalizeScopeText(sensitivity),
+      lim
+    );
+    return rows.map((row) => ({ id: row.id, archived: row.archived === 1, forgotten: row.forgotten === 1 }));
+  }
+
   function update(id, patch) {
     const existing = getById(id);
     if (!existing) throw new Error(`memory not found: ${id}`);
@@ -1034,13 +1114,18 @@ export function createStore(path) {
     const nextDecidedAt = patch.scope_decided_at !== undefined
       ? normalizeOccurredAt(patch.scope_decided_at)
       : (existing.scope_decided_at ?? null);
+    // #254：标题或正文变了，锚跟着重算——它是当前内容的派生物，留旧值等于让「这行
+    // 现在装的什么」和标记对不上。
+    const nextTitle = patch.title ?? existing.title;
+    const nextContent = patch.content ?? existing.content;
+    const contentHash = contentHashOf({ title: nextTitle, content: nextContent });
     runAtomically(() => {
       db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, agent_scope=?, workspace_scope=?, agent_scope_source=?, workspace_scope_source=?, scope_decided_at=?, evidence=?, updated_at=? WHERE id=?`
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, agent_scope=?, workspace_scope=?, agent_scope_source=?, workspace_scope_source=?, scope_decided_at=?, evidence=?, content_hash=?, updated_at=? WHERE id=?`
       ).run(
         type,
-        patch.title ?? existing.title,
-        patch.content ?? existing.content,
+        nextTitle,
+        nextContent,
         JSON.stringify(patch.tags ?? existing.tags),
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
@@ -1054,6 +1139,7 @@ export function createStore(path) {
         nextWorkspaceSource,
         nextDecidedAt,
         evidence,
+        contentHash,
         now,
         id
       );
@@ -1115,15 +1201,19 @@ export function createStore(path) {
     // dirty == false — recoverMirror sees no debt and the mirror stays stale.
     // Wrapping both in one transaction means a CAS miss rolls back cleanly too
     // (no write, no generation bump).
+    // 同 update：#254 的锚随标题/正文重算（CAS 路径也改这两列）。
+    const nextTitle = patch.title ?? existing.title;
+    const nextContent = patch.content ?? existing.content;
+    const contentHash = contentHashOf({ title: nextTitle, content: nextContent });
     let applied = false;
     runAtomically(() => {
       const result = db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, updated_at=?
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, content_hash=?, updated_at=?
          WHERE id=? AND updated_at=?`
       ).run(
         type,
-        patch.title ?? existing.title,
-        patch.content ?? existing.content,
+        nextTitle,
+        nextContent,
         JSON.stringify(patch.tags ?? existing.tags),
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
@@ -1131,6 +1221,7 @@ export function createStore(path) {
         qualityScore,
         embedding,
         epistemicStatus,
+        contentHash,
         now,
         id,
         expectedUpdatedAt
@@ -1182,15 +1273,15 @@ export function createStore(path) {
   function demoteToSummary(id, summary, { minRefTimeMs } = {}) {
     let changed = false;
     runAtomically(() => {
-      const row = db.prepare("SELECT last_accessed_at, content, _full_content FROM memories WHERE id = ?").get(id);
+      const row = db.prepare("SELECT title, last_accessed_at, content, _full_content FROM memories WHERE id = ?").get(id);
       if (!row || row._full_content) return;
       if (minRefTimeMs !== undefined && row.last_accessed_at) {
         const lastMs = Date.parse(row.last_accessed_at);
         if (lastMs >= minRefTimeMs) return; // touched after snapshot — still hot
       }
       db.prepare(
-        "UPDATE memories SET content = ?, _full_content = ?, updated_at = ? WHERE id = ?"
-      ).run(summary, row.content, nowIso(), id);
+        "UPDATE memories SET content = ?, _full_content = ?, content_hash = ?, updated_at = ? WHERE id = ?"
+      ).run(summary, row.content, contentHashOf({ title: row.title, content: summary }), nowIso(), id);
       incrementGeneration();
       changed = true;
     });
@@ -1201,11 +1292,11 @@ export function createStore(path) {
   function restoreContent(id) {
     let changed = false;
     runAtomically(() => {
-      const row = db.prepare("SELECT content, _full_content FROM memories WHERE id = ?").get(id);
+      const row = db.prepare("SELECT title, content, _full_content FROM memories WHERE id = ?").get(id);
       if (!row || !row._full_content) return;
       db.prepare(
-        "UPDATE memories SET content = ?, _full_content = NULL, updated_at = ? WHERE id = ?"
-      ).run(row._full_content, nowIso(), id);
+        "UPDATE memories SET content = ?, _full_content = NULL, content_hash = ?, updated_at = ? WHERE id = ?"
+      ).run(row._full_content, contentHashOf({ title: row.title, content: row._full_content }), nowIso(), id);
       incrementGeneration();
       changed = true;
     });
@@ -1766,8 +1857,8 @@ export function createStore(path) {
     db.prepare(
       `INSERT INTO llm_audit_logs (timestamp, trigger_source, operation_type, model_id,
         input_tokens, output_tokens, total_tokens, cost_usd, duration_ms, status,
-        error_message, related_memory_ids, metadata)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        error_message, related_memory_ids, metadata, session_key)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       entry.timestamp ?? now,
       entry.trigger_source,
@@ -1783,12 +1874,13 @@ export function createStore(path) {
       JSON.stringify(entry.related_memory_ids ?? []),
       entry.metadata !== undefined
         ? (typeof entry.metadata === "string" ? entry.metadata : JSON.stringify(entry.metadata))
-        : null
+        : null,
+      entry.session_key ?? null
     );
     return toLlmAudit(db.prepare("SELECT * FROM llm_audit_logs ORDER BY id DESC LIMIT 1").get());
   }
 
-  function listLlmAudits({ limit = 50, offset = 0, source } = {}) {
+  function listLlmAudits({ limit = 50, offset = 0, source, sessionKey } = {}) {
     const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
     const clauses = [];
     const params = [];
@@ -1796,6 +1888,11 @@ export function createStore(path) {
       clauses.push("trigger_source = ?");
       params.push(source);
     }
+    // #254 写入准入：会话内的话题回填只需要该会话的行（走 idx_llm_audit_session）。
+    if (sessionKey) {
+      clauses.push("session_key = ?");
+      params.push(sessionKey);
+    }
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     const rows = db.prepare(
       `SELECT * FROM llm_audit_logs ${where} ORDER BY timestamp DESC, id DESC LIMIT ? OFFSET ?`
@@ -1803,13 +1900,17 @@ export function createStore(path) {
     return rows.map(toLlmAudit);
   }
 
-  function countLlmAudits({ source } = {}) {
+  function countLlmAudits({ source, sessionKey } = {}) {
     const clauses = [];
     const params = [];
     if (source) {
       clauses.push("trigger_source = ?");
       params.push(source);
     }
+    if (sessionKey) {
+      clauses.push("session_key = ?");
+      params.push(sessionKey);
+    }
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     return db.prepare(`SELECT count(*) AS c FROM llm_audit_logs ${where}`).get(...params).c;
   }
@@ -1858,6 +1959,106 @@ export function createStore(path) {
     return db.prepare("DELETE FROM llm_audit_logs WHERE timestamp < ?").run(before).changes;
   }
 
+  // --- 存储生命周期：无损回收（#275 第一批）--------------------------------
+  //
+  // 两项都零价值判断、零条数变化：行数不变，只把不可重建/不可达的内容丢掉。
+  // 删行不在本模块里（维护者拍板 3：裁列同意、删行不同意）——dream_runs 的骨架、
+  // LLM 决策原文与 receipt 永不删。
+
+  /**
+   * 历史 run 的输入快照统计（#275 A 项，dry-run 用）。
+   *
+   * `input` 这一列的含义**按 run_type 分叉**：auto / sleep 的 run 存的是当时的记忆库
+   * 快照（可由记忆库重建），organize 的 run 存的是 apply 的重放载荷——`organize.js`
+   * 的 apply 直接读它（`snapshot = Array.isArray(report.input) ? report.input : []`），
+   * 置空会让 apply 找不到候选、静默什么都不做却照写回执并盖上 applied_at，那份报告
+   * 从此永远重放不了。所以 organize 行不在可清范围里（同一列，两种语义，只能按 type 分）。
+   *
+   * `bytes` 是列文本大小，只作上界（真实释放看 VACUUM 前后）。
+   * @returns {{runs: number, bytes: number}}
+   */
+  function dreamRunInputStats(before) {
+    const row = db.prepare(
+      `SELECT count(*) AS c, COALESCE(SUM(LENGTH(input)), 0) AS b
+         FROM dream_runs
+        WHERE input IS NOT NULL AND created_at < ? AND run_type != 'organize'`
+    ).get(before);
+    return { runs: row.c, bytes: row.b };
+  }
+
+  /** 置空历史 run 的输入快照（organize 的重放载荷除外）。返回实际改动的行数。 */
+  function clearDreamRunInputs(before) {
+    return db.prepare(
+      `UPDATE dream_runs SET input = NULL
+        WHERE input IS NOT NULL AND created_at < ? AND run_type != 'organize'`
+    ).run(before).changes;
+  }
+
+  /**
+   * 归档行仍带的向量统计（#275 B 项）。检索 SQL 恒带 `archived = 0`，所以这部分
+   * 向量按定义不可达，清掉不改变任何检索结果。
+   * @returns {{rows: number, bytes: number}}
+   */
+  function archivedEmbeddingStats() {
+    const row = db.prepare(
+      `SELECT count(*) AS c, COALESCE(SUM(LENGTH(embedding)), 0) AS b
+         FROM memories WHERE archived = 1 AND embedding IS NOT NULL`
+    ).get();
+    return { rows: row.c, bytes: row.b };
+  }
+
+  /** 清掉归档行的向量。返回实际改动行数。 */
+  function clearArchivedEmbeddings() {
+    const changed = db.prepare(
+      "UPDATE memories SET embedding = NULL WHERE archived = 1 AND embedding IS NOT NULL"
+    ).run().changes;
+    // Issue #202 的单条失效点在 setEmbedding 里，批量清走不到它——整表清缓存最省事，
+    // 代价只是活跃行下次检索多解析一次（FIFO 上限 4000，自愈）。
+    if (changed > 0) embeddingCache.clear();
+    return changed;
+  }
+
+  /**
+   * 库文件与页统计（#275 报告口径）：回收收益按 VACUUM 前后体积量，不按列字节估——
+   * 实际释放来自溢出页与索引页的回收，列文本大小只是上界。
+   *
+   * 体积是**磁盘足迹**：WAL 模式下主文件之外还有 `-wal` / `-shm`，只量主文件会把
+   * 「刚清完还没落盘」的那部分算漏（实测过：VACUUM 后主文件可能一动不动，要等一次
+   * checkpoint）。所以三份一起量；`:memory:` 库没有文件。
+   */
+  function storageStats() {
+    const pageSize = db.prepare("PRAGMA page_size").get().page_size;
+    const pageCount = db.prepare("PRAGMA page_count").get().page_count;
+    const freelistCount = db.prepare("PRAGMA freelist_count").get().freelist_count;
+    const sizeOf = (p) => {
+      try {
+        return statSync(p).size;
+      } catch {
+        return 0;
+      }
+    };
+    let fileBytes = null;
+    if (typeof path === "string" && path !== ":memory:") {
+      fileBytes = sizeOf(path) + sizeOf(`${path}-wal`) + sizeOf(`${path}-shm`);
+    }
+    return { path: typeof path === "string" ? path : null, pageSize, pageCount, freelistCount, fileBytes };
+  }
+
+  /**
+   * 整库 VACUUM（#275 的手动步骤）：代价 O(库大小) 且需要排他写锁，所以只在显式
+   * 入口里跑，绝不挂启动路径、也不开 auto_vacuum。
+   *
+   * 收尾补一次 `wal_checkpoint(TRUNCATE)`：WAL 模式下 VACUUM 重排的是主文件里的页，
+   * 已回收的空间可能还挂在 WAL 里，不 checkpoint 就量不到体积下降——报告口径要的是
+   * 真实释放量，量不到等于没做（评审实测：VACUUM 后主文件长度不变，checkpoint 后才降）。
+   */
+  function vacuum() {
+    const started = Date.now();
+    db.exec("VACUUM");
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    return { duration_ms: Date.now() - started };
+  }
+
   // --- failure memories ----------------------------------------------------
 
   /**
@@ -2485,6 +2686,8 @@ export function createStore(path) {
     saveDocument,
     update,
     compareAndUpdate,
+    // #254：写入准入的内容哈希候选集（只读）。
+    findContentHashMatches,
     remove,
     setForget,
     setArchived,
@@ -2523,6 +2726,13 @@ export function createStore(path) {
     countLlmAudits,
     getLlmAuditStats,
     deleteOldLlmAudits,
+    // 存储生命周期（#275 第一批）：无损回收的统计、清理与体积口径。
+    dreamRunInputStats,
+    clearDreamRunInputs,
+    archivedEmbeddingStats,
+    clearArchivedEmbeddings,
+    storageStats,
+    vacuum,
     saveFailure,
     listFailures,
     getFailureStats,