@modusensus/dsh-mneme 0.12.0 → 0.13.0

package/lib/store.js

@@ -432,7 +432,10 @@ CREATE INDEX IF NOT EXISTS idx_distill_runs_created ON distill_runs(created_at);
 --   · 本表 = 行级，「这条记忆出生自哪一轮」，覆盖没有窗口的铸造路径。
 -- 只填 **create** 一种动作：merge/conflict/update/supersede 对既有行的改动，receipt_chain
 -- 已经按 (run_id, record_id) 记过了——再造一份就是第二套账。create 是那边唯一的洞
--- （buildOutcome 刻意不给 create 派 disposition，receipt_chain 也就不产行）。
+-- （buildRecordReceipts 不给 create/create_merged 产行：新行没有「改动前后的账」可记，
+-- 只有「出生自哪一轮」，那正是本表的事）。#619 起 buildOutcome 会给 create 派
+-- disposition（created / created-refreshed），那是审计面读的结果，与 receipt_chain
+-- 产不产行是两件事；created-refreshed 是原地刷新，没有出生，本表也不记。
 -- run_type / trigger_source 就地冗余：run_id 在 dream_runs 与 distill_runs 两张表里
 -- 各有自己的主键域，读侧不该为了显示一个类型去 union 两张审计表。
 -- ON DELETE CASCADE：记忆行没了，归因没有指代对象；remove() 仍显式清（与
@@ -706,6 +709,59 @@ CREATE TABLE IF NOT EXISTS profile_fact_runs (
   finished_at    TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_profile_fact_runs_card ON profile_fact_runs(agent_key, started_at);
+
+-- ============================================================
+-- knowledge base（知识库第二层，spec: docs/plans/2026-11-08-kb-qoder-parity.md §3.3）。
+-- 与记忆行物理隔离的硬边界同 choro 那组表：kb 的行永不进 memories /
+-- saveWithDedupe / dream / 质量过滤的任何池子。这里存的是「用户/agent 主动
+-- 收进知识库的资料」——文件、网页、仓库地志页的**副本**与索引，天生属于外来
+-- 原文，让巩固流程够得着它就会把用户刚存的手册自己归档掉。
+-- 幂等键是 (collection_id, rel_key)：同一来源重入库按 sha256 判 no-op，
+-- 变了才替换 chunks（替换语义在 replaceKbDoc 里，事务包住删除与插入）。
+-- rel_key 是来源的稳定相对键（本地文件=绝对路径、网页=URL、地志页=repo#slug），
+-- 不是展示名——展示名在 kb_docs.title。
+CREATE TABLE IF NOT EXISTS kb_collections (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  key         TEXT NOT NULL,
+  title       TEXT NOT NULL,
+  description TEXT,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_kb_collections_key ON kb_collections(key);
+
+-- kind 限定三类（§3.3）：file | url | choro_page。sha256 是**正文内容**的哈希，
+-- 不是文件 stat 的指纹——文件 mtime 变了内容没变时重入库必须是 no-op，
+-- 否则每次保存键盘敲一下都全量重切块。
+CREATE TABLE IF NOT EXISTS kb_docs (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  collection_id INTEGER NOT NULL,
+  rel_key       TEXT NOT NULL,
+  kind          TEXT NOT NULL,
+  source_path   TEXT,
+  title         TEXT NOT NULL,
+  bytes         INTEGER NOT NULL DEFAULT 0,
+  sha256        TEXT,
+  indexed_at    TEXT NOT NULL,
+  status        TEXT NOT NULL DEFAULT 'ok',
+  error         TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_kb_docs_collection_relkey ON kb_docs(collection_id, rel_key);
+
+-- 分块正文。heading 是块所属的二级标题节（无节则空串），ordinal 是块在
+-- 文档内的序号——检索命中要能回指「第几块、哪一节」，面板/工具靠它跳段落。
+-- text 存原文切片（含分块时带的标题行？不含：标题在 heading 里，text 只放正文，
+-- 免得同一条命中把标题算两遍）。
+CREATE TABLE IF NOT EXISTS kb_chunks (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  doc_id     INTEGER NOT NULL,
+  ordinal    INTEGER NOT NULL,
+  heading    TEXT NOT NULL DEFAULT '',
+  text       TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_kb_chunks_doc_ordinal ON kb_chunks(doc_id, ordinal);
+
 `;
 
 // Exported for API-layer type validation (standalone API POST /memories and
@@ -960,6 +1016,10 @@ function toConflictPending(row) {
     memory_a: row.memory_a,
     memory_b: row.memory_b,
     reason: row.reason ?? undefined,
+    // Issue #603 第 2 层：入队时的相似度。存量行与调用方没给的行是 NULL，
+    // 这里如实透出 undefined（条件展开：带 undefined 键会让 in-process schema
+    // 校验判违规，同 toApiList 的处理）。
+    ...(typeof row.similarity === "number" ? { similarity: row.similarity } : {}),
     created_at: row.created_at,
     resolved_at: row.resolved_at ?? undefined,
     resolved_winner: row.resolved_winner ?? undefined
@@ -1493,6 +1553,18 @@ export function createStore(path) {
   addColumn("memory_provenance", "distill_run_id", "ALTER TABLE memory_provenance ADD COLUMN distill_run_id TEXT");
   db.exec("CREATE INDEX IF NOT EXISTS idx_memory_provenance_run ON memory_provenance(distill_run_id);");
 
+  // Issue #603 第 2 层：冲突待审队列此前只能按 created_at 倒序排。一次 sleep 轮次
+  // 里产出的对全部落在同一毫秒（实测 60 条挤在 60ms 内），排序键全同，队列在面板
+  // 上看起来是随机的——而「哪一对最该先看」的唯一客观信号是相似度，此前只存在
+  // reason 文本里（「相似度 0.87」），前端靠正则回收。落成列之后排序键是数据，
+  // 不是解析结果。
+  //
+  // 可空且不带 DEFAULT：存量行没有这个信息，NULL = 「入队时没记」（比填 0 诚实——
+  // 0 会被排到最后，等于替用户断言「这两条毫不相似」）。排序用 NULLS LAST。
+  addColumn("conflict_pending", "similarity", "ALTER TABLE conflict_pending ADD COLUMN similarity REAL");
+  // 索引建在加列之后（同 idx_memory_provenance_run 的理由）：老库打开时列才刚加上。
+  db.exec("CREATE INDEX IF NOT EXISTS idx_conflict_pending_similarity ON conflict_pending(similarity DESC, created_at DESC);");
+
   // 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
@@ -1714,13 +1786,12 @@ export function createStore(path) {
     return db.prepare("DELETE FROM distill_parse_failures WHERE session_id = ?").run(sessionId).changes;
   }
 
-  function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
-    const clauses = [];
-    const params = [];
-    if (type !== undefined) {
-      clauses.push("type = ?");
-      params.push(type);
-    }
+  // #597：count() 与 countByType() 共用的 WHERE 构造——两张 HTTP 面（宿主内 /list
+  // 与 Bearer /memories）的 total 与 typeCounts 必须同口径，分布的合计才等于总数。
+  // type 刻意不在这里：count() 按调用方带，countByType() 刻意不带（它要的就是
+  // 同一份筛选下、**不带类型**的全库分布——面板分类栏被 type 筛过的页上数不出它）。
+  function pushCountFilters(opts, clauses, params) {
+    const { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = opts ?? {};
     // Same filters as list() so a paged caller's total matches its rows.
     if (minImportance != null) {
       clauses.push("importance >= ?");
@@ -1786,10 +1857,32 @@ export function createStore(path) {
         "(id IN (SELECT record_id FROM receipt_chain WHERE kind IN ('merge', 'update') AND verdict = 'live') OR source = 'dream')"
       );
     }
+  }
+
+  function count(type, opts = {}) {
+    const clauses = [];
+    const params = [];
+    if (type !== undefined) {
+      clauses.push("type = ?");
+      params.push(type);
+    }
+    pushCountFilters(opts, clauses, params);
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     return db.prepare(`SELECT count(*) AS c FROM memories ${where}`).get(...params).c;
   }
 
+  // #597（/list 的 typeCounts）：同一份筛选、不带 type，一次 GROUP BY 拿全库分布。
+  // 面板分类栏的数字源：被 type 筛过又分过页的已加载行上数不出真分布。GROUP BY
+  // 只回存在的类，缺类即 0；分布合计恒等于同筛选的 count(undefined)。
+  function countByType(opts = {}) {
+    const clauses = [];
+    const params = [];
+    pushCountFilters(opts, clauses, params);
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(`SELECT type, count(*) AS c FROM memories ${where} GROUP BY type`).all(...params);
+    return Object.fromEntries(rows.map((r) => [r.type, r.c]));
+  }
+
   function getById(id) {
     const row = db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
     return toRow(row);
@@ -2575,6 +2668,30 @@ export function createStore(path) {
     return needsEmbeddingFor(modelHash, 1).length > 0;
   }
 
+  /**
+   * How many rows needsEmbeddingFor() would pick in total.
+   *
+   * A re-index run is bounded by a limit, so "indexed: 0" and "indexed: 3 of
+   * 300" looked identical to the caller. Counting is cheap (no content is
+   * materialised) and is what lets the caller say how much work is left.
+   */
+  function countNeedsEmbeddingFor(modelHash) {
+    if (!modelHash) {
+      return db.prepare(
+        `SELECT count(*) AS c FROM memories
+         WHERE (embedding IS NULL OR embedding = '')
+           AND forgotten = 0 AND archived = 0`
+      ).get().c;
+    }
+    return db.prepare(
+      `SELECT count(*) AS c FROM memories
+       WHERE ((embedding IS NULL OR embedding = '')
+              OR embedding_model IS NULL
+              OR embedding_model != ?)
+         AND forgotten = 0 AND archived = 0`
+    ).get(String(modelHash)).c;
+  }
+
   /** Per-model provenance counts over active rows ('' = unknown origin). */
   function embeddingModelBreakdown() {
     return db.prepare(
@@ -3650,6 +3767,18 @@ export function createStore(path) {
     return { path: typeof path === "string" ? path : null, pageSize, pageCount, freelistCount, fileBytes };
   }
 
+  /**
+   * 容量预警的行数口径（#275 空间维度）：活跃 / 归档各一格。体积与空闲页在
+   * storageStats()，这里只补行数——两条 COUNT 的成本，挂在 /health 的按需读上，
+   * 没有周期性消费者。归档增速（净增速率）是 recall-stats 的 archive 块（第五
+   * 指标，按精确 archived_at 算），这里刻意不算速率：同一个数字长两处就会分叉。
+   */
+  function capacityStats() {
+    const active = db.prepare("SELECT COUNT(*) AS n FROM memories WHERE archived = 0").get().n;
+    const archived = db.prepare("SELECT COUNT(*) AS n FROM memories WHERE archived = 1").get().n;
+    return { active, archived };
+  }
+
   /**
    * 整库 VACUUM（#275 的手动步骤）：代价 O(库大小) 且需要排他写锁，所以只在显式
    * 入口里跑，绝不挂启动路径、也不开 auto_vacuum。
@@ -3712,7 +3841,10 @@ export function createStore(path) {
    * pending once — a re-detection in a later dream run is a no-op, never a
    * duplicate queue entry. Returns the pending row (freshly inserted, or the
    * existing unresolved row when the pair is already pending), or undefined
-   * when the re-detection is suppressed.
+   * when the re-detection is suppressed. The returned row carries `fresh`:
+   * true only when this call actually inserted a row, false when the pair was
+   * already pending (issue #603 — callers used to read "non-null" as "parked",
+   * so a re-detection re-reported the same pair as a new freeze every run).
    *
    * v0.8.1（issue #170 复核项 4）：人工已裁决过的对（resolved_at 非空）不再
    * 反复入队——除非任一侧在裁决之后又被改过（updated_at 晚于 resolved_at）。
@@ -3720,12 +3852,12 @@ export function createStore(path) {
    * updated_at 是宽松代理（任何字段更新都会触发重新评审）——宁可多看一眼，
    * 不静音真冲突。
    */
-  function saveConflictPending({ run_id, memory_a, memory_b, reason }) {
+  function saveConflictPending({ run_id, memory_a, memory_b, reason, similarity }) {
     const [a, b] = [memory_a, memory_b].sort();
     const existing = db.prepare(
       "SELECT * FROM conflict_pending WHERE memory_a = ? AND memory_b = ? AND resolved_at IS NULL LIMIT 1"
     ).get(a, b);
-    if (existing) return toConflictPending(existing);
+    if (existing) return { ...toConflictPending(existing), fresh: false };
     const reviewed = db.prepare(
       "SELECT * FROM conflict_pending WHERE memory_a = ? AND memory_b = ? AND resolved_at IS NOT NULL ORDER BY resolved_at DESC, rowid DESC LIMIT 1"
     ).get(a, b);
@@ -3737,16 +3869,29 @@ export function createStore(path) {
     }
     const id = randomUUID();
     const now = nowIso();
+    // Issue #603 第 2 层：相似度落列。调用方拿不到（LLM 裁决路径只有理由文本）
+    // 就写 NULL，不猜——面板与排序都按「未知」处理，而不是当成 0。
+    const sim = typeof similarity === "number" && Number.isFinite(similarity)
+      && similarity >= 0 && similarity <= 1 ? similarity : null;
     db.prepare(
-      `INSERT INTO conflict_pending (id, run_id, memory_a, memory_b, reason, created_at)
-       VALUES (?, ?, ?, ?, ?, ?)`
-    ).run(id, run_id ?? null, a, b, reason ?? null, now);
-    return toConflictPending(db.prepare("SELECT * FROM conflict_pending WHERE id = ?").get(id));
+      `INSERT INTO conflict_pending (id, run_id, memory_a, memory_b, reason, similarity, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, run_id ?? null, a, b, reason ?? null, sim, now);
+    return { ...toConflictPending(db.prepare("SELECT * FROM conflict_pending WHERE id = ?").get(id)), fresh: true };
   }
 
   /**
-   * List pending conflicts, newest first. Unresolved rows only by default;
-   * pass includeResolved to include resolved ones (audit view).
+   * List pending conflicts, most-similar first. Unresolved rows only by
+   * default; pass includeResolved to include resolved ones (audit view).
+   *
+   * Issue #603 第 2 层：排序键从「created_at DESC」改成「相似度 DESC → created_at
+   * DESC」。原键在同一次 sleep 轮次里全同（实测 60 条落在 60ms 内），队列在面板
+   * 上等于随机；相似度是「该先看哪对」的唯一客观信号，现在它是一列而不是 reason
+   * 文本里的正则。
+   *
+   * NULL 排最后而不是当 0：存量行与 LLM 裁决路径没记相似度，把它们混进「低相似
+   * 度」会把「未知」伪装成「已测量」。`(similarity IS NULL)` 前缀让这条不依赖
+   * SQLite 的 NULL 排序约定，两个方向都稳。
    */
   function listConflictPending({ limit = 50, offset = 0, includeResolved = false } = {}) {
     const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
@@ -3755,7 +3900,9 @@ export function createStore(path) {
     if (!includeResolved) clauses.push("resolved_at IS NULL");
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     const rows = db.prepare(
-      `SELECT * FROM conflict_pending ${where} ORDER BY created_at DESC, id LIMIT ? OFFSET ?`
+      `SELECT * FROM conflict_pending ${where}
+       ORDER BY (similarity IS NULL), similarity DESC, created_at DESC, id
+       LIMIT ? OFFSET ?`
     ).all(...params, lim, off);
     return rows.map(toConflictPending);
   }
@@ -4265,6 +4412,26 @@ export function createStore(path) {
     return result.changes > 0;
   }
 
+  /**
+   * 覆盖一条关系行的 metadata（#619）。关系本身仍按 saveRelation 追加，
+   * 这条只给「同一条边被后续观察补充证据」用——情感相位判重命中时要把
+   * evidence 并集与 sessionCount 写回既有边，否则边上的场合数会永远停在
+   * 第一次写入那一刻。只改 metadata，不动 weight/source/created_at：这条边的
+   * 来源与权重反映的是它第一次被建立时的事实。
+   * 幂等（缺行 changes=0 → false）。
+   */
+  function updateRelationMetadata(id, metadata) {
+    const metaStr = metadata === undefined
+      ? null
+      : typeof metadata === "string"
+        ? metadata
+        : JSON.stringify(metadata);
+    const result = db.prepare(
+      "UPDATE entity_relations SET metadata = ? WHERE id = ?"
+    ).run(metaStr, id);
+    return result.changes > 0;
+  }
+
   /**
    * Re-point every attr row whose memory_id is fromMemoryId to toMemoryId
    * (autoDream merge migration, v0.3.0 Phase 4 / 4.3.2). When the keeper
@@ -4501,10 +4668,21 @@ export function createStore(path) {
   /** All entities (optionally name-filtered, newest first). Used by sleep phase 4
    *  orphan detection: an entity with zero relations is a candidate for relation
    *  completion. */
-  function listEntities({ limit = 1000 } = {}) {
+  function listEntities({ limit = 1000, q } = {}) {
+    const needle = typeof q === "string" ? q.trim() : "";
+    if (needle === "") {
+      const rows = db.prepare(
+        "SELECT * FROM entities ORDER BY last_seen DESC, name ASC LIMIT ?"
+      ).all(limit);
+      return rows.map(toEntity);
+    }
+    // 名字过滤放在 SQL 侧：调用方若在 LIMIT 之后过滤，排在 limit 之外的实体
+    // 就永远搜不到（面板按 limit=200 取回再本地过滤，1.6 万实体时命中率约 1%）。
+    // LIKE 的 % / _ 用 ESCAPE 转义，否则用户输入一个 "%" 就会把整库匹配出来。
+    const escaped = needle.replace(/[\\%_]/g, (ch) => `\\${ch}`);
     const rows = db.prepare(
-      "SELECT * FROM entities ORDER BY last_seen DESC, name ASC LIMIT ?"
-    ).all(limit);
+      "SELECT * FROM entities WHERE name LIKE ? ESCAPE '\\' ORDER BY last_seen DESC, name ASC LIMIT ?"
+    ).all(`%${escaped}%`, limit);
     return rows.map(toEntity);
   }
 
@@ -5128,9 +5306,143 @@ export function createStore(path) {
     ).all().map((r) => r.k);
   }
 
+  /* --------------------- knowledge base（知识库第二层，§3.3） --------------------- */
+  // 与 choro 那组表同一套纪律：本域只读写 kb_* 三张表，绝不进 memories /
+  // saveWithDedupe / dream / 质量过滤的任何池子。时间戳由调用方传（一次 ingest
+  // 的所有行共用一个时刻），store 不自取 now()——两处时钟会把「同一次入库」拆成
+  // 两个版本，sha256 幂等判据也会跟着抖。
+
+  function kbCollectionByKey(key) {
+    return db.prepare("SELECT * FROM kb_collections WHERE key = ?").get(String(key)) ?? undefined;
+  }
+
+  /** 集合列表带计数：面板左栏要的不是空壳 key 列表，docs/chunks 是它的主信息。 */
+  function listKbCollections() {
+    return db.prepare(
+      `SELECT c.*,
+              (SELECT COUNT(*) FROM kb_docs d WHERE d.collection_id = c.id) AS doc_count,
+              (SELECT COUNT(*) FROM kb_chunks k JOIN kb_docs d2 ON k.doc_id = d2.id
+                 WHERE d2.collection_id = c.id) AS chunk_count
+         FROM kb_collections c ORDER BY c.key`
+    ).all();
+  }
+
+  // key 是外部键（面板/工具用它寻址），title 是展示名。ON CONFLICT 不动 created_at：
+  // 「这个集合哪天建的」是事实，重命名不该改写它。
+  function upsertKbCollection({ key, title, description = null, at }) {
+    db.prepare(
+      `INSERT INTO kb_collections (key, title, description, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET
+         title = excluded.title,
+         description = excluded.description,
+         updated_at = excluded.updated_at`
+    ).run(String(key), String(title), description ?? null, at, at);
+    return kbCollectionByKey(key);
+  }
+
+  /** 删集合连带删它的文档与分块（三张表是一个整体，留孤儿行等于悄悄占空间）。 */
+  function deleteKbCollection(key) {
+    const row = kbCollectionByKey(key);
+    if (!row) return false;
+    return runAtomically(() => {
+      db.prepare(
+        "DELETE FROM kb_chunks WHERE doc_id IN (SELECT id FROM kb_docs WHERE collection_id = ?)"
+      ).run(row.id);
+      db.prepare("DELETE FROM kb_docs WHERE collection_id = ?").run(row.id);
+      db.prepare("DELETE FROM kb_collections WHERE id = ?").run(row.id);
+      return true;
+    });
+  }
+
+  function listKbDocs(collectionId) {
+    return db.prepare(
+      "SELECT * FROM kb_docs WHERE collection_id = ? ORDER BY rel_key"
+    ).all(collectionId);
+  }
+
+  function kbDocByRelKey(collectionId, relKey) {
+    return db.prepare(
+      "SELECT * FROM kb_docs WHERE collection_id = ? AND rel_key = ?"
+    ).get(collectionId, String(relKey)) ?? undefined;
+  }
+
+  function kbChunksByDoc(docId) {
+    return db.prepare(
+      "SELECT * FROM kb_chunks WHERE doc_id = ? ORDER BY ordinal"
+    ).all(docId);
+  }
+
+  /**
+   * 入库落库的唯一写口。幂等判据是 **正文 sha256**（不是文件 stat）：同 rel_key +
+   * 同 sha256 = 整件事 no-op，回执 skipped 且不动 chunks——否则编辑器保存一次
+   * （mtime 变、内容没变）就要全量重切块，库和索引一起白忙。
+   *
+   * 变了才替换：删旧 chunks 再插新的，事务包住，半截失败整体回滚，库里保持上一版
+   * 完整文档。上一版 status=error 的行不算命中（它没有可分块的正文，重来必须真跑）。
+   */
+  function replaceKbDoc({ collectionId, relKey, kind, sourcePath = null, title, bytes = 0, sha256 = null, at, chunks = [] }) {
+    return runAtomically(() => {
+      const prev = kbDocByRelKey(collectionId, relKey);
+      if (prev && prev.status === "ok" && sha256 && prev.sha256 === sha256) {
+        return { docId: prev.id, chunks: kbChunksByDoc(prev.id).length, skipped: true };
+      }
+      db.prepare("DELETE FROM kb_chunks WHERE doc_id IN (SELECT id FROM kb_docs WHERE collection_id = ? AND rel_key = ?)")
+        .run(collectionId, String(relKey));
+      let docId;
+      if (prev) {
+        db.prepare(
+          `UPDATE kb_docs SET kind = ?, source_path = ?, title = ?, bytes = ?, sha256 = ?,
+                  indexed_at = ?, status = 'ok', error = NULL WHERE id = ?`
+        ).run(kind, sourcePath, String(title), bytes, sha256, at, prev.id);
+        docId = prev.id;
+      } else {
+        const info = db.prepare(
+          `INSERT INTO kb_docs (collection_id, rel_key, kind, source_path, title, bytes, sha256, indexed_at, status, error)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'ok', NULL)`
+        ).run(collectionId, String(relKey), kind, sourcePath, String(title), bytes, sha256, at);
+        docId = Number(info.lastInsertRowid);
+      }
+      const ins = db.prepare(
+        "INSERT INTO kb_chunks (doc_id, ordinal, heading, text, created_at) VALUES (?, ?, ?, ?, ?)"
+      );
+      for (const c of chunks) ins.run(docId, c.ordinal, c.heading ?? "", c.text ?? "", at);
+      return { docId, chunks: chunks.length, skipped: false };
+    });
+  }
+
+  /** 入库失败也要留痕：面板要能显示「这份文档上次为什么没进来」，静默丢来源等于假成功。 */
+  function markKbDocError({ collectionId, relKey, kind, sourcePath = null, title, error, at }) {
+    const prev = kbDocByRelKey(collectionId, relKey);
+    if (prev) {
+      db.prepare(
+        "UPDATE kb_docs SET status = 'error', error = ?, indexed_at = ?, source_path = ?, kind = ?, title = ? WHERE id = ?"
+      ).run(String(error ?? ""), at, sourcePath, kind, String(title ?? prev.title), prev.id);
+      return prev.id;
+    }
+    const info = db.prepare(
+      `INSERT INTO kb_docs (collection_id, rel_key, kind, source_path, title, bytes, sha256, indexed_at, status, error)
+       VALUES (?, ?, ?, ?, ?, 0, NULL, ?, 'error', ?)`
+    ).run(collectionId, String(relKey), kind, sourcePath, String(title ?? relKey), at, String(error ?? ""));
+    return Number(info.lastInsertRowid);
+  }
+
+  /** 检索候选集：跨集合或单集合，一次取全（BM25 需要全语料算 df，不能分页取）。 */
+  function kbChunksForSearch(collectionId = null) {
+    return db.prepare(
+      `SELECT k.id, k.doc_id, k.ordinal, k.heading, k.text,
+              d.rel_key, d.title, d.kind, c.key AS collection_key
+         FROM kb_chunks k
+         JOIN kb_docs d ON k.doc_id = d.id
+         JOIN kb_collections c ON d.collection_id = c.id
+        WHERE d.status = 'ok' AND (? IS NULL OR d.collection_id = ?)`
+    ).all(collectionId, collectionId);
+  }
+
   return {
     db,
     count,
+    countByType,
     getById,
     // 车道 C：外来行身份的两个读口（幂等键 / 整包清点）。
     getByShareExternalId,
@@ -5174,6 +5486,7 @@ export function createStore(path) {
     embeddedCount,
     needsEmbedding,
     needsEmbeddingFor,
+    countNeedsEmbeddingFor,
     hasStaleEmbedding,
     embeddingModelBreakdown,
     embeddingDimensionBreakdown,
@@ -5232,6 +5545,7 @@ export function createStore(path) {
     archivedEmbeddingStats,
     clearArchivedEmbeddings,
     storageStats,
+    capacityStats,
     vacuum,
     saveFailure,
     listFailures,
@@ -5284,6 +5598,7 @@ export function createStore(path) {
     listBoostedRelations,
     getLinkedMemoryIds,
     saveRelation,
+    updateRelationMetadata,
     bumpRelationWeight,
     migrateAttrsToMemory,
     getRelations,
@@ -5303,6 +5618,17 @@ export function createStore(path) {
     getContinuityProposal,
     listContinuityProposals,
     countContinuityProposals,
+    // knowledge base（知识库第二层，§3.3）：三张 kb_* 表，与记忆行物理隔离。
+    kbCollectionByKey,
+    listKbCollections,
+    upsertKbCollection,
+    deleteKbCollection,
+    listKbDocs,
+    kbDocByRelKey,
+    kbChunksByDoc,
+    replaceKbDoc,
+    markKbDocError,
+    kbChunksForSearch,
     // chorography（仓库地志）：M0 只写不读，消费面 M1 接（见上面注释块）。
     choroRepoByRoot,
     upsertChoroRepo,

package/lib/summarize.js

@@ -9,6 +9,8 @@ import { createScopeResolver } from "./scope.js";
 // #493 补充 §③：断链与巩固侧同一份实现（src/fence.js）。转录里出现闭合标记时
 // 原先能提前闭合围栏——那是把用户消息升格成指令最短的一条路。
 import { breakFenceMarkers } from "./fence.js";
+// Issue #611：图片块的文本口径（占位，不是空串）。三个 textOf 副本共用这一份。
+import { contentToText, countImages } from "./attachment-text.js";
 // #512：每轮蒸馏一个 run id（归因主体）。store 侧也能铸造，但这里必须知道它——
 // 写记忆时要把它一路带到 saveMemoryProvenance / 落 run 行，拿回来再写就是两次往返。
 import { randomUUID } from "node:crypto";
@@ -292,13 +294,13 @@ const SUBAGENT_MESSAGE_KINDS = new Set(["agent-message", "subagent-settled"]);
 
 // 兼容严格形状 [{type:"text",text}] 与宽松形状 ["字符串", ...]（lib-smoke 用例
 // 直接传字符串数组）。只取公开文本块；reasoning 私有推理块不进蒸馏上下文。
+//
+// Issue #611：图片块曾经在这里一律变空串，于是图-only 消息整条被丢、图+文消息只剩
+// 文字——静默，没有任何计数。现在改由 attachment-text 统一产占位，
+// `[图: 屏幕截图 … 1543x983]`。抽取口径只有一份，三个调用方（本文件 /
+// continuity / hot-memory）共用，避免同一件事写成三份会漂移的实现。
 function textOf(content) {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .map((block) => (typeof block === "string" ? block : (block && block.type === "text" && typeof block.text === "string" ? block.text : "")))
-    .filter((s) => s)
-    .join("\n");
+  return contentToText(content);
 }
 
 /**
@@ -333,6 +335,10 @@ function publicTranscriptParts(event) {
     parts.push({
       role: "agent",
       text,
+      // Issue #611：把产文本的那份 content 一起带出去。判定与文本同源，计量才能
+      // 跟着同一份判定走（见 collectMessages 里的 imageCount）——另写一套「哪些块
+      // 算公开」给计量用，就是第二份实现，迟早与这份漂移。
+      blocks: Array.isArray(message?.content) ? message.content : [],
       // 同一条子会话消息可能同时出现在 user/message 与 agent/inbox/spliced
       // 里（投递路径重叠），按 id（无 id 时按内容）去重，否则转录会重复。
       key: typeof message?.id === "string" && message.id
@@ -346,7 +352,7 @@ function publicTranscriptParts(event) {
       const text = textOf(data?.content);
       if (!text.trim()) break;
       if (SUBAGENT_MESSAGE_KINDS.has(kind)) pushAgentMessage(data);
-      else parts.push({ role: "user", text });
+      else parts.push({ role: "user", text, blocks: Array.isArray(data?.content) ? data.content : [] });
       break;
     }
     case "agent/inbox/spliced": {
@@ -358,7 +364,7 @@ function publicTranscriptParts(event) {
       const blocks = Array.isArray(data?.message?.content) ? data.message.content : [];
       const text = textOf(blocks);
       // 私有推理块（reasoning）刻意不采集：蒸馏记忆不得沉淀模型私有思考链。
-      if (text.trim()) parts.push({ role: "assistant", text });
+      if (text.trim()) parts.push({ role: "assistant", text, blocks });
       break;
     }
     default:
@@ -395,6 +401,10 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
   const events = snapshotSessionEvents(session, afterSeq, throughSeq);
   const lines = [];
   const seenSubagentMessages = new Set();
+  // Issue #611：这一窗里被折成占位的图片张数。占位本身不丢信息，但「折了几张」
+  // 必须是个能读到的数——否则 off 档和旧版静默丢弃在观测上无法区分，下次再有人
+  // 问「图到底进来没有」还是得翻源码。计量只数窗口内事件，不受截断影响。
+  let imageCount = 0;
   const trim = (s, n) => (typeof s === "string" && s.length > n ? `${s.slice(0, n)}…` : s);
   const trimTranscript = (s, n) => {
     if (typeof s !== "string" || s.length <= n) return s;
@@ -421,9 +431,20 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
       if (part.role === "agent") {
         if (part.key && seenSubagentMessages.has(part.key)) continue;
         if (part.key) seenSubagentMessages.add(part.key);
-        lines.push(STR.transcriptAgent[language](part.text));
-      } else if (part.role === "user") {
+      }
+      // Issue #611 计量：数「真正进了转录的图块」，所以按 part 数、并且在去重之后
+      // ——同一条子会话消息会同时出现在 user/message 与 agent/inbox/spliced 里
+      // （投递路径重叠），按事件数会把它算两遍。
+      //
+      // 不按事件数还有个更要紧的理由：被 publicTranscriptParts 挡掉的注入消息
+      // （工具结果、插件注入、陌生 source.kind）里的图根本进不了转录，按事件累加
+      // 会报「这一窗有 2 张图」而转录里一张都没有。part 是渲染与落盘共用的同一份
+      // 判定，计量跟着它走，两处不会再各有一套口径。
+      imageCount += countImages(part.blocks);
+      if (part.role === "user") {
         lines.push(STR.transcriptUser[language](part.text));
+      } else if (part.role === "agent") {
+        lines.push(STR.transcriptAgent[language](part.text));
       } else {
         lines.push(STR.transcriptAssistant[language](part.text));
       }
@@ -485,6 +506,9 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
       : [],
     hasEvents: events.length > 0,
     lastSeq,
+    // Issue #611：这一窗折成占位的图片张数。调用方把它写进审计 metadata，
+    // 让「图进来了几张」成为可对账的事实而不是推断。
+    imageCount,
     // Issue #493：只数**转录正文**的字符数。minWindowChars 闸门与审计里的
     // distillChars 量的都是「这一窗有多少可提炼内容」，不是「我们额外包了多少
     // 提示词」——若把围栏与角色句算进去，一条「短」也会凭空越过任何阈值，
@@ -850,6 +874,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
         0
       );
       const minWindowChars = config.summarizeMinWindowChars ?? 0;
+      const imageCount = collected.imageCount ?? 0;
       if (minWindowChars > 0 && distillChars < minWindowChars) {
         commitCursor(session.id, nextSeq);
         writeAudit({
@@ -857,7 +882,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
           model_id: route ? `${route.provider}:${route.model}` : "unknown",
           status: "skipped",
           error_message: "window-too-small",
-          metadata: { distillChars, minWindowChars }
+          metadata: { distillChars, minWindowChars, ...(imageCount > 0 ? { imageCount } : {}) }
         });
         return;
       }
@@ -1064,6 +1089,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
           audit.errorMessage = failureAudit.errorMessage;
           audit.metadata = {
             distillChars,
+            ...(imageCount > 0 ? { imageCount } : {}),
             ...failureAudit.metadata,
             streak,
             ...(maxParseRetries > 0 ? { maxRetries: maxParseRetries } : {}),
@@ -1203,6 +1229,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
       if (audit) {
         audit.metadata = {
           distillChars,
+          ...(imageCount > 0 ? { imageCount } : {}),
           parsed: parsed.length,
           ...(parsedResult.salvaged ? { json_salvaged: true } : {}),
           ...(capped > 0 ? { capped } : {}),