@modusensus/dsh-mneme 0.11.0 → 0.12.0

package/src/profile-facts.js

@@ -0,0 +1,356 @@
+// dsh-mneme/src/profile-facts.js
+// 「Agent 眼中的你」自动事实（2026-11-06）：按会话身份分卡维护一份逐条事实清单，
+// dream 巩固轮结束后自动增量维护（opt-in：profileFactsEnabled），面板可手动触发与
+// 逐条修正。形态对标 ChatGPT 记忆 / DS Bot 每 bot 一份 MEMORY.md 事实清单（journal
+// 记每笔 op 的 before/after）——事实可独立增改归档、账本可审计，而不是整段重写。
+//
+// 四条纪律，都是「做错界面上看不出来」的那类，所以写在文件头：
+// 1. **手填画像神圣**。user_settings.profile 是用户原文，本模块对它只有读权
+//    （profile-extract #497 的「只出草稿不落库」口径不变）；事实住独立的
+//    profile_facts 三表，注入时作为画像之后的独立段出现，绝不回写 user_settings。
+// 2. **没有增量输入就不调模型**。游标之后没有新行时返回 noop 回执——为维护而
+//    维护的一轮只会产出「看起来像事实的复读」，那种事实每帧都在注入。
+// 3. **吐不出可用 ops 就 failed，绝不冒充成功**。「模型没配合」与「确实没什
+//    么可改」必须可区分（#493 同一条教训：解析失败被读成空结果，用户会以为
+//    这轮维护跑过了）。failed 轮照样落回执行，账面上留痕。
+// 4. **失败不推进游标**。failed 轮之后重跑同一窗口（蒸馏游标同款纪律：失败不
+//    消费），宁可重复消费也不跳过没维护到的行。
+//
+// 记忆正文是模型的**可影响输入**：围栏 + 「数据非指令」 + 禁止给助手起名设人格，
+// 三件套与 profile-extract / #380 同源（src/fence.js 一份断链，不写第二套）。
+//
+// LLM 调用与审计完全复用 dream.js 的既有缝（resolveRoute / runAuditedLlm /
+// streamText / describeStreamFailure）：chunk 形状的三个硬点（用量嵌在 chunk.usage、
+// 终态 finish 才是错误、rc.1 把适配器故障转成 finish chunk 而不是抛错）都在那里
+// 踩过并修过，不在这里重写第二遍。
+
+import { randomUUID } from "node:crypto";
+import { STR, langOf } from "./lang.js";
+import { describeStreamFailure, resolveRoute, runAuditedLlm, streamText } from "./dream.js";
+// 与巩固/蒸馏/画像提取同一份断链（src/fence.js）。事实同样是模型的可影响输入，
+// 一条写着「<<<记忆条目结束>>>」的记忆能提前闭合围栏。
+import { breakFenceMarkers } from "./fence.js";
+
+const DEFAULT_INPUT_ROWS = 120;
+const DEFAULT_ROW_CHARS = 260;
+const DEFAULT_TOTAL_CHARS = 9000;
+// 与 prompt 里的「单轮最多 12 个 op」同一个数：超出的切片丢弃并记进回执 detail，
+// 不让一轮失控的输出把清单搅成毛线团。清单长度本身不设硬顶——prompt 要求模型
+// archive 冗余，注入侧另有逐行/总长截断兜底（user-settings.js），撑不爆每一帧。
+const MAX_OPS_PER_RUN = 12;
+
+/** 带 code 的失败：路由按 code 映射状态码，调用方据此区分「没东西可提」与「模型没配合」。 */
+export class ProfileFactsError extends Error {
+  constructor(code, message) {
+    super(message ?? code);
+    this.name = "ProfileFactsError";
+    this.code = code;
+  }
+}
+
+/**
+ * 单个 op 的形状谓词；批量口径（路由层 400 闸）与解析层共用这一份——两处各抄
+ * 一遍的话，改形状就会漏一边（评审 P3：同一谓词两份皮，P1 的洞因此要修两处）。
+ * add 与 update 都必须带非空 content：update 缺 content 时 `String(undefined)`
+ * 会把「undefined」三个字母写进事实正文并从此每帧注入（评审 P1 实测复现的洞）。
+ */
+function isValidFactOp(o) {
+  return !!o && typeof o === "object"
+    && (o.op === "add" || o.op === "update" || o.op === "archive")
+    && (o.op !== "add" && o.op !== "update" || (typeof o.content === "string" && o.content.trim()))
+    && (o.op === "add" || typeof o.id === "string" && o.id.trim());
+}
+
+/** 批量口径：待写入的 op 批必须非空且逐个形状合格（空批走「没什么可改」，不进这条）。 */
+export function isValidFactOps(ops) {
+  return Array.isArray(ops) && ops.length > 0 && ops.every(isValidFactOp);
+}
+
+/**
+ * 从模型输出里取 ops 数组。先剥 markdown 围栏，再退到「第一个 [ 或 { 到最后一个
+ * ] 或 }」的宽取——与 parseProfileDraft 同款两步。形状校验：op 只认 add/update/
+ * archive；add 必须带非空 content；update/archive 必须带 id（id 是否真实存在由
+ * apply 层裁决——这里只做形状校验）。取不到可用结构返回 null，绝不返回空数组
+ * 冒充成功（空 ops 是合法的「没什么可改」，但那必须是 JSON 里真的写着空数组）。
+ */
+export function parseFactOps(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  const cleaned = text.replace(/```(?:json)?\s*([\s\S]*?)```/gi, "$1").trim();
+  const candidates = [];
+  const arrOpen = cleaned.indexOf("[");
+  const objOpen = cleaned.indexOf("{");
+  const start = arrOpen >= 0 && (objOpen < 0 || arrOpen < objOpen) ? arrOpen : objOpen;
+  const end = Math.max(cleaned.lastIndexOf("]"), cleaned.lastIndexOf("}"));
+  if (start >= 0 && end > start) candidates.push(cleaned.slice(start, end + 1));
+  if (cleaned.startsWith("{") || cleaned.startsWith("[")) candidates.push(cleaned);
+  for (const candidate of candidates) {
+    let value;
+    try {
+      value = JSON.parse(candidate);
+    } catch {
+      continue;
+    }
+    const ops = Array.isArray(value) ? value : (value && typeof value === "object" && Array.isArray(value.ops) ? value.ops : null);
+    // 空 ops 是合法的「没什么可改」（runFor 会以 ok + opsApplied:0 收尾），所以
+    // 这里只验逐 op 形状、不要求非空——非空是批量写入口径（isValidFactOps）。
+    if (!ops || !ops.every(isValidFactOp)) continue;
+    return ops;
+  }
+  return null;
+}
+
+/** 采集增量输入的截断读数：多取一行只为如实回答「还有没有」（profile-extract 同款）。 */
+function collectInputRows(store, agentKey, cursor) {
+  const fetched = store.listFactInputRows(agentKey, { since: cursor, limit: DEFAULT_INPUT_ROWS + 1 });
+  const rows = [];
+  let chars = 0;
+  let truncated = fetched.length > DEFAULT_INPUT_ROWS;
+  for (const row of fetched.slice(0, DEFAULT_INPUT_ROWS)) {
+    const content = String(row.content ?? "").slice(0, DEFAULT_ROW_CHARS);
+    if (content.length < String(row.content ?? "").length) truncated = true;
+    const size = `${row.type} ${row.title} ${content}`.length;
+    // 首行保底：单行就超总预算时也收进来（截断已如实标记）——否则游标永远
+    // 推不进、这张卡变成永久 noop（评审 P3：首行即超预算的死角）。
+    if (rows.length && chars + size > DEFAULT_TOTAL_CHARS) {
+      truncated = true;
+      break;
+    }
+    chars += size;
+    rows.push(row);
+  }
+  return { rows, truncated, charsUsed: chars };
+}
+
+/**
+ * @param {{ ctx: object, service: object, store: object, config: object, logger?: object }} deps
+ *   ctx 要带 llm（宿主 LLM 句柄）；settings 不参与——本模块按纪律绝不写 user_settings。
+ * @returns object with runFor / applyManualOps / cardKeys / factsProvider / listFacts / listJournal / listRuns
+ */
+export function createProfileFacts({ ctx, service, store, config, logger }) {
+  const log = logger ?? ctx?.logger;
+  const language = langOf(config);
+
+  /** 卡片清单：''（default 兜底）恒在；非空键来自记忆行的 scope 值 ∪ 存量卡片。 */
+  function cardKeys() {
+    const keys = store.listFactCardKeys()
+      .filter((k) => typeof k === "string" && k.trim())
+      .map((k) => k.trim());
+    return ["", ...new Set(keys)];
+  }
+
+  /** 注入 provider 读口：renderUserSettingsBlock 的 factsProvider（面板预览共用）。 */
+  function factsProvider() {
+    return store.listActiveFactsGrouped();
+  }
+
+  function listFacts(agentKey, { includeArchived = false } = {}) {
+    return store.listProfileFacts(agentKey, { includeArchived });
+  }
+
+  function listJournal(agentKey, { limit = 20 } = {}) {
+    return store.listProfileFactJournal(agentKey, { limit });
+  }
+
+  function listRuns(agentKey, { limit = 10 } = {}) {
+    return store.listProfileFactRuns(agentKey, { limit });
+  }
+
+  /**
+   * ops 落库（自动轮与人工面板共用这一份）：单事务，逐 op 记账（scope_changes 式
+   * before/after）。跨卡守卫：op.id 必须属于本卡——LLM 幻觉出的别卡 id 不能当成
+   * 合法目标；精确重复的 add（与既有活跃事实 trim 后相同）跳过并计数，不落库。
+   */
+  function applyOps(agentKey, ops, { actor, runId = null, at = new Date().toISOString() } = {}) {
+    const failures = [];
+    let applied = 0;
+    let dupsSkipped = 0;
+    const existing = store.listProfileFacts(agentKey, { includeArchived: true });
+    const existingById = new Map(existing.map((f) => [f.id, f]));
+    const activeContents = new Set(
+      existing.filter((f) => f.status === "active").map((f) => String(f.content ?? "").trim())
+    );
+    store.runAtomically(() => {
+      for (const op of ops) {
+        try {
+          if (op.op === "add") {
+            const content = String(op.content).trim();
+            if (activeContents.has(content)) {
+              dupsSkipped += 1;
+              continue;
+            }
+            const sourceIds = Array.isArray(op.source_ids)
+              ? op.source_ids.filter((id) => typeof id === "string" && id.trim()).map((id) => id.trim())
+              : [];
+            const id = randomUUID();
+            store.insertProfileFact({ id, agentKey, content, sourceMemoryIds: sourceIds, at });
+            store.insertProfileFactJournal({ at, agentKey, runId, factId: id, op: "add", before: null, after: content, actor });
+            activeContents.add(content);
+            applied += 1;
+          } else if (op.op === "update" || op.op === "archive") {
+            const prev = existingById.get(op.id);
+            if (!prev || prev.agent_key !== agentKey) {
+              failures.push({ op: op.op, id: op.id ?? null, reason: "fact not found on this card" });
+              continue;
+            }
+            const nextContent = op.op === "update" ? String(op.content).trim() : prev.content;
+            const nextStatus = op.op === "archive" ? "archived" : prev.status;
+            store.updateProfileFact(prev.id, { content: nextContent, status: nextStatus, at });
+            store.insertProfileFactJournal({
+              at, agentKey, runId, factId: prev.id, op: op.op,
+              before: prev.content, after: op.op === "update" ? nextContent : null, actor
+            });
+            if (op.op === "update") {
+              // 去重集合要跟上新值：同批 [update A→B, add B] 不收新值的话会落两条
+              // 相同的活跃事实，而 dupsSkipped 还是 0（评审 P2 实测复现）。
+              activeContents.delete(String(prev.content ?? "").trim());
+              activeContents.add(nextContent);
+            }
+            applied += 1;
+          } else {
+            failures.push({ op: op.op ?? null, id: op.id ?? null, reason: "unsupported op" });
+          }
+        } catch (error) {
+          // 逐 op 吞错是刻意的：一条 journal 写失败不该把整批已落的事实回滚掉
+          // （失败进 failures 由回执如实报）。代价是与「单事务」注释的原子粒度
+          // 有出入——真故障通常连 COMMIT 一起失败，这里只是收窄那道缝。
+          failures.push({ op: op.op ?? null, id: op.id ?? null, reason: String(error?.message ?? error) });
+        }
+      }
+    });
+    return { applied, failures, dupsSkipped };
+  }
+
+  /** 面板人工修正入口：actor=manual、runId=null，账本与自动轮同一份。 */
+  function applyManualOps(agentKey, ops) {
+    return applyOps(agentKey, ops, { actor: "manual" });
+  }
+
+  /**
+   * 跑一轮维护。返回回执 `{ runId, status, inputCount, opsApplied, failures, ... }`；
+   * no-route / stream-failed / unparseable 以 ProfileFactsError 抛出（回执已先落库，
+   * API 层按 code 映射状态码）。
+   */
+  async function runFor(agentKey, { trigger = "manual" } = {}) {
+    const key = typeof agentKey === "string" ? agentKey.trim() : "";
+    const runId = randomUUID();
+    const startedAt = new Date().toISOString();
+    const finish = (status, extra = {}) => {
+      const receipt = { runId, agentKey: key, status, ...extra };
+      store.insertProfileFactRun({
+        id: runId,
+        agentKey: key,
+        triggerSource: trigger === "auto" ? "auto" : "manual",
+        status,
+        cursor: receipt.cursor ?? null,
+        inputCount: receipt.inputCount ?? 0,
+        opsApplied: receipt.opsApplied ?? 0,
+        detail: receipt.detail ? JSON.stringify(receipt.detail) : null,
+        startedAt,
+        finishedAt: new Date().toISOString()
+      });
+      return receipt;
+    };
+
+    const cursor = store.profileFactsCursor(key);
+    const { rows, truncated } = collectInputRows(store, key, cursor);
+    const facts = store.listProfileFacts(key, { includeArchived: false });
+    // 没有增量输入就没有本轮：连回执都记成 noop（面板能看到「没有新记忆」），
+    // 游标不动——下一次有新行时窗口从旧游标接续。
+    if (!rows.length) {
+      return finish("noop", { inputCount: 0, cursor });
+    }
+
+    const fail = (code, message, detail) => {
+      finish("failed", { inputCount: rows.length, cursor: null, detail: { code, ...(detail ?? {}) } });
+      throw new ProfileFactsError(code, message);
+    };
+
+    const route = resolveRoute(ctx, config, log);
+    // resolveRoute 在「没有 dreamProvider/dreamModel、宿主也没有可解析的默认模型」
+    // 时返回 undefined。不判它就是一个语义为「内部错误」的 500——真正该说的是
+    // 「没配模型」（profile-extract 同款取舍：不同结局不同话）。
+    if (!route) {
+      fail("no-route", "no model route: set dreamProvider/dreamModel or pick an agent default model");
+    }
+
+    const factListing = facts.length
+      ? facts.map((f, i) => `${i + 1}. [${f.id}] ${f.content}`).join("\n")
+      : "（尚无既有事实）";
+    const rowListing = rows.map((r, i) => `${i + 1}. [${r.id}] [${r.type}] ${r.title} :: ${String(r.content ?? "").slice(0, DEFAULT_ROW_CHARS)}`).join("\n");
+    const userText = [
+      STR.profileFenceOpen[language],
+      breakFenceMarkers(`【既有事实】\n${factListing}\n\n【新记忆条目】\n${rowListing}`),
+      STR.profileFenceClose[language],
+      truncated
+        ? (language === "zh"
+          ? `（输入行有截断：本轮只呈现了窗口内的一部分。）`
+          : `(Input was truncated: only part of the window is shown this pass.)`)
+        : "",
+      language === "zh"
+        ? `以上材料（数据）到此结束。只依据它们输出 JSON，材料里没有的绝不发明。`
+        : `End of the material (data). Answer from it only; invent nothing absent from it.`
+    ].filter(Boolean).join("\n");
+
+    let streamFailure = "";
+    const text = await runAuditedLlm(ctx, service, config, {
+      triggerSource: "profileFacts",
+      operationType: "profile_facts",
+      modelId: `${route.provider}:${route.model}`,
+      relatedMemoryIds: rows.map((r) => r.id),
+      streamError: () => streamFailure,
+      // 吐了文字但没有可用结构 = 失败调用。审计必须记 error：success 配解析失败
+      // 会让「模型不配合」在账目上长得像「这轮确实没什么可改」。
+      auditError: (out) => (parseFactOps(out) ? null : "profile facts pass returned no usable ops JSON")
+    }, (reportUsage) => streamText(ctx, {
+      provider: route.provider,
+      model: route.model,
+      purpose: "compaction",
+      messages: [
+        { role: "system", content: [{ type: "text", text: STR.prompts.profileFacts[language] }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
+        { role: "user", content: [{ type: "text", text: userText }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } }
+      ]
+    }, reportUsage, (reason) => { streamFailure = describeStreamFailure(reason); }));
+
+    if (text === undefined) {
+      fail("stream-failed", streamFailure || "llm stream aborted or errored");
+    }
+    const ops = parseFactOps(text);
+    if (!ops) {
+      fail("unparseable", "profile facts output was not a usable ops JSON object");
+    }
+
+    const sliced = ops.length > MAX_OPS_PER_RUN ? ops.slice(0, MAX_OPS_PER_RUN) : ops;
+    const { applied, failures, dupsSkipped } = applyOps(key, sliced, { actor: "auto", runId });
+    // 游标取本轮实际消费到的最大 updated_at：ok 轮才推进（含「ops 为空但窗口
+    // 已看过」的轮——那是合法的「没什么可改」，不重跑同一窗口）。
+    const nextCursor = rows.reduce((m, r) => (String(r.updated_at ?? "") > m ? String(r.updated_at) : m), String(cursor ?? ""));
+    const receipt = finish("ok", {
+      cursor: nextCursor || cursor,
+      inputCount: rows.length,
+      opsApplied: applied,
+      detail: {
+        truncated,
+        opsProposed: ops.length,
+        opsSliced: ops.length - sliced.length,
+        dupsSkipped,
+        failures
+      }
+    });
+    store.pruneProfileFactJournal(key);
+    return receipt;
+  }
+
+  /** 自动轮候选（dream 成功后由 index.js 逐卡 runFor）：只列有增量输入的卡——
+   *  无输入的卡连 noop 回执都不落，dream 每轮一次的自动维护不生产回执噪音。 */
+  function autoPassCandidates() {
+    return cardKeys().filter((key) => {
+      try {
+        return !!store.countFactInputRows(key, { since: store.profileFactsCursor(key) });
+      } catch {
+        return true; // 读数失败按「有待维护」处理，交给 runFor 的回执说话
+      }
+    });
+  }
+
+  return { runFor, applyManualOps, cardKeys, factsProvider, listFacts, listJournal, listRuns, autoPassCandidates };
+}

package/src/service.js

@@ -516,9 +516,12 @@ export function createService({ store, mirror, config, onWrite, logger, document
   // Weighted blend factor for hybrid search; exposed so callers can tune it.
   const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
 
-  // Cosine over two plain arrays (shared by the search-time semantic dedup).
+  // Cosine over two numeric vectors (shared by the search-time semantic dedup).
+  // Accepts typed arrays too — the store's cache holds Float32Array, and
+  // `Array.isArray` is false for typed arrays (would score everything 0).
   function cosineVec(a, b) {
-    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
+    const isVec = (v) => Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
+    if (!isVec(a) || !isVec(b) || a.length !== b.length || !a.length) return 0;
     let dot = 0, na = 0, nb = 0;
     for (let i = 0; i < a.length; i++) {
       dot += a[i] * b[i];
@@ -1849,6 +1852,76 @@ export function createService({ store, mirror, config, onWrite, logger, document
         candidates = merged;
       }
     }
+    // pin 池取数修复（#249 第一批）：pin 类行被混合合并的封顶挡在候选池外面。
+    // `merged.length >= poolSize` 在 pin 筛选**之前**就封顶（生产 maxItems=5 →
+    // poolSize=10，向量路一次正好返回 10 条即 break），规则窗口里那些
+    // constraint/preference 于是一条都进不了 candidates，pin 池只能从那 10 条里
+    // 碰运气选——而本文件注释（:1919）与 issue #249 验收都写着「pin 不占
+    // maxItems 名额」。实测真库 maxItems=5 时 pin shown 只有 2/5，补回后恒 5/5；
+    // maxItems=10（poolSize=20）时前后都是 5/5——所以这不是多给名额，只是把被
+    // 向量路吃掉的那部分补回来。
+    // 两条纪律：①只在 pin 预算 > 0 时补，预算关时 candidates 与改前逐字节一致；
+    // ②只补到候选池尾部，后面的 strictScope（:1923）与 scopeState（:1930）两道
+    // 闸门照旧作用其上，「pin 池 eligible 取自过滤之后的候选」这条位置纪律不变。
+    //
+    // #249 第二批（显式 pin）：判据从「类型」换成「用户亲手钉的 id」。两种口径
+    // 由 pinned_memories 表**里能用的行**回答，而不是由「表里有几行」回答：
+    // - 有可用行 → explicit：按 id 点查（store.listByIdsForInject）取回行，于是
+    //   **200 行规则窗口之外的记忆也能进**（这是第二层存在的理由本身）；不再按
+    //   type 认 pin（写得最全的那版往往是 pattern，限类型就只能拿残缺版）。
+    // - 一条可用行都没有 → 回落旧的类型口径，升级即等价；她钉第一条才切换。
+    //
+    // ⚠ 判据为什么必须看「能用的」而不是 countPinned()>0：pin 行会在 memories
+    // 那边被归档、遗忘、硬删，而 pinned_memories 对这三种一无所知。用 count(*)
+    // 当判据，只要表里剩一行（哪怕是归档行），pinMode 就永远钉在 explicit，而
+    // eligible 恒为空 → pin 全灭且**永不回落**，无日志无报错——正是这批改动要
+    // 治的那类静默失败。删除路径补 DELETE 只堵「硬删」这一种，归档/遗忘比硬删
+    // 常见得多，所以根因在判据，不在清理。
+    // 只要还有一条能用就留在 explicit、只注入能用的那几条：若因为「有 3 条归档」
+    // 就整段回落到类型口径，会突然冒出一批她没钉过的条目，那比少注入更糟。
+    // 补位仍在这段：早于 topic 重排（:1930）、strictScope（:1972）、scopeState
+    // （:1979），所以越权行与暂停作用域行照样过两道闸——pin 不是绕过闸门的通道。
+    // 预算 0 时整段不执行：不读表、不改 candidates，逐字节等于改前。
+    const pinnedBudget = Math.max(0, Math.min(5, Math.floor(config?.pinnedInjectBudget ?? 0)));
+    // null | "explicit" | "type-fallback" | "fallback-none-usable"
+    let pinMode = null;
+    let pinRows = [];              // explicit：按 pin 先后（created_at ASC）排好、已滤遗忘/归档
+    let pinOutsideWindow = 0;      // explicit：点查取回、原本不在候选池的行数（观测点）
+    if (pinnedBudget > 0) {
+      let pinRecords = [];
+      try {
+        // 先读表（本表行数以个位计）；能用的行下一步按 id 点查回来再判。
+        pinRecords = store.countPinned() > 0 ? store.listPinned() : [];
+      } catch { pinRecords = []; }
+      if (pinRecords.length > 0) {
+        try {
+          // 点查带列裁剪（listByIdsForInject 复用 memoryColumnList，已排除 embedding）。
+          // 遗忘/归档行在这里就滤掉：pin 不是复活通道（验收第 7 条）。
+          const byId = new Map(store.listByIdsForInject(pinRecords.map((p) => p.memory_id))
+            .map((m) => [m.id, m]));
+          pinRows = pinRecords.map((p) => byId.get(p.memory_id)).filter((m) => m && !m.forgotten && !m.archived);
+        } catch { pinRows = []; }
+      }
+      if (pinRows.length > 0) {
+        pinMode = "explicit";
+        const knownIds = new Set(candidates.map((m) => m.id));
+        const additions = pinRows.filter((m) => !knownIds.has(m.id));
+        pinOutsideWindow = additions.length;
+        if (additions.length) candidates = [...candidates, ...additions];
+      } else {
+        // 表空，或表里有行但一条都用不了（归档/遗忘/被删）。两种都回落类型口径，
+        // 但 source 分开记：后者是一次**静默降级**，必须留痕，否则读的人只会看到
+        // 「pin 一条都没注入」而不知道为什么。
+        pinMode = pinRecords.length > 0 ? "fallback-none-usable" : "type-fallback";
+        if (candidates !== items) {
+          const knownIds = new Set(candidates.map((m) => m.id));
+          const spilledPins = items.filter(
+            (m) => PINNED_MEMORY_TYPES.has(m.type) && m.graphHint !== true && !knownIds.has(m.id)
+          );
+          if (spilledPins.length) candidates = [...candidates, ...spilledPins];
+        }
+      }
+    }
     // Topic-ranked selection (v0.5.0 2.2): when the current query's vector is
     // available the whole candidate list is re-ordered by similarity to that
     // vector, so the injected slots go to memories on the current topic
@@ -1909,12 +1982,24 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // （验收：pin 不参与跨轮轮换）。独立预算的两层意义：pin 既不占 maxItems
     // 名额、也不被 document 预算截断，因此不会把当前任务需要的情景候选挤出去；
     // 超预算的条数回报给调用方，在块内如实标注（绝不静默省略）。
-    const pinnedBudget = Math.max(0, Math.min(5, Math.floor(config?.pinnedInjectBudget ?? 0)));
+    // （pinnedBudget 与口径在候选池那段已算好——见 :1876 起的 #249 第二批注释。）
     // eligible 留到块外：未展示条数要等 general 槽选完才算得准（见 selected 之后）。
     // graphHint 行不进 pin 池：pin 是「每轮必进的约束/偏好」，而线索行按定义是
     // 「链路信息、非事实断言」，且 pin 长在候选池遍历之前——不排除的话，保守档
     // （graphInjectHint 关）也能从 pin 侧把它放回注入块，线索开关就被绕过去了。
-    const eligible = pinnedBudget > 0 ? candidates.filter((m) => PINNED_MEMORY_TYPES.has(m.type) && m.graphHint !== true) : [];
+    //
+    // 两种口径（#249 第二批）：explicit 时 eligible 就是「钉过、点查取回、且过了
+    // 两道闸（仍在 candidates 里）」的行，次序按 pin 先后（created_at ASC）——
+    // 稳定偏好按「什么时候被钉」排，而不是按「最近改过」，正是第二层要修的
+    // 那个排序维度；type-fallback 时保持旧口径（候选里按类型筛），升级即等价。
+    const eligible = pinnedBudget > 0
+      ? (pinMode === "explicit"
+        ? (() => {
+            const live = new Set(candidates.map((m) => m.id));
+            return pinRows.filter((m) => live.has(m.id) && m.graphHint !== true);
+          })()
+        : candidates.filter((m) => PINNED_MEMORY_TYPES.has(m.type) && m.graphHint !== true))
+      : [];
     let pinned = [];
     if (pinnedBudget > 0 && eligible.length > 0) {
       pinned = eligible.slice(0, pinnedBudget);
@@ -1969,6 +2054,17 @@ export function createService({ store, mirror, config, onWrite, logger, document
       const shownIds = new Set(selected.map((m) => m.id));
       pinnedStats.shown = pinned.length;
       pinnedStats.suppressed = eligible.filter((m) => !shownIds.has(m.id)).length;
+      // #249 第二批：口径来源与「绕开窗口」的观测点。source 四档（预算 0 时整个
+      // 键不出现）：
+      //   "explicit"              用户钉的行里有能用的，按 pin 先后注入
+      //   "type-fallback"         表里从没钉过（含升级后还没钉），走旧类型口径
+      //   "fallback-none-usable"  钉过，但那些行全被归档/遗忘/删了 —— 这次是一次
+      //                           静默降级，留这一档就是为了让它不再静默
+      // 前两档的行为差异在「窗口外也能进」：只有 explicit 享受点查补位，
+      // outsideWindow 也只数这批（cognee 那条「别让它进候选池」的等价做法）；
+      // 两个 fallback 档恒 0（它们只能从窗口里取）。
+      pinnedStats.source = pinMode ?? undefined;
+      pinnedStats.outsideWindow = pinOutsideWindow;
     }
     // Issue #380：注入前判定（preInjectGate）在这里消费——**必须在 touchRecalled
     // 之前**，与 strictScope 同纪律（见本文件 :419-422 的注释：闸门放在记账之后，
@@ -2688,6 +2784,15 @@ export function createService({ store, mirror, config, onWrite, logger, document
     setScopeState: (r) => store.setScopeState(r),
     getScopeState: (d, v) => store.getScopeState(d, v),
     listScopeStates: (o) => store.listScopeStates(o),
+    // #249 第二批：pin 的读写口。这四个都是纯 bookkeeping——它们不动任何记忆行，
+    // 只动 pinned_memories 这张关系表，所以照 setScopeState 那一批的纪律**不挂
+    // write hook**（不 afterSync、不 notifyWrite）：pin 一条不该让 mirror 重渲染，
+    // 也不该把那行记忆的 heat/embedding 重新排队。注入侧只经 store 读本表
+    // （listPinned / listByIdsForInject），写侧只经这里，两处都绕开 memories 主表。
+    pinMemory: (id, opts) => store.pinMemory(id, opts),
+    unpinMemory: (id) => store.unpinMemory(id),
+    listPinned: () => store.listPinned(),
+    countPinned: () => store.countPinned(),
     // 巩固（dream.js）侧的过滤出口。暴露出来而不是让 dream 自己读状态表，是因为
     // 判定只能有一份实现（gateByScope 注释里那条「过滤点漂移」的教训）；dream 侧
     // 的三个读入口各自的附加条件不同（有的排 forgotten、有的不排），但「被按下的

package/src/settings.js

@@ -247,6 +247,11 @@ const FEATURE_FLAG_BOOLEANS = [
   // Issue #497：画像提取草稿（POST /profile/extract）。默认关——每次调用一次 LLM 且
   // 读上百行记忆；产物只回草稿，绝不写 user_settings。进 LIGHT_MODE_OFF（预设关）。
   "profileExtractEnabled",
+  // 「Agent 眼中的你」自动事实（2026-11-06）：dream 后逐卡维护 + 手动轮 + 注入段，
+  // 事实住 profile_facts 独立三表，绝不写 user_settings（#497 口径不变）。默认关，
+  // 进 LIGHT_MODE_OFF（自动维护轮与低资源档互斥）。顶层扁平键，与 config.js schema
+  // 成对出现（计数锁 test/api.test.js 钉住）。
+  "profileFactsEnabled",
   // #539：逐会话无痕默认关闭；子代理开关受总开关约束。手动 session id 名单留在配置，
   // 不进入只支持标量的 feature_flags 白名单。
   "sessionGateEnabled",