@modusensus/dsh-mneme 0.11.0 → 0.13.0

package/src/store.js

@@ -287,6 +287,29 @@ CREATE TABLE IF NOT EXISTS scope_state (
 -- 它同时是 setScopeState 那条 UPSERT 的冲突目标，所以不能省。
 CREATE UNIQUE INDEX IF NOT EXISTS idx_scope_state_key ON scope_state(dimension, scope_value);
 
+-- pinned_memories: #249 第二批，显式 pin。旧口径把「类型是 constraint/preference」
+-- 当成 pin（隐含假设），于是 1163 条自动变「每轮必进」而预算只有 5——池子本身
+-- 就太大，靠相关性排序永远轮不到「署名」「拒绝谄媚」这类稳定偏好。本表把
+-- 「哪些是用户亲手钉的」变成一条显式事实：注入侧只认这张表，不再认类型。
+--
+-- 为什么是独立表而不是 memories 的布尔列：回退只需一条 DROP，不碰 31 列的主表；
+-- 且「pin 是用户与记忆之间的一条关系」天然是关系表——created_at 还能给出
+-- pin 顺序（按 pin 先后注入，而不是按「最近改过」）。外泄面天然为零：
+-- mirror/share 都不 SELECT 本表，pin 标记不会出现在导出物里。
+--
+-- 幂等靠 CREATE TABLE IF NOT EXISTS（本文件其余建表同款），不登记
+-- applied_migrations——那是给「跑完恒不命中却仍要全表扫一遍」的 data migration
+-- 用的，本表没有回填步骤。存量库升级后本表为空，注入侧据此回落到旧的类型口径
+-- （见 service.injectCandidates 的 type-fallback 分支），升级即等价。
+CREATE TABLE IF NOT EXISTS pinned_memories (
+  memory_id  TEXT PRIMARY KEY,
+  created_at TEXT NOT NULL,
+  note       TEXT
+);
+-- 按 pin 顺序注入要读 created_at 全序；本表行数以「人手钉的条数」计（个位到几十），
+-- 索引只为把排序的临时 B 树换成一次有序扫，不承担过滤。
+CREATE INDEX IF NOT EXISTS idx_pinned_created ON pinned_memories(created_at);
+
 -- llm_audit_logs: every background LLM call (autoDream consolidation + summary,
 -- autoSummarize compression) is recorded here — tokens in/out, duration, status
 -- and the trigger that caused it (Bug8). Failures are captured as status='error'
@@ -409,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() 仍显式清（与
@@ -603,14 +629,19 @@ CREATE TABLE IF NOT EXISTS choro_claims (
 );
 CREATE INDEX IF NOT EXISTS idx_choro_claims_page ON choro_claims(page_id);
 
--- 向量壳（M1/M2 接 embedder 后灌）：owner_id 指向 choro_claims 或 choro_pages
--- （spec §5 的多态指向）。向量与记忆向量不共表、不共查询——两边换模型版本的
--- 节奏不同（V4 待实测项），混表会让其中一边被另一边的模型版本绑死。
+-- 向量壳（收尾档 P36/P38 落地）：owner_id 指向 choro_pages（v1 只做页级；
+-- claims 级留待真有精排需求）。向量与记忆向量不共表、不共查询——两边换模型
+-- 版本的节奏不同（V4 的答案在此：model/dim 记行内，**不锁死**——dim 失配 =
+-- 惰性全量重嵌，代价只是几十页重嵌而不是作废记忆向量）。
+-- vector 存 JSON 数组（与 memories.embedding 同款 TEXT 形态）；source_generated_at
+-- 记嵌入时刻页面的 generated_at——页面富化/重建后该值变化，检索侧据此判 staleness。
 CREATE TABLE IF NOT EXISTS choro_vectors (
-  owner_id   INTEGER NOT NULL,
-  dim        INTEGER NOT NULL,
-  model      TEXT NOT NULL,
-  created_at TEXT NOT NULL
+  owner_id            INTEGER NOT NULL,
+  dim                 INTEGER NOT NULL,
+  model               TEXT NOT NULL,
+  vector              TEXT,
+  source_generated_at TEXT,
+  created_at          TEXT NOT NULL
 );
 CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_vectors_owner_model ON choro_vectors(owner_id, model);
 
@@ -626,6 +657,111 @@ CREATE TABLE IF NOT EXISTS choro_edges (
 );
 CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_edges_triple ON choro_edges(repo_id, from_slug, to_slug);
 CREATE INDEX IF NOT EXISTS idx_choro_edges_to ON choro_edges(repo_id, to_slug);
+
+-- profile_facts：「Agent 眼中的你」自动事实（2026-11-06 需求，对标 DS Bot 每 bot
+-- 一份 MEMORY.md 事实清单的设计）。与手填画像（user_settings.profile）**物理分离**
+-- ——那是用户的原文，模型只有读权（profile-extract #497 的「只出草稿不落库」口径
+-- 不变）；本表是 agent 侧对用户的独立认知，模型可在 dream 轮里增改、用户可在面板
+-- 上逐条修正。agent_key='' 是 default 卡（解析不到会话身份的会话），非空值是会话
+-- 身份，与 persona byAgent 同一取值域（session.header.agentPreset）。
+-- 输入行严格分区不互串：agent 卡只吃 agent_scope=自己 的记忆行，default 卡只吃
+-- agent_scope IS NULL 的行；外来行（source=imported）整体排除（memory-source.js
+-- 那条「本库不巩固别人导入的原文」延伸到画像事实：导入的包不该改写本库对用户的认知）。
+CREATE TABLE IF NOT EXISTS profile_facts (
+  id                TEXT PRIMARY KEY,
+  agent_key         TEXT NOT NULL DEFAULT '',
+  content           TEXT NOT NULL,
+  status            TEXT NOT NULL DEFAULT 'active',  -- active | archived
+  source_memory_ids TEXT NOT NULL DEFAULT '[]',      -- JSON：这条事实的出处记忆 id
+  created_at        TEXT NOT NULL,
+  updated_at        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_profile_facts_card ON profile_facts(agent_key, status);
+
+-- 逐 op 账本（scope_changes 式）：谁（auto 轮 / 面板人工）、何时、把哪条事实从什么
+-- 改成了什么。审计纪律同 dream_runs / llm_audit_logs：只记账，不触发任何 hook。
+CREATE TABLE IF NOT EXISTS profile_fact_journal (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  at        TEXT NOT NULL,
+  agent_key TEXT NOT NULL DEFAULT '',
+  run_id    TEXT,                                -- auto 轮的回执 id；人工操作为 NULL
+  fact_id   TEXT,
+  op        TEXT NOT NULL,                       -- add | update | archive | restore | delete
+  before    TEXT,
+  after     TEXT,
+  actor     TEXT NOT NULL DEFAULT 'auto'         -- auto | manual
+);
+CREATE INDEX IF NOT EXISTS idx_profile_fact_journal_card ON profile_fact_journal(agent_key, id);
+
+-- 每轮回执（dream_runs 式）：游标（该卡消费到 memories.updated_at 的哪一刻）、
+-- 输入条数、落地 op 数。游标从最近一次 ok 轮读取——failed 轮不推进游标，下次
+-- 重跑同一窗口（与蒸馏游标同款纪律：失败不消费）。
+CREATE TABLE IF NOT EXISTS profile_fact_runs (
+  id             TEXT PRIMARY KEY,
+  agent_key      TEXT NOT NULL DEFAULT '',
+  trigger_source TEXT NOT NULL,                   -- auto | manual
+  status         TEXT NOT NULL,                   -- ok | noop | failed
+  cursor         TEXT,                            -- 本轮消费到的 memories.updated_at
+  input_count    INTEGER NOT NULL DEFAULT 0,
+  ops_applied    INTEGER NOT NULL DEFAULT 0,
+  detail         TEXT,
+  started_at     TEXT NOT NULL,
+  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
@@ -880,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
@@ -930,6 +1070,17 @@ function toScopeState(row) {
   };
 }
 
+// pinned_memories 行 → 读侧对象（#249 第二批）。NULL note 落 undefined，
+// 与 toScopeState 同口径。
+function toPinned(row) {
+  if (!row) return undefined;
+  return {
+    memory_id: row.memory_id,
+    created_at: row.created_at,
+    note: row.note ?? undefined
+  };
+}
+
 function toRecallRun(row) {
   if (!row) return undefined;
   return {
@@ -1141,6 +1292,10 @@ export function createStore(path) {
   // chorography（M2，实现计划 P17）：T1 生成轮的页级失败计数。T0 建的表没有它
   // （M0 只写 skeleton），存量库经 PRAGMA 检查后补列，幂等。
   addColumn("choro_pages", "fail_count", "ALTER TABLE choro_pages ADD COLUMN fail_count INTEGER NOT NULL DEFAULT 0");
+  // chorography 收尾档（P36）：v0.11.0 的 choro_vectors 是空壳表（spec §5 漏了
+  // 向量本体列），存量库经 PRAGMA 检查补列。
+  addColumn("choro_vectors", "vector", "ALTER TABLE choro_vectors ADD COLUMN vector TEXT");
+  addColumn("choro_vectors", "source_generated_at", "ALTER TABLE choro_vectors ADD COLUMN source_generated_at TEXT");
 
   // v0.8.0 A1（issue #17）scope 隔离存储层：四列全部可空、不带 DEFAULT——存量行
   // 零重写，读侧把 NULL 视为未标注（= 全局可见）。是否落值由 scopeEnabled 门控
@@ -1398,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
@@ -1419,28 +1586,71 @@ export function createStore(path) {
   // Issue #202：embedding 解析缓存。检索路径此前每次调用都对全部带向量行
   // JSON.parse（993 × 512 维 ≈ 48 ms/次，且 SQL 拖着 10 MB 的 TEXT），余弦本身
   // 只占 3%。向量只经 setEmbedding 写入（单一失效点），把解析结果按 id 缓存，
-  // 命中即零解析；上限 FIFO 驱逐防大库内存无界（4000 × 512 维 double ≈ 16 MB）。
+  // 命中即零解析。
+  //
+  // 上限为什么不能是固定常量（2026-11-05 实测）：上限 4000、活跃带向量行 6685，
+  // 扫到第 4001 条开始驱逐自己刚填的条目，扫完只剩最后 4000 条，下一轮又从第
+  // 一条 miss——四轮实测命中率恒 0.0%，缓存等于不存在，每次检索都全量重解析
+  // （实测 624 ms）。固定调大只是把复发推到下个月（活跃行近 30 天净增 6156 条，
+  // 上限 20000 也只撑到 2027-01-09），所以上限跟工作集自适应：
+  //   · 每次全量扫（searchVector / vectorDimensionState）在循环前把上限抬到
+  //     「本次扫到的行数 ×1.25」，一次扫完不会被自己的驱逐打断；
+  //   · 内存预算封顶（默认 256 MB），超预算的行仍按 FIFO 驱逐——大库退化回
+  //     「部分命中」，不会无界吃内存。
+  // 存储用 Float32Array。同一口径（GC 后 heapUsed + arrayBuffers，6730 条
+  // 1024 维全常驻）实测：number[] 56.4MB → Float32Array 29.7MB（heap 1.9 +
+  // arrayBuffers 27.8），省 26.7MB / 47%。注意 heapUsed 不统计 TypedArray 的
+  // 底层 ArrayBuffer，只看 heapUsed 会读成「省 96%」的假象；旧实现若保持上限
+  // 4000 则装不下工作集（常驻 31.9MB 但命中率 0%），两者不可比，所以对照组是
+  // 把旧上限抬到 20000 让工作集全常驻。cosine 全量 25.4ms → 18.0ms，前 50 条
+  // 排序精度差 0.00e+0。对外契约不变：
+  // getParsedEmbedding / getEmbeddings 仍返回 number[]，只有内部热路径
+  // （readVector）拿 Float32Array。
   const embeddingCache = new Map();
-  const EMBEDDING_CACHE_MAX = 4000;
+  const EMBEDDING_CACHE_FLOOR = 4000;
+  const EMBEDDING_CACHE_BUDGET_BYTES = 256 * 1024 * 1024;
+  let embeddingCacheCap = EMBEDDING_CACHE_FLOOR;
+  let embeddingCacheHits = 0;
+  let embeddingCacheMisses = 0;
+
+  /** Vector-like = number[] or Float32Array (typed). All cosine guards use this
+   *  instead of Array.isArray, which is false for typed arrays — with the old
+   *  guard every cached vector would silently score 0. */
+  function isVectorLike(v) {
+    return Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
+  }
 
   function cacheEmbedding(id, vector) {
-    if (embeddingCache.size >= EMBEDDING_CACHE_MAX && !embeddingCache.has(id)) {
+    if (embeddingCache.size >= embeddingCacheCap && !embeddingCache.has(id)) {
       const oldest = embeddingCache.keys().next().value;
       embeddingCache.delete(oldest);
     }
     embeddingCache.set(id, vector);
   }
 
-  /** Parsed embedding for one id (cache-first); undefined when none/parse
-   *  failure. Single read path shared by searchVector / getEmbedding(s). */
-  function getParsedEmbedding(id) {
+  /** Raise the cap to fit a sweep of `rows` rows (×1.25 headroom), clamped by
+   *  the memory budget. Called before a full scan so the scan itself does not
+   *  evict what it just cached. */
+  function noteSweep(rows, avgDim) {
+    if (!rows || !avgDim) return;
+    const perVector = avgDim * Float32Array.BYTES_PER_ELEMENT;
+    const budgetRows = Math.floor(EMBEDDING_CACHE_BUDGET_BYTES / perVector);
+    const want = Math.ceil(rows * 1.25);
+    embeddingCacheCap = Math.max(EMBEDDING_CACHE_FLOOR, Math.min(budgetRows, want));
+  }
+
+  /** Cache-first read returning Float32Array (internal hot path only).
+   *  undefined when none/parse failure. */
+  function readVector(id) {
     const cached = embeddingCache.get(id);
-    if (cached) return cached;
+    if (cached) { embeddingCacheHits += 1; return cached; }
+    embeddingCacheMisses += 1;
     const row = db.prepare("SELECT embedding FROM memories WHERE id = ?").get(id);
     if (!row?.embedding) return undefined;
     try {
-      const v = JSON.parse(row.embedding);
-      if (Array.isArray(v) && v.length) {
+      const parsed = JSON.parse(row.embedding);
+      if (Array.isArray(parsed) && parsed.length) {
+        const v = new Float32Array(parsed);
         cacheEmbedding(id, v);
         return v;
       }
@@ -1448,6 +1658,27 @@ export function createStore(path) {
     return undefined;
   }
 
+  /** Parsed embedding for one id (cache-first); undefined when none/parse
+   *  failure. Single read path shared by searchVector / getEmbedding(s).
+   *  Public contract: returns number[] (callers guard with Array.isArray). */
+  function getParsedEmbedding(id) {
+    const v = readVector(id);
+    return v ? Array.from(v) : undefined;
+  }
+
+  /** Cache instrumentation for the regression lock (hit rate must not collapse
+   *  back to 0 when the working set outgrows a fixed cap). */
+  function embeddingCacheStats() {
+    const total = embeddingCacheHits + embeddingCacheMisses;
+    return {
+      size: embeddingCache.size,
+      cap: embeddingCacheCap,
+      hits: embeddingCacheHits,
+      misses: embeddingCacheMisses,
+      hitRate: total ? embeddingCacheHits / total : 0
+    };
+  }
+
   // all()/list() 的显式列清单：从实际 schema 派生（迁移后），只排除 embedding
   // 列——consolidation/sleep/inject 的消费方都不读向量，而它是全表里最重的一列
   // （5k 行库 ≈ 9.4 MB TEXT），每次全表调用都白搬。经 PRAGMA 派生而非硬编码，
@@ -1555,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 >= ?");
@@ -1627,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);
@@ -1883,6 +2135,11 @@ export function createStore(path) {
       db.prepare("DELETE FROM memory_provenance WHERE memory_id = ?").run(id);
       // #512：铸造记录同理——它也只是指着记忆行的索引，行没了索引就没有指代对象。
       db.prepare("DELETE FROM memory_mints WHERE memory_id = ?").run(id);
+      // #249 第二批：pin 行同理，理由与前两条完全一致（本表建表时也没抄
+      // REFERENCES ... ON DELETE CASCADE，清理不挂驱动默认）。注意这一条**只
+      // 防攒垃圾**，不修「回落被卡住」——注入侧判据看的是「有几条能用的」
+      // 而不是「表里有几行」，见 service.js 注入段与 pinnedStats.source 三档。
+      db.prepare("DELETE FROM pinned_memories WHERE memory_id = ?").run(id);
       db.prepare("DELETE FROM memories WHERE id = ?").run(id);
       // Mirror sync must reflect the deletion; bump desired generation so a
       // crash between the delete and syncMirror leaves a recoverable debt.
@@ -1950,6 +2207,8 @@ export function createStore(path) {
         const marks = chunk.map(() => "?").join(", ");
         db.prepare(`DELETE FROM memory_provenance WHERE memory_id IN (${marks})`).run(...chunk);
         db.prepare(`DELETE FROM memory_mints WHERE memory_id IN (${marks})`).run(...chunk);
+        // 同 remove()：pin 行防攒垃圾（不修卡回落的那个判据问题）。
+        db.prepare(`DELETE FROM pinned_memories WHERE memory_id IN (${marks})`).run(...chunk);
         deleted += db.prepare(`DELETE FROM memories WHERE id IN (${marks})`).run(...chunk).changes;
       }
       incrementGeneration();
@@ -2311,7 +2570,10 @@ export function createStore(path) {
    *  name; omitting modelHash leaves the column untouched (callers that
    *  predate the column still work, their rows simply read as unknown). */
   function setEmbedding(id, vector, modelHash) {
-    const json = Array.isArray(vector) && vector.length ? JSON.stringify(vector) : null;
+    // isVectorLike 而非 Array.isArray：调用方可能递进 Float32Array（本模块缓存的
+    // 就是它）。旧守卫对 typed array 返回 false，会把「设置向量」读成「清空向量」，
+    // 静默把行改成 NULL。
+    const json = isVectorLike(vector) && vector.length ? JSON.stringify(Array.from(vector)) : null;
     if (json) {
       if (modelHash !== undefined) {
         db.prepare("UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?")
@@ -2324,15 +2586,10 @@ export function createStore(path) {
     }
     // Issue #202：单一写入口即单一失效点——重写缓存条目（向量在手上不必重解析），
     // 清空则移除，删除过的 id 不会被下一次 searchVector 的 id 集合选中。
-    if (json) {
-      try {
-        const parsed = JSON.parse(json);
-        if (Array.isArray(parsed) && parsed.length) cacheEmbedding(id, parsed);
-        else embeddingCache.delete(id);
-      } catch { embeddingCache.delete(id); }
-    } else {
-      embeddingCache.delete(id);
-    }
+    // 缓存里存 Float32Array（与 readVector 同一表示），不存 JSON.parse 出来的
+    // number[]，否则写后第一次读还要再转一次。
+    if (json) cacheEmbedding(id, new Float32Array(vector));
+    else embeddingCache.delete(id);
   }
 
   /** Batch fetch stored embeddings by id (v0.5.0 search-time semantic dedup).
@@ -2411,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(
@@ -2493,18 +2774,21 @@ export function createStore(path) {
    */
   function vectorDimensionState(dimension) {
     if (!Number.isInteger(dimension) || dimension <= 0) return { state: "invalid" };
-    // 与 searchVector 的 WHERE 谓词逐条相同（顺序不同、语义等价）——同源行集，同步改。
+    // 与 searchVector 的行集逐条相同（顺序不同、语义等价）——同源行集，同步改。
+    // 同样不带 `embedding != ''`：只取 id，读 embedding 列纯属白搬；空串行由
+    // readVector 返回 undefined，落到下面 sawVector 分支（不影响 unreadable 判定）。
     const rows = db.prepare(
       `SELECT id FROM memories
-       WHERE embedding IS NOT NULL AND embedding != ''
+       WHERE embedding IS NOT NULL
          AND forgotten = 0 AND archived = 0`
     ).all();
     if (!rows.length) return { state: "none" };
     let sawVector = false;
+    noteSweep(rows.length, dimension);
     for (const row of rows) {
-      // 走 getParsedEmbedding 的解析缓存，不自己 JSON.parse——与 searchVector /
-      // getEmbedding(s) 同一条读路径，缓存热时零解析。
-      const v = getParsedEmbedding(row.id);
+      // 走同一解析缓存，不自己 JSON.parse——与 searchVector / getEmbedding(s)
+      // 同一条读路径，缓存热时零解析。
+      const v = readVector(row.id);
       if (!v || !v.length) continue;
       sawVector = true;
       if (v.length === dimension) return { state: "match" };
@@ -2538,7 +2822,7 @@ export function createStore(path) {
   // --- vector search ------------------------------------------------------
 
   function cosine(a, b) {
-    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
+    if (!isVectorLike(a) || !isVectorLike(b) || a.length !== b.length || !a.length) return 0;
     let dot = 0;
     let na = 0;
     let nb = 0;
@@ -2561,13 +2845,22 @@ export function createStore(path) {
     // Issue #202：只取 id 列（~40 KB）而非 SELECT *（~11 MB）——向量从缓存取，
     // 缓存未命中时按 id 点查 embedding 再解析回填。SQL 里保留 embedding 的
     // IS NOT NULL 过滤，保证「有向量的行」集合始终以库为准（删除/清空即时生效）。
+    //
+    // 为什么不带 `embedding != ''`（2026-11-05 实测）：`!= ''` 要读 embedding 列
+    // 才能判定，SQLite 就得把 134MB 向量文本整个从磁盘搬一遍——而这里只 SELECT
+    // id，一条文本都不用。真库副本实测：这条 SQL 单独跑 265ms → 96ms；落到
+    // 一轮完整检索上是 138ms → 47ms（省约 90ms，其余是解析/打分开销）。
+    // 空串行（外部直接 UPDATE 造出来的，setEmbedding 写的是 NULL）由 readVector
+    // 兜住：JSON.parse('') 抛错 → 返回 undefined → 跳过，既不计分也不崩。
     const rows = db.prepare(
       `SELECT id FROM memories
-       WHERE ${archivedFilter}forgotten = 0 AND embedding IS NOT NULL AND embedding != ''`
+       WHERE ${archivedFilter}forgotten = 0 AND embedding IS NOT NULL`
     ).all();
     const scored = [];
+    // 自适应上限：本次要扫这么多行，先让缓存装得下，否则会边扫边驱逐自己。
+    noteSweep(rows.length, vector.length);
     for (const row of rows) {
-      const v = getParsedEmbedding(row.id);
+      const v = readVector(row.id);
       if (!v) continue;
       // distill-tx-embed-gap 顺带修：维度不匹配的行按维度分流，直接跳过。旧路径
       // 喂进 cosine 不等长就 return 0，换了模型/维度的旧向量以 0 分混进结果尾部
@@ -3474,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。
@@ -3536,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）。
@@ -3544,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);
@@ -3561,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);
@@ -3579,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);
   }
@@ -3804,6 +4127,85 @@ export function createStore(path) {
     return rows.map(toScopeState);
   }
 
+  // --- pinned_memories: 显式 pin（#249 第二批） ------------------------------
+  // 四个函数只管「哪条被钉住了」这条事实，不回答「该不该注入」——注入侧的
+  // 越权/暂停作用域/遗忘判定一律留在 service（与 strictScope、scopeStateGate
+  // 同处，见 injectCandidates 的位置纪律）。存储层越薄，越不会被绕过。
+
+  /**
+   * 全部 pin 行，按 pin 先后（created_at ASC）——注入就按这个序前置，**先钉的
+   * 排在最前**。预算不够（钉的条数 > pinnedInjectBudget）时，被 eligible.slice
+   * 取走的是最早钉的那几条，最近才钉的排后面、先被挤掉。
+   *
+   * 这个方向和「稳定偏好」的理由是一致的：pin 表达的是「这条我要长期带着」，
+   * 越早做出这个承诺、越久没被撤回，就越该占住名额；若反过来让新钉的优先，
+   * pin 就退化成「最近关注」清单，和 updated_at DESC 那个错误排序键同病。
+   *
+   * 注意排序键是「什么时候钉的」，不是内容的 updated_at——一条 10 月的老记忆
+   * 今天才钉，它在 pin 序里是新的、在内容上是老的，两个轴不要混。
+   * 次键 rowid：同毫秒连钉两条时 UUID 主键排序是随机的，回执要可复现。
+   */
+  function listPinned() {
+    return db.prepare("SELECT * FROM pinned_memories ORDER BY created_at ASC, rowid ASC").all().map(toPinned);
+  }
+
+  /**
+   * 钉住一条记忆。重复 pin 同一 id 不刷新 created_at（只补 note）——pin 顺序
+   * 是「第一次钉的时间」，重钉不该把老偏好的位置往后推。调用方负责确认目标
+   * 记忆存在；这里不做外键校验（本库其余表同款：关系表不设 FK，删记忆时由
+   * unpinMemory 或下一次读的 forgotten/archived 过滤兜住）。
+   */
+  function pinMemory(memoryId, { note, created_at } = {}) {
+    if (typeof memoryId !== "string" || !memoryId.trim()) return undefined;
+    const id = memoryId.trim();
+    const at = normalizeOccurredAt(created_at) ?? nowIso();
+    db.prepare(
+      `INSERT INTO pinned_memories (memory_id, created_at, note) VALUES (?, ?, ?)
+       ON CONFLICT(memory_id) DO UPDATE SET note = COALESCE(excluded.note, pinned_memories.note)`
+    ).run(id, at, normalizeScopeText(note));
+    return toPinned(db.prepare("SELECT * FROM pinned_memories WHERE memory_id = ?").get(id));
+  }
+
+  /** 松开一条 pin。返回实际删掉的行数（0 = 本来就没钉，不是错误）。 */
+  function unpinMemory(memoryId) {
+    if (typeof memoryId !== "string" || !memoryId.trim()) return 0;
+    return db.prepare("DELETE FROM pinned_memories WHERE memory_id = ?").run(memoryId.trim()).changes;
+  }
+
+  /** pin 行数。注入侧靠它判「表是空的」——空表要回落到旧的类型口径。 */
+  function countPinned() {
+    return db.prepare("SELECT count(*) AS c FROM pinned_memories").get().c;
+  }
+
+  /**
+   * 这条记忆是否被显式钉住（单行点查，读侧）。
+   *
+   * 存在的理由是 #593 的缺口：升格吸收（document.js 的 evidence 归档）只拿得到
+   * 记忆行、拿不到 pin 表，于是它只能按**类型**猜「谁属于保真池」。显式 pin 落地
+   * 后，一条 pattern / decision 被钉住仍然是 pin，按类型猜就把它当普通行收走了。
+   * 谓词必须来自本表，不能从类型推——这正是 #593 把 pin 从类型推断改成显式存储
+   * 的同一件事，别在第二个地方又推回去。
+   */
+  function isPinned(memoryId) {
+    if (typeof memoryId !== "string" || !memoryId.trim()) return false;
+    return db.prepare("SELECT 1 AS hit FROM pinned_memories WHERE memory_id = ?").get(memoryId.trim()) !== undefined;
+  }
+
+  /**
+   * 按 id 点查注入所需的行（绕开 200 行窗口的唯一通道）。
+   *
+   * 显式列清单复用 memoryColumnList：它经 PRAGMA 派生、已排除 embedding
+   * （1024 维浮点文本 ≈ 34KB/条，5 条就白搬 170KB 而注入渲染根本不用向量）。
+   * 返回顺序不保证（IN 的求值序），调用方按自己的次序（pin created_at）重排。
+   */
+  function listByIdsForInject(ids) {
+    const wanted = Array.isArray(ids) ? ids.filter((id) => typeof id === "string" && id) : [];
+    if (wanted.length === 0) return [];
+    const placeholders = wanted.map(() => "?").join(", ");
+    return db.prepare(`SELECT ${memoryColumnList} FROM memories WHERE id IN (${placeholders})`)
+      .all(...wanted).map(toRow);
+  }
+
   function getFailureStats({ since } = {}) {
     const clause = since ? "WHERE created_at >= ?" : "";
     const params = since ? [since] : [];
@@ -4010,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
@@ -4246,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);
   }
 
@@ -4707,9 +5140,309 @@ export function createStore(path) {
     });
   }
 
+  // --- chorography 向量（收尾档 P36–P38）---------------------------------
+  // 一页一行（saveChoroPageVector 先删后插）；dim 失配由检索侧判（查询向量
+  // 的 dim ≠ 行 dim → 该行按 stale 处理，惰性全量重嵌）。
+  function getChoroPageVectors(repoId) {
+    return db.prepare(
+      `SELECT v.owner_id, v.dim, v.model, v.vector, v.source_generated_at,
+              m.slug, m.title, p.generated_at AS page_generated_at
+         FROM choro_vectors v
+         JOIN choro_pages p ON v.owner_id = p.id
+         JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ?`
+    ).all(repoId);
+  }
+
+  function saveChoroPageVector(pageId, { vector, dim, model, sourceGeneratedAt, createdAt }) {
+    return runAtomically(() => {
+      db.prepare("DELETE FROM choro_vectors WHERE owner_id = ?").run(pageId);
+      db.prepare(
+        `INSERT INTO choro_vectors (owner_id, dim, model, vector, source_generated_at, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`
+      ).run(pageId, dim, model, JSON.stringify(vector), sourceGeneratedAt, createdAt);
+      return { owner_id: pageId, dim };
+    });
+  }
+
+  // --- 「Agent 眼中的你」自动事实（2026-11-06，profile-facts 域）---
+  // 三张表只服务本域，写路径全部走 runAtomically：facts 与记忆主表零交叉，不需要
+  // service.transaction 的 pendingEmbed/pendingEntity 截断语义（那层是给写记忆行用的）。
+
+  function parseFactIds(text) {
+    if (!text) return [];
+    try {
+      const v = JSON.parse(text);
+      return Array.isArray(v) ? v.map((x) => String(x)) : [];
+    } catch { return []; }
+  }
+
+  function listProfileFacts(agentKey, { includeArchived = false } = {}) {
+    const rows = db.prepare(
+      `SELECT * FROM profile_facts WHERE agent_key = ? ${includeArchived ? "" : "AND status = 'active'"} ORDER BY updated_at DESC, id DESC`
+    ).all(agentKey);
+    return rows.map((r) => ({ ...r, source_memory_ids: parseFactIds(r.source_memory_ids) }));
+  }
+
+  /** 全库活跃事实按卡分组（注入 provider 的读口，见 src/profile-facts.js）。 */
+  function listActiveFactsGrouped() {
+    const rows = db.prepare(
+      "SELECT agent_key, content FROM profile_facts WHERE status = 'active' ORDER BY updated_at DESC"
+    ).all();
+    const grouped = { default: [], byAgent: {} };
+    for (const r of rows) {
+      if (r.agent_key === "") grouped.default.push(r.content);
+      else (grouped.byAgent[r.agent_key] ??= []).push(r.content);
+    }
+    return grouped;
+  }
+
+  function getProfileFact(id) {
+    const r = db.prepare("SELECT * FROM profile_facts WHERE id = ?").get(id);
+    return r ? { ...r, source_memory_ids: parseFactIds(r.source_memory_ids) } : undefined;
+  }
+
+  function insertProfileFact({ id, agentKey, content, sourceMemoryIds = [], at }) {
+    db.prepare(
+      "INSERT INTO profile_facts (id, agent_key, content, status, source_memory_ids, created_at, updated_at) VALUES (?, ?, ?, 'active', ?, ?, ?)"
+    ).run(id, agentKey, String(content), JSON.stringify(sourceMemoryIds ?? []), at, at);
+  }
+
+  /** 返回更新后的行；id 不存在返回 undefined，由调用方记入 failures。 */
+  function updateProfileFact(id, { content, status, sourceMemoryIds, at }) {
+    const cur = getProfileFact(id);
+    if (!cur) return undefined;
+    const next = {
+      content: content ?? cur.content,
+      status: status ?? cur.status,
+      source_memory_ids: sourceMemoryIds ?? cur.source_memory_ids,
+      updated_at: at
+    };
+    db.prepare("UPDATE profile_facts SET content = ?, status = ?, source_memory_ids = ?, updated_at = ? WHERE id = ?")
+      .run(next.content, next.status, JSON.stringify(next.source_memory_ids), next.updated_at, id);
+    return { ...cur, ...next };
+  }
+
+  function insertProfileFactJournal({ at, agentKey, runId = null, factId = null, op, before = null, after = null, actor = "auto" }) {
+    db.prepare(
+      "INSERT INTO profile_fact_journal (at, agent_key, run_id, fact_id, op, before, after, actor) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+    ).run(at, agentKey, runId, factId, op, before, after, actor);
+  }
+
+  function listProfileFactJournal(agentKey, { limit = 20 } = {}) {
+    return db.prepare("SELECT * FROM profile_fact_journal WHERE agent_key = ? ORDER BY id DESC LIMIT ?")
+      .all(agentKey, limit);
+  }
+
+  /** 每卡只留最近 keep 条：账本是审计事实不是检索面，无界增长没有读者。 */
+  function pruneProfileFactJournal(agentKey, keep = 200) {
+    return db.prepare(
+      `DELETE FROM profile_fact_journal WHERE agent_key = ? AND id NOT IN (
+         SELECT id FROM profile_fact_journal WHERE agent_key = ? ORDER BY id DESC LIMIT ?)`
+    ).run(agentKey, agentKey, keep).changes;
+  }
+
+  function insertProfileFactRun({ id, agentKey, triggerSource, status, cursor = null, inputCount = 0, opsApplied = 0, detail = null, startedAt, finishedAt }) {
+    db.prepare(
+      `INSERT INTO profile_fact_runs (id, agent_key, trigger_source, status, cursor, input_count, ops_applied, detail, started_at, finished_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, agentKey, triggerSource, status, cursor, inputCount, opsApplied, detail, startedAt, finishedAt);
+  }
+
+  function listProfileFactRuns(agentKey, { limit = 10 } = {}) {
+    return db.prepare("SELECT * FROM profile_fact_runs WHERE agent_key = ? ORDER BY started_at DESC, id DESC LIMIT ?")
+      .all(agentKey, limit);
+  }
+
+  /** 该卡最近一次 ok 轮的游标。failed 轮不消费——下次重跑同一窗口（蒸馏游标同款纪律）。 */
+  function profileFactsCursor(agentKey) {
+    const row = db.prepare(
+      "SELECT cursor FROM profile_fact_runs WHERE agent_key = ? AND status = 'ok' ORDER BY started_at DESC, id DESC LIMIT 1"
+    ).get(agentKey);
+    return row ? row.cursor : null;
+  }
+
+  /**
+   * 增量输入行：活跃（未归档未遗忘）+ 排除外来行（source IS NULL OR 那一支是三值
+   * 逻辑必填，与 list() 的 excludeImported 同一个坑）+ 严格 scope 分区——agent 卡
+   * 只吃 agent_scope=自己 的行，default 卡只吃 agent_scope IS NULL 的行。
+   * updated_at 是 ISO 串，字典序即时间序，`>` 即「游标之后」（单调时间戳纪律）。
+   */
+  function listFactInputRows(agentKey, { since = null, limit = 120 } = {}) {
+    const scopeClause = agentKey ? "agent_scope = ?" : "agent_scope IS NULL";
+    const params = [IMPORTED_SOURCE, ...(agentKey ? [agentKey] : [])];
+    if (since) params.push(since);
+    params.push(limit);
+    return db.prepare(
+      `SELECT id, type, title, content, importance, updated_at FROM memories
+       WHERE forgotten = 0 AND archived = 0 AND (source IS NULL OR source <> ?)
+         AND ${scopeClause}
+         ${since ? "AND updated_at > ?" : ""}
+       ORDER BY updated_at DESC LIMIT ?`
+    ).all(...params);
+  }
+
+  function countFactInputRows(agentKey, { since = null } = {}) {
+    const scopeClause = agentKey ? "agent_scope = ?" : "agent_scope IS NULL";
+    const params = [IMPORTED_SOURCE, ...(agentKey ? [agentKey] : [])];
+    if (since) params.push(since);
+    return db.prepare(
+      `SELECT COUNT(*) AS n FROM memories
+       WHERE forgotten = 0 AND archived = 0 AND (source IS NULL OR source <> ?)
+         AND ${scopeClause}
+         ${since ? "AND updated_at > ?" : ""}`
+    ).get(...params).n;
+  }
+
+  /**
+   * 自动轮要维护的卡：有 scope 行的记忆身份 ∪ 存量卡片。存量卡即使输入行被清空
+   * 也保留在名单里（手动轮还可能对它做人工修正后的再维护）；'' 由调用方固定追加。
+   */
+  function listFactCardKeys() {
+    return db.prepare(
+      `SELECT DISTINCT agent_scope AS k FROM memories WHERE agent_scope IS NOT NULL
+       UNION
+       SELECT DISTINCT agent_key FROM profile_facts WHERE agent_key <> ''`
+    ).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,
@@ -4749,9 +5482,11 @@ export function createStore(path) {
     setEmbedding,
     getEmbeddings,
     getParsedEmbedding,
+    embeddingCacheStats,
     embeddedCount,
     needsEmbedding,
     needsEmbeddingFor,
+    countNeedsEmbeddingFor,
     hasStaleEmbedding,
     embeddingModelBreakdown,
     embeddingDimensionBreakdown,
@@ -4810,6 +5545,7 @@ export function createStore(path) {
     archivedEmbeddingStats,
     clearArchivedEmbeddings,
     storageStats,
+    capacityStats,
     vacuum,
     saveFailure,
     listFailures,
@@ -4833,6 +5569,15 @@ export function createStore(path) {
     setScopeState,
     getScopeState,
     listScopeStates,
+    // #249 第二批：显式 pin（独立表，绕开候选池的通道）。注入侧只读这里，
+    // 不再拿 PINNED_MEMORY_TYPES 当 pin 标记（那个常量在 write-admission 里
+    // 另有写入配额豁免的语义，两件事不再叠在同一个名字上）。
+    listPinned,
+    pinMemory,
+    unpinMemory,
+    countPinned,
+    isPinned,
+    listByIdsForInject,
     createEntity,
     findEntityByName,
     findEntityById,
@@ -4853,6 +5598,7 @@ export function createStore(path) {
     listBoostedRelations,
     getLinkedMemoryIds,
     saveRelation,
+    updateRelationMetadata,
     bumpRelationWeight,
     migrateAttrsToMemory,
     getRelations,
@@ -4872,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,
@@ -4880,6 +5637,24 @@ export function createStore(path) {
     recordChoroPageFailure,
     markChoroPageEnriched,
     saveChoroPageClaims,
+    getChoroPageVectors,
+    saveChoroPageVector,
+    // 「Agent 眼中的你」自动事实（2026-11-06）：读口与写口都只给 domain 层
+    // （src/profile-facts.js）和 API 层用，记忆主表路径不经此。
+    listProfileFacts,
+    listActiveFactsGrouped,
+    getProfileFact,
+    insertProfileFact,
+    updateProfileFact,
+    insertProfileFactJournal,
+    listProfileFactJournal,
+    pruneProfileFactJournal,
+    insertProfileFactRun,
+    listProfileFactRuns,
+    profileFactsCursor,
+    listFactInputRows,
+    countFactInputRows,
+    listFactCardKeys,
     close() {
       db.close();
     }