recallnest 3.0.0 → 4.0.0

package/src/cli.ts

@@ -10,19 +10,20 @@
  */
 
 import { Command } from "commander";
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 
 import { metaDir } from "./compat.js";
 import { PACKAGE_VERSION } from "./version.js";
-import type { RetrievalResult } from "./retriever.js";
 import { applyRetrievalProfile, listRetrievalProfiles } from "./retrieval-profiles.js";
 import { distillResults, formatExplainResults, formatSearchResults, selectBriefSeedResults, summarizeResults } from "./memory-output.js";
-import { archiveDirtyBriefAsset, assetSummaryLine, buildBriefAsset, buildPinAsset, getExportsDir, listDirtyBriefAssets, listMemoryAssets, listPinAssets, pinSummaryLine, saveBriefAsset, savePinAsset, writeExportArtifact } from "./memory-assets.js";
-import { indexAsset, indexPinnedAsset } from "./asset-sync.js";
-import { createComponents, createStoreOnly, expandHome, loadConfig, loadDotEnv, resolveDbPath, type LocalMemoryConfig } from "./runtime-config.js";
+import { archiveDirtyBriefAsset, assetSummaryLine, buildBriefAsset, formatDirtyBriefEmptyMessage, formatDirtyBriefReadErrors, getExportsDir, listMemoryAssets, scanDirtyBriefAssets, listPinAssets, pinSummaryLine, saveBriefAsset, writeExportArtifact } from "./memory-assets.js";
+import { indexAsset, pinMemory } from "./asset-sync.js";
+import { createComponents, createStoreOnly, expandHome, loadConfig, loadDotEnv, resolveDataDir, resolveDbPath, type LocalMemoryConfig } from "./runtime-config.js";
 import { KGStore } from "./kg-store.js";
+import { extractTriggerCandidates, normalizeTriggerTexts } from "./trigger-store.js";
+import { isActiveMemory } from "./memory-evolution.js";
 import { isKGModeEnabled } from "./kg-extractor.js";
 import {
   formatDedupReasonSummary,
@@ -35,8 +36,11 @@ import {
   ingestMarkdownFiles,
   ingestObsidianVault,
   ingestConnectorFile,
+  parseCCTranscript,
 } from "./ingest.js";
 import { runDoctor, formatDoctorResults } from "./doctor.js";
+import { archiveIngestedMinisFiles, isCompleteJsonl, settledCheck } from "./minis-archive.js";
+import { isProcessed } from "./tracker.js";
 import { persistCaseMemory, persistMemory, persistWorkflowPattern } from "./capture-engine.js";
 import {
   scanMemoryPromotions,
@@ -46,10 +50,17 @@ import {
   formatSynthesisPromoteResult,
 } from "./memory-promotion.js";
 import { runDream, formatDreamResult, formatDreamMetrics, DEFAULT_DREAM_CONFIG, classifyDreamFailure, shouldBlockDreamRun, partitionAutoDreamScopes } from "./dream-pipeline.js";
-import { dreamBudgetMs } from "./env-config.js";
+import { dataDir as envDataDir, dreamBudgetMs, transcriptIngest } from "./env-config.js";
+import { planIngest } from "./ingest-plan.js";
 import { listScopesAboveThreshold, pruneWriteCounts } from "./activity-counter.js";
 import { isTranscriptScope } from "./memory-boundaries.js";
 import { maybeRunGc } from "./auto-gc.js";
+import {
+  formatReconcileSummary,
+  reconcileMemoryDocuments,
+  undoMemoryReconcile,
+  type ReconcileOutcome,
+} from "./memory-reconcile.js";
 import {
   CaseMemoryInputSchema,
   type CaseMemoryInput,
@@ -58,7 +69,9 @@ import {
   WorkflowPatternInputSchema,
   type WorkflowPatternInput,
 } from "./memory-schema.js";
-import { classifyLegacyScope, type MemoryEntry } from "./store.js";
+import { classifyLegacyScope, loadLanceDB, MemoryStore, type MemoryEntry } from "./store.js";
+import { backfillCheckpointMirror, openReadOnlyMirrorReader, purgeCheckpointMirror, type CheckpointMirrorDeps } from "./checkpoint-mirror.js";
+import { autoRegisterBabelMemory } from "./language-hook.js";
 import { ConflictStatusSchema } from "./conflict-schema.js";
 import { resolveConflictCandidate } from "./conflict-engine.js";
 import { escalateConflicts } from "./conflict-escalation.js";
@@ -146,7 +159,8 @@ function resolveSourcePath(source: string, key: string): string {
 }
 
 function formatIngestSummary(result: IngestResult): string {
-  return `${result.filesProcessed} files, ${result.chunksIngested} ingested, ${result.chunksDeduped} deduped (${formatDedupReasonSummary(result)}), ${result.errors.length} errors`;
+  const subagentNote = result.subagentFilesSkipped ? `, ${result.subagentFilesSkipped} subagent files skipped` : "";
+  return `${result.filesProcessed} files, ${result.chunksIngested} ingested, ${result.chunksDeduped} deduped (${formatDedupReasonSummary(result)}), ${result.errors.length} errors${subagentNote}`;
 }
 
 function maybeWarnHighCCDedupRate(result: IngestResult): void {
@@ -268,6 +282,42 @@ function parseRequiredLimitOption(value: string | undefined, field: string, min
   return Math.min(max, Math.max(min, parsed));
 }
 
+/**
+ * 记忆对账动手前的路径核对。锁与审计日志走 envConfig.dataDir()（RECALLNEST_DATA_DIR，否则当前目录下的 data），
+ * 库走 config.dbPath（相对路径按代码所在仓库解析）——两者必须是同一个 data 目录，否则对账拿的锁不是 dream / GC
+ * 用的那把、forget 记录也读错地方；从别的工作区跑时尤其容易错位（第三轮互审 N1）。库里必须已有 memories 表，
+ * 免得路径写错时对着一个新建的空库「对账」。
+ */
+function checkReconcilePaths(
+  config: LocalMemoryConfig,
+  options: { requireTable?: boolean } = {},
+): { ok: boolean; reason: string; dataDir: string; dbPath: string } {
+  const dbPath = resolveDbPath(config);
+  const dataDir = resolve(envDataDir());
+  const real = (p: string): string => {
+    try { return realpathSync(p); } catch { return p; }
+  };
+  if (real(dataDir) !== real(resolveDataDir(config))) {
+    return { ok: false, reason: `锁与审计目录 ${dataDir} 和库所在目录 ${resolveDataDir(config)} 不一致（从仓库根目录运行，或设 RECALLNEST_DATA_DIR）`, dataDir, dbPath };
+  }
+  if (options.requireTable !== false && !existsSync(join(dbPath, "memories.lance"))) {
+    return { ok: false, reason: `库目录里没有 memories 表：${dbPath}`, dataDir, dbPath };
+  }
+  return { ok: true, reason: "", dataDir, dbPath };
+}
+
+function reconcileToIngestResult(outcome: ReconcileOutcome): IngestResult {
+  return {
+    source: "memory",
+    filesProcessed: outcome.plan?.currentFiles ?? 0,
+    chunksIngested: outcome.applied?.inserted ?? 0,
+    chunksSkipped: 0,
+    chunksDeduped: 0,
+    dedupReasonCounts: { hard: 0, exact: 0, "llm-skip": 0, "llm-merge": 0, unique: 0 },
+    errors: outcome.applied?.insertErrors ?? [],
+  };
+}
+
 function toScopeFilter(scope?: string): string[] | undefined {
   const trimmed = typeof scope === "string" ? scope.trim() : "";
   return trimmed ? [trimmed] : undefined;
@@ -459,18 +509,6 @@ function collectRepeatedOption(value: string, previous: string[] = []): string[]
   return [...previous, value];
 }
 
-function entryToRetrievalResult(entry: Awaited<ReturnType<MemoryStore["get"]>>): RetrievalResult {
-  if (!entry) {
-    throw new Error("Memory entry not found.");
-  }
-  return {
-    entry,
-    score: entry.importance || 0.7,
-    sources: {
-      fused: { score: entry.importance || 0.7 },
-    },
-  };
-}
 
 // ─── search ──────────────────────────────────────────────────────────────────
 
@@ -554,17 +592,17 @@ program
       return;
     }
 
-    const pinnedImportance = Math.max(entry.importance || 0.7, 0.95);
-    await store.update(entry.id, { importance: pinnedImportance }, scopeSelection.scopeFilter);
-
-    const asset = buildPinAsset(entryToRetrievalResult(entry), {
+    const pinned = await pinMemory(store, embedder, entry, scopeSelection.scopeFilter, {
       title: options.title,
       summary: options.summary,
       query: options.query,
       profile: options.profile,
     });
-    const path = savePinAsset(asset);
-    await indexPinnedAsset(store, embedder, asset);
+    if (!pinned) {
+      console.log(`Memory not found: ${memoryId}`);
+      return;
+    }
+    const { asset, path } = pinned;
 
     console.log([
       `Pinned   : ${asset.id.slice(0, 8)}`,
@@ -657,9 +695,11 @@ program
   .description("归档旧规则生成的脏 brief，并从索引删除对应 asset scope")
   .option("--apply", "执行清理；默认只预览")
   .action(async (options) => {
-    const dirty = listDirtyBriefAssets();
+    const scan = scanDirtyBriefAssets();
+    const dirty = scan.items;
+    const readErrors = formatDirtyBriefReadErrors(scan.readErrors);
     if (dirty.length === 0) {
-      console.log("No dirty briefs found.");
+      console.log(formatDirtyBriefEmptyMessage(scan));
       return;
     }
 
@@ -669,6 +709,7 @@ program
         console.log(`${item.id.slice(0, 8)}  ${item.title}  [${item.scope}]  ${item.reasons.join("; ")}`);
       }
       console.log("\nRun with --apply to archive files and delete their indexed asset scopes.");
+      if (readErrors) console.log(`\n${readErrors}`);
       return;
     }
 
@@ -688,6 +729,7 @@ program
       `Archived    : ${archived}`,
       `Index rows  : ${deleted}`,
     ].join("\n"));
+    if (readErrors) console.log(`\n${readErrors}`);
   });
 
 program
@@ -1103,6 +1145,109 @@ conflictsCommand
     console.log(formatConflictResolution(result));
   });
 
+const kgFilterHelp = (cmd: string) => `
+过滤选项（默认全关；一个都不传时输出与不带这组选项时完全一样）：
+  ${cmd === "kg-compare" ? "只过滤分组候选一侧，再拿过滤后的候选做双向对照；正则一侧不变。\n  " : ""}依次过 谓词白名单 → 函数型判定 → 证据门槛，输出 funnel：每一步还剩多少组，没启用的标 skipped。
+  JSON 另带 predicateStats：本 scope 每个谓词的 subjects / pairs / functionality / multiValuedSubjects，
+  按 functionality 降序。
+  functionality = 用到该谓词的不同 subject 数 ÷ 不同 (subject, 归一化 object) 对数，取值 (0, 1]，
+  越接近 1 越像「一个主体同一时间只有一个值」（located_in 这类）。有候选组的谓词恒 < 1。
+
+示例：
+  conflicts ${cmd} --scope memory:pivot --functional-min 0.8 --json
+  conflicts ${cmd} --scope memory:pivot --functional-min 0.8 --min-second-mentions 2
+  conflicts ${cmd} --scope memory:pivot --predicates located_in,owned_by
+`;
+
+/** 四个过滤选项挂到命令上（kg-candidates / kg-compare 共用）。 */
+function withKGFilterOptions(command: Command): Command {
+  const kgFilterHelpText = kgFilterHelp(command.name());
+  return command
+    .option("--predicates <list>", "谓词白名单，逗号分隔，精确匹配（谓词本身不归一化）")
+    .option("--functional-min <ratio>", "只留 functionality ≥ ratio 的谓词上的候选组，ratio ∈ (0, 1]，例如 0.8")
+    .option("--functional-min-subjects <n>", "配合 --functional-min：谓词的 subject 少于 n 个按不满足处理（默认 3）")
+    .option("--min-second-mentions <n>", "只留第二多取值的 mention_count ≥ n 的组（默认 1，即不过滤）")
+    .addHelpText("after", kgFilterHelpText);
+}
+
+withKGFilterOptions(
+  conflictsCommand
+    .command("kg-candidates")
+    .description("只读：KG 三元组按 (subject, predicate) 分组的多值候选（影子期，候选非判决）")
+    .requiredOption("--scope <scope>", "scope（精确匹配）")
+    .option("-n, --limit <n>", "按排序取前 n 组", "20")
+    .option("--sample <n>", "改为随机抽 n 组（确定性，配 --seed）")
+    .option("--seed <seed>", "抽样种子", "1")
+    .option("--json", "JSON 格式输出"),
+).action(async (options) => {
+  const {
+    filterKGCandidates,
+    findKGContradictionCandidates,
+    formatCandidateReport,
+    hasCandidateFilter,
+    loadScopeTriples,
+    parseCandidateFilterArgs,
+    sampleCandidates,
+  } = await import("./kg-contradiction.js");
+  const filterOpts = parseCandidateFilterArgs(options);
+  const dbPath = resolveDbPath(loadConfig());
+  const triples = await loadScopeTriples(dbPath, options.scope);
+  const all = findKGContradictionCandidates(triples);
+  const filtered = hasCandidateFilter(filterOpts) ? filterKGCandidates(all, triples, filterOpts) : undefined;
+  const candidates = filtered ? filtered.candidates : all;
+  const sampling = options.sample !== undefined;
+  const n = sampling ? parseRequiredLimitOption(options.sample, "--sample", 1, 1000) : parseLimitOption(options.limit, 20, 1, 1000);
+  const seed = Number.parseInt(String(options.seed), 10) || 1;
+  const shown = sampling ? sampleCandidates(candidates, n, seed) : candidates.slice(0, n);
+  const mode = sampling ? `random sample n=${n} seed=${seed}` : `top ${n}`;
+
+  if (options.json) {
+    const filterFields = filtered ? { funnel: filtered.funnel, predicateStats: filtered.predicateStats } : {};
+    console.log(JSON.stringify({ scope: options.scope, tripleCount: triples.length, candidateCount: candidates.length, mode, ...filterFields, candidates: shown }, null, 2));
+    return;
+  }
+  console.log(formatCandidateReport(options.scope, triples.length, candidates.length, shown, mode, filtered?.funnel));
+});
+
+withKGFilterOptions(
+  conflictsCommand
+    .command("kg-compare")
+    .description("只读：同一 scope 上现有正则矛盾检测 (memory lint) 与 KG 分组候选的双向对照")
+    .requiredOption("--scope <scope>", "scope（精确匹配）")
+    .option("-n, --limit <n>", "文本输出每节最多列几条；0 = 全部", "0")
+    .option("--json", "JSON 格式输出（始终完整）"),
+).action(async (options) => {
+  const {
+    compareRegexWithCandidates,
+    filterKGCandidates,
+    findKGContradictionCandidates,
+    formatComparisonReport,
+    hasCandidateFilter,
+    loadRegexInput,
+    loadScopeTriples,
+    parseCandidateFilterArgs,
+    regexHitPairs,
+  } = await import("./kg-contradiction.js");
+  const filterOpts = parseCandidateFilterArgs(options);
+  const dbPath = resolveDbPath(loadConfig());
+  const [triples, regexInput] = await Promise.all([loadScopeTriples(dbPath, options.scope), loadRegexInput(dbPath, options.scope)]);
+  const all = findKGContradictionCandidates(triples);
+  // 过滤只作用在分组候选一侧；正则一侧与判断「有没有三元组」用的全部三元组都不变
+  const filtered = hasCandidateFilter(filterOpts) ? filterKGCandidates(all, triples, filterOpts) : undefined;
+  const candidates = filtered ? filtered.candidates : all;
+  const pairs = regexHitPairs(regexInput.entries);
+  const cmp = compareRegexWithCandidates(pairs, candidates, triples, new Set(regexInput.entries.map((e) => e.id)));
+  const meta = { tripleCount: triples.length, regexInputCount: regexInput.entries.length, scanLimited: regexInput.scanLimited };
+
+  if (options.json) {
+    const filterFields = filtered ? { funnel: filtered.funnel, predicateStats: filtered.predicateStats } : {};
+    console.log(JSON.stringify({ scope: options.scope, ...meta, ...filterFields, ...cmp }, null, 2));
+    return;
+  }
+  const limit = Number.parseInt(String(options.limit), 10);
+  console.log(formatComparisonReport(options.scope, meta, cmp, Number.isFinite(limit) && limit > 0 ? limit : 0, filtered?.funnel));
+});
+
 program
   .command("seed-patterns [file]")
   .description("批量写入 continuity / workflow pattern seeds")
@@ -1420,6 +1565,51 @@ program
       return;
     }
     const results: any[] = [];
+    // 记忆对账没执行 / 出错 / 护栏拦下（24 小时去抖后）→ 整条 ingest 以退出码 3 结束，调用脚本据此发专门的报警
+    let memoryReconcileAlert = false;
+    // 对话原文 2026-10-06 起默认不入库（RECALLNEST_TRANSCRIPT_INGEST=on 才入）；这一轮跑哪些来源见 ingest-plan.ts
+    const plan = planIngest(source, transcriptIngest());
+    if (plan.skippedTranscriptSources.length > 0) {
+      console.log(`\n⏸  对话入库已关（RECALLNEST_TRANSCRIPT_INGEST 没有设为 on）：${plan.skippedTranscriptSources.join(" / ")} 不切片、不嵌入、不写库`);
+      console.log("   原文在 Deja 里查；Minis 投递目录的文件照样挪进存档；记忆文件照常。要重开见 env-config.ts transcriptIngest");
+    }
+
+    // Minis 投递目录 → data/minis-archive（Deja 从那里读，记忆库不读它），原因见 minis-archive.ts 文件头。
+    // 入库开着：先入库，再只挪台账里记着已入库的。入库关着：没有「已入库」可等，放稳了（至少 60 秒没被改过）、
+    // 整个文件写完了、能解析出对话的就挪——这里要是照旧拿台账当闸，文件永远不会被标成已处理，也就永远进不了 Deja，而且不报错。
+    const runMinis = async (ingestOpts?: { limit?: number; verbose: boolean; noDedup: boolean; llm: typeof llm | null; recentHours?: number }) => {
+      const minisSource = config.sources.minis;
+      if (!minisSource) return;
+      const minisPath = resolveSourcePath(minisSource.path, "minis");
+      if (!existsSync(minisPath)) {
+        if (source === "minis") console.log(`⚠️  Minis 目录不存在: ${minisPath}`);
+        return;
+      }
+      if (plan.minis === "ingest-then-archive" && ingestOpts) {
+        console.log("📱 导入 Minis 对话...");
+        const r = await ingestCCTranscripts(store, embedder, minisPath, { ...ingestOpts, scopePrefix: "minis" });
+        results.push(r);
+        console.log(`  ✅ Minis: ${formatIngestSummary(r)}`);
+      } else {
+        console.log("📱 Minis 对话：不入库，只挪存档...");
+      }
+      const archiveDir = resolve(metaDir(import.meta), "..", "data", "minis-archive");
+      const moved = archiveIngestedMinisFiles(
+        minisPath,
+        archiveDir,
+        plan.minis === "ingest-then-archive" ? isProcessed : settledCheck(),
+        // 关着时多看一条「文件写完了」：解析会跳过残缺行，半截文件也解析得出对话
+        (p) => (plan.minis === "ingest-then-archive" || isCompleteJsonl(p)) && parseCCTranscript(p).length > 0,
+      );
+      if (moved.archived.length > 0 || moved.errors.length > 0) {
+        const failed = moved.errors.length > 0
+          ? `，${moved.errors.length} 个出错、原件留在原处：${moved.errors.join("；")}`
+          : "";
+        console.log(`  📦 Minis 存档: ${moved.archived.length} 个移入 data/minis-archive${failed}`);
+      }
+    };
+    // 只挪存档用不着嵌入接口，所以排在接口预检之前：接口挂了（预检失败会直接退出）也不耽误对话进 Deja
+    if (plan.minis === "archive-only") await runMinis();
 
     // Pre-flight: validate embedding API before processing any files
     console.log("\n🔑 验证 Embedding API...");
@@ -1449,8 +1639,8 @@ program
       console.log("  ⚠️  LLM: 未配置，原始对话将跳过不存入（配置 config.json → llm 以启用）");
     }
 
-    // Drain pending queue if LLM is available
-    if (effectiveLlm) {
+    // Drain pending queue if LLM is available（队列里是对话切片，回填等于入库，跟着对话入库的开关走）
+    if (effectiveLlm && plan.drainPendingQueue) {
       const { drainPendingQueue } = await import("./ingest.js");
       const drained = await drainPendingQueue(store, embedder, effectiveLlm);
       if (drained.processed > 0) {
@@ -1469,7 +1659,7 @@ program
 
     // CC Transcripts
     // CC 按 cwd 编码 project 子目录，所有有 jsonl 的子目录都要 ingest（不只是 jsonl 最多的那个）
-    if (source === "all" || source === "cc") {
+    if (plan.transcriptSources.includes("cc")) {
       console.log("📝 导入 Claude Code 对话...");
       const ccSource = config.sources.cc;
       if (ccSource) {
@@ -1489,7 +1679,7 @@ program
     }
 
     // Codex Sessions
-    if (source === "all" || source === "codex") {
+    if (plan.transcriptSources.includes("codex")) {
       console.log("🤖 导入 Codex 对话...");
       const r = await ingestCodexSessions(store, embedder, ingestOpts);
       results.push(r);
@@ -1497,7 +1687,7 @@ program
     }
 
     // Kimi Code Sessions (wire.jsonl 事件流，~/.kimi-code/sessions/)
-    if (source === "all" || source === "kimi") {
+    if (plan.transcriptSources.includes("kimi")) {
       console.log("🌙 导入 Kimi Code 对话...");
       const r = await ingestKimiSessions(store, embedder, ingestOpts);
       results.push(r);
@@ -1505,7 +1695,7 @@ program
     }
 
     // Gemini Sessions (JSON format under ~/.gemini/tmp/*/chats/)
-    if (source === "all" || source === "gemini") {
+    if (plan.transcriptSources.includes("gemini")) {
       console.log("💎 导入 Gemini 对话...");
       const r = await ingestGeminiSessions(store, embedder, {
         limit,
@@ -1519,7 +1709,7 @@ program
     }
 
     // Claude Desktop / claude.ai web conversations (CC transcript format)
-    if (source === "all" || source === "desktop") {
+    if (plan.transcriptSources.includes("desktop")) {
       const desktopSource = config.sources.desktop;
       if (desktopSource) {
         const desktopPath = resolve(metaDir(import.meta), "..", desktopSource.path);
@@ -1538,29 +1728,14 @@ program
     // Minis (iPhone) —— 手机 agent 自己把对话写进这个目录，ingest 顺带扫走。
     // 为什么是独立源而不是复用 desktop：scope 前缀决定了 memory-boundaries 怎么降权，
     // 混在 cc: 里的话来源在库里就分辨不出来（那正是 2026-08-12 起挂着的缺口）。
-    if (source === "all" || source === "minis") {
-      const minisSource = config.sources.minis;
-      if (minisSource) {
-        const minisPath = resolveSourcePath(minisSource.path, "minis");
-        if (existsSync(minisPath)) {
-          console.log("📱 导入 Minis 对话...");
-          const r = await ingestCCTranscripts(store, embedder, minisPath, {
-            ...ingestOpts,
-            scopePrefix: "minis",
-          });
-          results.push(r);
-          console.log(`  ✅ Minis: ${formatIngestSummary(r)}`);
-        } else if (source === "minis") {
-          console.log(`⚠️  Minis 目录不存在: ${minisPath}`);
-        }
-      }
-    }
+    if (plan.minis === "ingest-then-archive") await runMinis(ingestOpts);
 
     // Memory markdown files
-    if (source === "all" || source === "memory") {
+    if (plan.memory) {
       console.log("📚 导入记忆文件...");
       const memSource = config.sources.memory;
-      if (memSource) {
+      if (memSource && memSource.path === "auto") {
+        // auto 路径保持旧行为（追加式导入 + 全库判重）；对账只在显式配置路径时启用（互审 K4）
         const memPath = resolveSourcePath(memSource.path, "memory");
         const r = await ingestMarkdownFiles(store, embedder, memPath, "memory", {
           verbose,
@@ -1570,6 +1745,36 @@ program
         });
         results.push(r);
         console.log(`  ✅ Memory: ${formatIngestSummary(r)}`);
+      } else if (memSource) {
+        // 显式路径：按文件对账（src/memory-reconcile.ts）。它每轮全量比对现行文件，--recent / --limit 不适用（互审 K2）
+        if (recentHours !== undefined || limit !== undefined) {
+          console.log("  ℹ️  记忆文件走对账（每轮全量比对现行文件），--recent / --limit 对它不生效");
+        }
+        const paths = checkReconcilePaths(config);
+        if (!paths.ok) {
+          console.log(`  ⚠️ Memory: 对账没有执行——${paths.reason}`);
+          memoryReconcileAlert = true;
+        } else {
+          try {
+            const outcome = await reconcileMemoryDocuments({
+              store,
+              embedder,
+              llm: effectiveLlm,
+              auditLogger: createAuditLogger(),
+              memDir: resolveSourcePath(memSource.path, "memory"),
+              dataDir: paths.dataDir,
+              explicitPath: true,
+              apply: true,
+            });
+            results.push(reconcileToIngestResult(outcome));
+            console.log(`  ✅ Memory: ${formatReconcileSummary(outcome)}`);
+            if (outcome.journalPath) console.log(`     对账日志: ${outcome.journalPath}`);
+            if (outcome.alert) memoryReconcileAlert = true;
+          } catch (err) {
+            console.log(`  ❌ Memory: 对账出错——${err instanceof Error ? err.message : String(err)}`);
+            memoryReconcileAlert = true;
+          }
+        }
       }
     }
 
@@ -1629,6 +1834,233 @@ program
       `  总计: ${totalChunks} chunks 已索引, ${totalDeduped} chunks 去重 (hard:${totalDedupReasons.hard}, exact:${totalDedupReasons.exact}, llm-skip:${totalDedupReasons["llm-skip"]}, llm-merge:${totalDedupReasons["llm-merge"]}), ${totalErrors} errors`,
     );
     console.log();
+    if (memoryReconcileAlert) {
+      console.log("⚠️ 记忆对账需要人看（见上面 Memory: 行），以退出码 3 结束");
+      process.exitCode = 3;
+    }
+  });
+
+// ─── checkpoint-mirror-backfill ───────────────────────────────────────────────
+// checkpoint 镜像（src/checkpoint-mirror.ts）的一次性回填：每场会话取最新的 rich checkpoint 写进 scope
+// `checkpoint`，已是这一版的跳过，可重复跑。输出只有计数，不打印 checkpoint 正文。
+// --db-path / --checkpoints-dir 只给演练用：指向生产库以外的副本；指向配置里的生产库会被拒绝（生产库不传这个参数）。
+
+program
+  .command("checkpoint-mirror-backfill")
+  .description("把现有 checkpoint 按会话取最新一份镜像进记忆库（scope checkpoint；默认写库，--dry-run 只数）")
+  .option("--dry-run", "只数会做什么，不嵌入、不写库")
+  .option("--db-path <dir>", "演练用：写进这个 LanceDB 副本，而不是配置里的生产库")
+  .option("--checkpoints-dir <dir>", "演练用：从这个目录读 checkpoint，而不是 data/session-checkpoints")
+  .action(async (options: { dryRun?: boolean; dbPath?: string; checkpointsDir?: string }) => {
+    const config = loadConfig();
+    // The mirror's write lock lives under the data dir resolved from the working directory, the
+    // database under the repo; both must be the ones the running MCP / API processes use, or the
+    // backfill and a live save would hold different locks (互审 R3 N1). Run from the repo root.
+    // A drill copy given on the command line — not config.dbPath, which only resolveDbPath reads.
+    const drillCopy = options.dbPath;
+    const paths = checkReconcilePaths(config, { requireTable: !drillCopy });
+    if (!paths.ok) {
+      console.error(`❌ ${paths.reason}`);
+      process.exitCode = 2;
+      return;
+    }
+    const { store: prodStore, embedder } = createComponents(config);
+    let dbPath = paths.dbPath;
+    if (drillCopy) {
+      const target = realpathSync(resolve(expandHome(drillCopy)));
+      if (existsSync(paths.dbPath) && target === realpathSync(paths.dbPath)) {
+        console.error("❌ --db-path 指向的就是生产库；写生产库不传这个参数");
+        process.exitCode = 2;
+        return;
+      }
+      if (!existsSync(join(target, "memories.lance"))) {
+        console.error(`❌ 库目录里没有 memories 表：${target}`);
+        process.exitCode = 2;
+        return;
+      }
+      dbPath = target;
+    }
+    const { SessionCheckpointStore } = await import("./session-store.js");
+    const checkpointStore = options.checkpointsDir
+      ? new SessionCheckpointStore(resolve(expandHome(options.checkpointsDir)))
+      : new SessionCheckpointStore();
+    const records = await checkpointStore.listRecent({ limit: Number.MAX_SAFE_INTEGER });
+    console.log(`库: ${dbPath}`);
+    console.log(`checkpoint 目录: ${checkpointStore.dataDir}`);
+    let deps: CheckpointMirrorDeps;
+    if (options.dryRun) {
+      // Plain reads only — MemoryStore's initialization could add columns or build an index.
+      const reader = await openReadOnlyMirrorReader(dbPath);
+      deps = {
+        store: { getById: (id: string) => reader.getById(id), upsertUnlessNewer: async () => { throw new Error("dry run does not write"); } },
+        embedder,
+      };
+    } else {
+      // Same tokenizer the MCP server registers at startup, so backfilled rows get the same
+      // language / fts_text as rows the MCP tool writes (互审 R3 N3).
+      await autoRegisterBabelMemory();
+      deps = { store: drillCopy ? new MemoryStore({ dbPath, vectorDim: embedder.dimensions }) : prodStore, embedder };
+    }
+    const result = await backfillCheckpointMirror(deps, records, {
+      dryRun: Boolean(options.dryRun),
+      onProgress: (done, total) => {
+        if (done % 50 === 0 || done === total) console.log(`  ${done}/${total}`);
+      },
+    });
+    console.log(JSON.stringify({ dryRun: Boolean(options.dryRun), ...result }, null, 2));
+    if ((result.statuses.failed ?? 0) > 0) process.exitCode = 1;
+  });
+
+// ─── checkpoint-mirror-purge ─────────────────────────────────────────────────
+// 撤回 checkpoint 镜像：建 data/checkpoint-mirror.off 停掉所有进程的镜像写入（每次写都读它），
+// 再持镜像写锁按 scope 精确等于 checkpoint 删除。不带 --yes 只数不删。恢复镜像：删掉开关文件。
+
+program
+  .command("checkpoint-mirror-purge")
+  .description("撤回 checkpoint 镜像：停写并删除 scope 恰为 checkpoint 的全部行（不带 --yes 只数）")
+  .option("--yes", "确认执行")
+  .action(async (options: { yes?: boolean }) => {
+    const config = loadConfig();
+    const paths = checkReconcilePaths(config);
+    if (!paths.ok) {
+      console.error(`❌ ${paths.reason}`);
+      process.exitCode = 2;
+      return;
+    }
+    console.log(`库: ${paths.dbPath}`);
+    if (!options.yes) {
+      const table = await (await (await loadLanceDB()).connect(paths.dbPath)).openTable("memories");
+      console.log(`scope = 'checkpoint' 的行数: ${await table.countRows("scope = 'checkpoint'")}（加 --yes 才会停写并删除）`);
+      return;
+    }
+    const result = await purgeCheckpointMirror(paths.dbPath);
+    console.log(JSON.stringify(result, null, 2));
+    console.log("开关文件 data/checkpoint-mirror.off 已建，镜像写入已停；要恢复，删掉这个文件。几分钟后再跑一次本命令（不带 --yes）确认仍是 0。");
+    if (result.rowsAfter !== 0) process.exitCode = 1;
+  });
+
+// ─── reconcile-memory ────────────────────────────────────────────────────────
+// 记忆文件对账的手动入口：默认只打印计划不写库；--apply 执行；--undo 按对账日志逐条撤销。
+// 定时导入（ingest）在显式配置 sources.memory.path 时自动做同一件事，这里是给首轮存量清理、
+// 护栏拦下后人工放行、以及出问题时撤销用的。输出只有数量、文件名和 id 前 8 位，不打印切片正文。
+
+program
+  .command("reconcile-memory")
+  .description("记忆文件对账：让 memory 源的文档切片与现行记忆文件一一对应（默认只看计划，不写库）")
+  .option("--apply", "执行：插入 → 恢复 → 下架")
+  .option("--max-retire <n>", "本次下架上限（默认 max(300, 活跃文档切片数的 25%)，也可用 RECALLNEST_MEMORY_RECONCILE_MAX_RETIRE）")
+  .option("--undo <journal>", "按对账日志（data/reconcile-journals/*.jsonl）逐条撤销")
+  .option("--json", "以 JSON 输出计划与结果")
+  .action(async (options) => {
+    const config = loadConfig();
+    const paths = checkReconcilePaths(config);
+    console.log(`库: ${paths.dbPath}`);
+    console.log(`数据目录（锁 / 审计 / 对账日志）: ${paths.dataDir}`);
+    if (!paths.ok) {
+      console.error(`❌ ${paths.reason}`);
+      process.exitCode = 2;
+      return;
+    }
+    const { store, embedder, llm } = createComponents(config);
+
+    if (options.undo) {
+      const journalPath = resolve(String(options.undo));
+      let r: Awaited<ReturnType<typeof undoMemoryReconcile>>;
+      try {
+        r = await undoMemoryReconcile({ store, auditLogger: createAuditLogger() }, journalPath, { auditPath: join(paths.dataDir, "audit.jsonl") });
+      } catch (err) {
+        console.error(`❌ ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 2;
+        return;
+      }
+      const ids8 = (ids: string[]) => `${ids.slice(0, 20).map((id) => id.slice(0, 8)).join(" ")}${ids.length > 20 ? ` …（共 ${ids.length}）` : ""}`;
+      console.log(`撤销完成：写回 ${r.restored} 条，本轮插入的 ${r.insertsRetired} 条改为下架，期间被改过而跳过 ${r.skippedConflict.length} 条，合并链依赖未满足而保留 ${r.skippedDependency.length} 条，文字已被 forget 而保留非活跃 ${r.skippedForgotten.length} 条`);
+      if (r.skippedConflict.length > 0) console.log(`  被改过而跳过的 id（前 8 位）: ${ids8(r.skippedConflict)}`);
+      if (r.skippedDependency.length > 0) console.log(`  保留的合并链成员 id（它原来指向的那一行已不活跃、或本次撤销会把它撤掉，撤了会断链）: ${ids8(r.skippedDependency)}`);
+      if (r.skippedForgotten.length > 0) console.log(`  文字已被 forget、没撤回活跃的 id: ${ids8(r.skippedForgotten)}`);
+      if (r.unparsedLines > 0) console.log(`  ⚠️ 日志里有 ${r.unparsedLines} 行解析不了（多半是写到一半的截断尾行），已跳过`);
+      console.log(`撤销日志: ${r.undoJournalPath}`);
+      console.log("⚠️ 撤销后把 sources.memory.path 改回 auto 或暂停导入，否则下一轮对账会按现行文件重新对一遍");
+      return;
+    }
+
+    const memSource = config.sources.memory;
+    if (!memSource || memSource.path === "auto") {
+      console.error("❌ 需要在 config.json 里显式配置 sources.memory.path（当前为 auto 或未配置）");
+      process.exitCode = 2;
+      return;
+    }
+    const memDir = resolveSourcePath(memSource.path, "memory");
+    console.log(`记忆目录: ${memDir}`);
+    const maxRetire = options.maxRetire !== undefined
+      ? parseRequiredLimitOption(options.maxRetire, "--max-retire", 0, Number.MAX_SAFE_INTEGER)
+      : undefined;
+
+    const outcome = await reconcileMemoryDocuments({
+      store,
+      embedder,
+      llm,
+      auditLogger: createAuditLogger(),
+      memDir,
+      dataDir: paths.dataDir,
+      explicitPath: true,
+      apply: Boolean(options.apply),
+      maxRetire,
+    });
+
+    const plan = outcome.plan;
+    const countBy = <T,>(items: T[], key: (item: T) => string): Record<string, number> => {
+      const out: Record<string, number> = {};
+      for (const item of items) out[key(item)] = (out[key(item)] ?? 0) + 1;
+      return out;
+    };
+    const topFiles = (items: Array<{ file: string | null }>): Array<[string, number]> =>
+      Object.entries(countBy(items, (i) => i.file ?? "(无文件名)")).sort((a, b) => b[1] - a[1]).slice(0, 10);
+
+    if (options.json) {
+      console.log(JSON.stringify({
+        ran: outcome.ran,
+        skippedReason: outcome.skippedReason ?? null,
+        mode: options.apply ? "apply" : "dry-run",
+        maxRetire: outcome.maxRetire,
+        guard: outcome.guard,
+        alert: outcome.alert,
+        journalPath: outcome.journalPath,
+        plan: plan && {
+          currentFiles: plan.currentFiles,
+          currentChunks: plan.currentChunks,
+          currentDistinct: plan.currentDistinct,
+          existingRows: plan.existingRows,
+          activeDocRows: plan.activeDocRows,
+          filesWithActiveDocRows: plan.filesWithActiveDocRows,
+          keep: plan.keep,
+          insert: plan.insert.length,
+          insertAltId: plan.insertAltId,
+          insertByFile: topFiles(plan.insert.map((i) => ({ file: i.chunk.file }))),
+          retire: plan.retire.length,
+          retireByReason: countBy(plan.retire, (r) => r.reason),
+          retireByFile: topFiles(plan.retire),
+          reactivate: countBy(plan.reactivate, (r) => `${r.kind}${r.kind === "broken-consolidation" && r.targetRetiredThisRun ? "(目标本轮下架)" : ""}`),
+          representedByConsolidation: plan.representedByConsolidation,
+          exceptionForgotten: plan.exceptionForgotten,
+          exceptionOtherInactive: plan.exceptionOtherInactive,
+          exceptionOtherInactiveIds: plan.exceptionOtherInactiveIds.map((id) => id.slice(0, 8)),
+        },
+        applied: outcome.applied,
+      }, null, 2));
+    } else {
+      console.log(`\n${options.apply ? "执行结果" : "计划（未写库，加 --apply 执行）"}: ${formatReconcileSummary(outcome)}`);
+      if (plan) {
+        console.log(`  库里 scope "memory" 共 ${plan.existingRows} 行，其中活跃文档切片 ${plan.activeDocRows} 条、涉及 ${plan.filesWithActiveDocRows} 个文件；单轮下架上限 ${outcome.maxRetire}`);
+        const byReason = countBy(plan.retire, (r) => r.reason);
+        if (plan.retire.length > 0) console.log(`  下架按原因: ${Object.entries(byReason).map(([k, v]) => `${k} ${v}`).join("，")}`);
+        if (plan.retire.length > 0) console.log(`  下架最多的文件: ${topFiles(plan.retire).map(([f, n]) => `${f} ${n}`).join("，")}`);
+        if (plan.insert.length > 0) console.log(`  插入最多的文件: ${topFiles(plan.insert.map((i) => ({ file: i.chunk.file }))).map(([f, n]) => `${f} ${n}`).join("，")}`);
+        if (plan.exceptionOtherInactive > 0) console.log(`  例外②（同文只剩被别的机制下架的行，未推翻）id 前 8 位: ${plan.exceptionOtherInactiveIds.slice(0, 20).map((id) => id.slice(0, 8)).join(" ")}`);
+      }
+      if (outcome.journalPath) console.log(`  对账日志（撤销用）: ${outcome.journalPath}`);
+    }
+    if (outcome.alert) process.exitCode = 3;
   });
 
 // ─── dream ───────────────────────────────────────────────────────────────────
@@ -2057,6 +2489,94 @@ program
 
 // ─── doctor ──────────────────────────────────────────────────────────────────
 
+program
+  .command("triggers-backfill")
+  .description("T-Mem triggers 回填：从正文抠「她以后会怎么问」句写入 memory_triggers 侧表（默认 dry-run，零 LLM）")
+  .option("-s, --scope <scope>", "限定 scope", "memory:pivot")
+  .option("-n, --limit <n>", "最多扫描条数", "5000")
+  .option("--apply", "真写入（默认只预览）")
+  .option("--include-batch", "连 tags 含 pivot-apply 的批量提炼条目一起回填（默认跳过：09-21 校准其走样率约七成，先别给它们加联想入口）")
+  .option("--rebuild", "不看正文，只按 metadata.triggers 重建侧表（迁移 / 回滚后恢复用）")
+  .option("--samples <n>", "预览时打印几条样例", "12")
+  .action(async (options) => {
+    const config = loadConfig();
+    const { store, embedder, triggerStore } = createComponents(config);
+    const scopeFilter = toScopeFilter(options.scope);
+    const limit = parseLimitOption(options.limit, 5000, 1, 100000);
+    const samples = parseLimitOption(options.samples, 12, 0, 200);
+    const entries = await store.list(scopeFilter, undefined, limit, 0);
+    const already = options.rebuild ? new Set<string>() : await triggerStore.listMemoryIds(scopeFilter);
+    const counts = { scanned: 0, skippedBatch: 0, skippedInactive: 0, skippedHas: 0, noLine: 0, planned: 0, written: 0, rows: 0 };
+    const preview: Array<{ id: string; triggers: string[] }> = [];
+    for (const entry of entries) {
+      counts.scanned += 1;
+      if (!isActiveMemory(entry.metadata)) { counts.skippedInactive += 1; continue; }
+      let meta: Record<string, unknown> = {};
+      try { meta = JSON.parse(entry.metadata || "{}"); } catch { meta = {}; }
+      const tags = Array.isArray(meta.tags) ? (meta.tags as unknown[]).map(String) : [];
+      let texts: string[];
+      if (options.rebuild) {
+        texts = normalizeTriggerTexts(Array.isArray(meta.triggers) ? (meta.triggers as unknown[]).map(String) : []);
+        if (texts.length === 0) { counts.noLine += 1; continue; }
+      } else {
+        if (!options.includeBatch && tags.includes("pivot-apply")) { counts.skippedBatch += 1; continue; }
+        const hasMeta = Array.isArray(meta.triggers) && (meta.triggers as unknown[]).length > 0;
+        if (already.has(entry.id) || hasMeta) { counts.skippedHas += 1; continue; }
+        texts = extractTriggerCandidates(entry.text);
+        if (texts.length === 0) { counts.noLine += 1; continue; }
+      }
+      counts.planned += 1;
+      if (preview.length < samples) preview.push({ id: entry.id.slice(0, 8), triggers: texts });
+      if (!options.apply) continue;
+      const n = await triggerStore.upsertForMemory(entry.id, entry.scope, texts, (t) => embedder.embedBatchQuery(t));
+      counts.rows += n;
+      counts.written += 1;
+      if (!options.rebuild) {
+        meta.triggers = texts;
+        await store.update(entry.id, { metadata: JSON.stringify(meta) });
+      }
+    }
+    const mode = options.apply ? "APPLY" : "DRY-RUN";
+    console.log(`[triggers-backfill ${mode}] scope=${options.scope} scanned=${counts.scanned} planned=${counts.planned}` +
+      ` skipped(batch=${counts.skippedBatch} inactive=${counts.skippedInactive} already=${counts.skippedHas}) noLine=${counts.noLine}` +
+      (options.apply ? ` written=${counts.written} rows=${counts.rows}` : ""));
+    for (const p of preview) console.log(`  ${p.id}  ${p.triggers.map((t) => `「${t}」`).join(" ")}`);
+    if (options.apply) {
+      const stat = await triggerStore.stats(scopeFilter);
+      console.log(`侧表现状：${stat.rows} 条 trigger / ${stat.memories} 个宿主（scope=${options.scope}）`);
+    } else {
+      console.log("（预览。加 --apply 真写入）");
+    }
+  });
+
+program
+  .command("triggers-calibrate")
+  .description("T-Mem trigger 硬闸校准：对 canary 用例逐条打印 query 对侧表 trigger 的最高余弦（不看 gate），用来定 RECALLNEST_TRIGGER_GATE")
+  .option("--cases <path>", "canary 文件", "eval/cases-canary.json")
+  .option("-s, --scope <scope>", "限定 scope（缺省用各 case 自己的 scope）")
+  .option("-k, --top <n>", "每条打印几个命中", "4")
+  .action(async (options) => {
+    const config = loadConfig();
+    const { embedder, triggerStore } = createComponents(config);
+    const { readFileSync } = require("node:fs");
+    const { resolve: resolvePath } = require("node:path");
+    const raw = JSON.parse(readFileSync(resolvePath(options.cases), "utf8"));
+    const cases: Array<{ name: string; query: string; scope?: string; targets?: string[] }> = Array.isArray(raw) ? raw : raw.cases;
+    const top = parseLimitOption(options.top, 4, 1, 20);
+    const stat = await triggerStore.stats();
+    console.log(`侧表：${stat.rows} 条 trigger / ${stat.memories} 个宿主`);
+    for (const c of cases) {
+      const scope = options.scope || c.scope;
+      const qv = await embedder.embedQuery(c.query);
+      const hits = await triggerStore.search(qv, top, scope ? [scope] : undefined, { minCosine: 0, softCosine: 0, minOverlap: 0, minQueryTokens: 0, queryText: c.query });
+      const targets = c.targets || [];
+      const line = hits
+        .map((h) => `${h.memoryId.slice(0, 8)}${targets.some((t) => h.memoryId.startsWith(t)) ? "✓" : " "} cos=${h.cosine.toFixed(3)} ov=${(h.overlap ?? 0).toFixed(2)}「${h.text.slice(0, 28)}」`)
+        .join(" | ");
+      console.log(`${c.name}\n  ${line || "(no trigger rows in scope)"}`);
+    }
+  });
+
 program
   .command("memory-utility")
   .description("价值回溯：查一条 memory 参与过的任务成功率与 utility（不传 id 时按 scope 批量）")