recallnest 2.6.0 → 3.0.0

package/src/auto-gc.ts

@@ -14,7 +14,7 @@ import {
   parseEvolution,
   computeDecayScore,
   computeUsageAdjustedDecayScore,
-  buildArchivedMetadata,
+  patchEvolutionOnMeta,
   isActiveMemory,
 } from "./memory-evolution.js";
 import { loadRetentionPolicy, shouldArchiveByPolicy } from "./retention-policy.js";
@@ -23,6 +23,7 @@ import type { AuditLogger } from "./audit-log.js";
 import * as envConfig from "./env-config.js";
 import { isUsageSignalActive } from "./usage-tracker.js";
 import { acquireLock, releaseLock, getLastDistillTime, stampLock, lockPathForKey } from "./distill-lock.js";
+import { logInfo } from "./stderr-log.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -54,6 +55,7 @@ export const DEFAULT_AUTO_GC_CONFIG: AutoGcConfig = {
 // ---------------------------------------------------------------------------
 
 let lastGcTimestamp = 0;
+let lastVersionGroupRepairTimestamp = 0;
 
 // ---------------------------------------------------------------------------
 // Core
@@ -64,6 +66,7 @@ export interface GcResult {
   reason?: string;
   archivedCount: number;
   totalChecked: number;
+  dissolvedVersionGroups: number;
 }
 
 /**
@@ -85,38 +88,70 @@ export async function maybeRunGc(
   const stats = await store.stats();
   const totalMemories = stats.totalCount ?? 0;
 
-  // Condition 1: enough memories to warrant GC
-  if (totalMemories < config.minMemoryCount) {
-    return { triggered: false, reason: "below_memory_threshold", archivedCount: 0, totalChecked: 0 };
-  }
+  // Singleton version-group repair has its own persistent throttle. It must not be
+  // hidden behind minMemoryCount: a small store can lose one member of a pair too.
+  // Reuse the configured maintenance interval, but keep a separate timestamp so a
+  // repair-only pass does not postpone a later archive pass (or vice versa).
+  const repairStampPath = lockPathForKey("version-group-repair-last");
+  const lastRepair = Math.max(
+    lastVersionGroupRepairTimestamp,
+    getLastDistillTime({ lockPath: repairStampPath }),
+  );
+  const repairDue = totalMemories > 0
+    && (Date.now() - lastRepair) / 3_600_000 >= config.minHoursSinceLastGc;
 
-  // Condition 2: enough time since last GC. P0-1: the throttle is cross-process now —
-  // take the max of this process's in-memory timestamp and the shared gc-last stamp
-  // file's mtime. The old module-level var alone let each of the 11 mcp-server
-  // processes run gc on its own independent 24h clock.
+  // Archive GC retains its existing count and time gates. P0-1: the time throttle
+  // is cross-process, using the shared gc-last marker in addition to process state.
   const gcStampPath = lockPathForKey("gc-last");
   const lastGc = Math.max(lastGcTimestamp, getLastDistillTime({ lockPath: gcStampPath }));
   const hoursSinceLastGc = (Date.now() - lastGc) / 3_600_000;
-  if (hoursSinceLastGc < config.minHoursSinceLastGc) {
-    return { triggered: false, reason: "too_soon", archivedCount: 0, totalChecked: 0 };
+  const archiveSkipReason = totalMemories < config.minMemoryCount
+    ? "below_memory_threshold"
+    : hoursSinceLastGc < config.minHoursSinceLastGc
+      ? "too_soon"
+      : undefined;
+
+  // Nothing is due: preserve the old fast no-op path without taking a run lock.
+  if (!repairDue && archiveSkipReason) {
+    return { triggered: false, reason: archiveSkipReason, archivedCount: 0, totalChecked: 0, dissolvedVersionGroups: 0 };
   }
 
   // Concurrency guard: only one process scans the full corpus at a time. A process that
   // passed the throttle in the same instant loses the O_EXCL race here and skips.
   const gcRunLock = { lockPath: lockPathForKey("gc-run"), expireMs: 30 * 60_000 };
   if (!acquireLock(gcRunLock)) {
-    return { triggered: false, reason: "locked_by_another_process", archivedCount: 0, totalChecked: 0 };
+    return { triggered: false, reason: "locked_by_another_process", archivedCount: 0, totalChecked: 0, dissolvedVersionGroups: 0 };
   }
 
-  // All conditions met — run GC
-  lastGcTimestamp = Date.now(); // in-process immediate throttle
-
   try {
+    let dissolvedVersionGroups = 0;
+    if (repairDue) {
+      dissolvedVersionGroups = await store.repairSingletonVersionGroups();
+      lastVersionGroupRepairTimestamp = Date.now();
+      stampLock({ lockPath: repairStampPath });
+      if (dissolvedVersionGroups > 0) {
+        logInfo(`[INFO] Auto-GC dissolved ${dissolvedVersionGroups} singleton version group(s)`);
+      }
+    }
+
+    // A repair-only pass is still useful maintenance, but `triggered` continues to
+    // mean that the archive scan ran so existing callers keep their old semantics.
+    if (archiveSkipReason) {
+      return {
+        triggered: false,
+        reason: archiveSkipReason,
+        archivedCount: 0,
+        totalChecked: 0,
+        dissolvedVersionGroups,
+      };
+    }
+
+    lastGcTimestamp = Date.now(); // in-process immediate throttle
     const { archivedCount, totalChecked } = await runGcScan(store, config, retentionConfigDir, auditLogger);
     // Stamp completion into the shared throttle marker (create-or-touch → mtime = now)
     // so the other processes observe "last run" via getLastDistillTime.
     stampLock({ lockPath: gcStampPath });
-    return { triggered: true, archivedCount, totalChecked };
+    return { triggered: true, archivedCount, totalChecked, dissolvedVersionGroups };
   } finally {
     releaseLock(gcRunLock);
   }
@@ -169,13 +204,47 @@ async function runGcScan(
 
   // Pass 2: archive sweep.
   const useUsageAdjustedDecay = envConfig.usageDecay() && isUsageSignalActive();
+
+  // 2026-08-14 批量化（dream 写爆库根治）：候选先收集，页末统一一次 patchMetadataBatch
+  // —— 原逐条 update 每行一个 LanceDB commit（每天最多 100 个 manifest），现在页数级。
+  // activeCounts 仍在"选中"时即刻预递减，保持旧路径"逐行归档、后续行的 retention 判断
+  // 看到已减的 activeCount"语义（互审 C6）。selected 与 archivedCount 分开：前者控
+  // maxArchivePerRun 上限（选中即占额度），后者按批量写的实际写入数累计。
+  let selected = 0;
+  let pendingArchive: Array<{ id: string; ageDays: number }> = [];
+  const flushArchiveBatch = async (): Promise<void> => {
+    if (pendingArchive.length === 0) return;
+    const batch = pendingArchive;
+    pendingArchive = [];
+    const written = await store.patchMetadataBatch(
+      batch.map(({ id }) => ({
+        id,
+        patchFn: (meta: Record<string, unknown>) => patchEvolutionOnMeta(meta, { status: "archived" }),
+      })),
+    );
+    archivedCount += written;
+    // F-1: Audit log — record archive operations (silent on failure)。按提交批记录：
+    // 批内个别行被并发删除时 audit 会多记一条，best-effort 语义可接受（旧路径里
+    // update 失败是直接炸掉整个 GC，连 audit 都到不了）。
+    for (const { id, ageDays } of batch) {
+      try {
+        auditLogger?.log({
+          operation: "archive",
+          memoryId: id,
+          actor: "system",
+          details: `auto-gc: age=${Math.floor(ageDays)}d`,
+        });
+      } catch { /* Audit must never block GC */ }
+    }
+  };
+
   outer:
   for (let offset = 0; ; offset += GC_PAGE_SIZE) {
     const page = await store.listPage({ limit: GC_PAGE_SIZE, offset });
     totalChecked += page.length;
 
   for (const entry of page) {
-    if (archivedCount >= config.maxArchivePerRun) break outer;
+    if (selected >= config.maxArchivePerRun) break outer;
 
     // Only archive active memories
     if (!isActiveMemory(entry.metadata)) continue;
@@ -215,19 +284,10 @@ async function runGcScan(
     }
 
     if (shouldArchive) {
-      const archivedMeta = buildArchivedMetadata(entry.metadata);
-      await store.update(entry.id, { metadata: archivedMeta });
-      archivedCount++;
-      // F-1: Audit log — record archive operation (silent on failure)
-      try {
-        auditLogger?.log({
-          operation: "archive",
-          memoryId: entry.id,
-          actor: "system",
-          details: `auto-gc: age=${Math.floor(ageDays)}d`,
-        });
-      } catch { /* Audit must never block GC */ }
-      // Decrement active count for the scope (memory is no longer active)
+      pendingArchive.push({ id: entry.id, ageDays });
+      selected++;
+      // Decrement active count for the scope（预递减：选中即视为不再 active，
+      // 同页后续行的 retention 判断与旧逐行路径看到同样的计数）
       const scope = entry.scope ?? "";
       const prev = activeCounts.get(scope) ?? 0;
       if (prev > 0) {
@@ -236,9 +296,14 @@ async function runGcScan(
     }
   }
 
+    // 页末提交本页候选（含 break outer 前最后一页扫过的部分）
+    await flushArchiveBatch();
     if (page.length < GC_PAGE_SIZE) break;
   }
 
+  // break outer 跳出时 pendingArchive 可能还有未提交的候选 —— 上限命中不弃单（互审 C6）
+  await flushArchiveBatch();
+
   return { archivedCount, totalChecked };
 }
 
@@ -248,9 +313,11 @@ async function runGcScan(
  */
 export function resetGcTimestamp(): void {
   lastGcTimestamp = 0;
+  lastVersionGroupRepairTimestamp = 0;
   try {
     releaseLock({ lockPath: lockPathForKey("gc-last") });
     releaseLock({ lockPath: lockPathForKey("gc-run") });
+    releaseLock({ lockPath: lockPathForKey("version-group-repair-last") });
   } catch {
     /* ignore — nothing to clear */
   }

package/src/cli.ts

@@ -38,9 +38,18 @@ import {
 } from "./ingest.js";
 import { runDoctor, formatDoctorResults } from "./doctor.js";
 import { persistCaseMemory, persistMemory, persistWorkflowPattern } from "./capture-engine.js";
-import { scanMemoryPromotions, buildPromoteScanDeps, formatPromoteScanResult } from "./memory-promotion.js";
+import {
+  scanMemoryPromotions,
+  scanSynthesisPromotions,
+  buildPromoteScanDeps,
+  formatPromoteScanResult,
+  formatSynthesisPromoteResult,
+} from "./memory-promotion.js";
 import { runDream, formatDreamResult, formatDreamMetrics, DEFAULT_DREAM_CONFIG, classifyDreamFailure, shouldBlockDreamRun, partitionAutoDreamScopes } from "./dream-pipeline.js";
-import { listScopesAboveThreshold } from "./activity-counter.js";
+import { dreamBudgetMs } from "./env-config.js";
+import { listScopesAboveThreshold, pruneWriteCounts } from "./activity-counter.js";
+import { isTranscriptScope } from "./memory-boundaries.js";
+import { maybeRunGc } from "./auto-gc.js";
 import {
   CaseMemoryInputSchema,
   type CaseMemoryInput,
@@ -62,6 +71,7 @@ import { WorkflowObservationOutcomeSchema } from "./workflow-observation-schema.
 import { buildWorkflowEvidence, buildWorkflowObservationRecord, inspectWorkflowDashboard, inspectWorkflowHealth } from "./workflow-observation-engine.js";
 import { formatWorkflowEvidencePack, formatWorkflowHealthDashboard, formatWorkflowHealthReport, formatWorkflowObservationSaved } from "./workflow-observation-output.js";
 import { WorkflowObservationStore } from "./workflow-observation-store.js";
+import { applyUtilityToMeta, computeMemoryUtility, formatMemoryUtility } from "./memory-utility.js";
 import {
   applyWorkflowObservationScopeSuggestions,
   formatWorkflowObservationScopeReview,
@@ -702,6 +712,28 @@ program
     console.log(formatPromoteScanResult(result));
   });
 
+program
+  .command("promote-synthesis")
+  .description("扫描 dream 合成出的结论（evidence 层），把证据充分的那些晋升出一份 durable 副本")
+  .requiredOption("--scope <scope>", "要扫描的 scope，如 memory")
+  .option("--apply", "执行晋升；默认 dry-run 只预览")
+  .option("--min-evidence <n>", "最少几条仍存活的不同证据（默认 2）", "2")
+  .option("--min-importance <n>", "合成条目自身的最低 importance（默认 0.6）", "0.6")
+  .action(async (options) => {
+    const config = loadConfig();
+    const { store, embedder } = createComponents(config);
+    const conflictStore = new ConflictCandidateStore();
+    const deps = buildPromoteScanDeps({ store, embedder, conflictStore });
+    const minDistinctEvidence = Number(options.minEvidence);
+    const minImportance = Number(options.minImportance);
+    const result = await scanSynthesisPromotions(deps, options.scope, {
+      dryRun: !options.apply,
+      ...(Number.isFinite(minDistinctEvidence) ? { minDistinctEvidence } : {}),
+      ...(Number.isFinite(minImportance) ? { minImportance } : {}),
+    });
+    console.log(formatSynthesisPromoteResult(result));
+  });
+
 program
   .command("export <query>")
   .description("导出检索与蒸馏结果到 markdown/json")
@@ -1360,7 +1392,7 @@ program
 program
   .command("ingest")
   .description("导入对话记录到索引")
-  .option("-s, --source <source>", "数据源: cc / codex / gemini / kimi / memory / desktop / all", "all")
+  .option("-s, --source <source>", "数据源: cc / codex / gemini / kimi / memory / desktop / minis / all", "all")
   .option("-l, --limit <n>", "限制处理文件数（调试用）")
   .option("-v, --verbose", "详细输出")
   .option("--no-dedup", "跳过向量去重")
@@ -1503,6 +1535,27 @@ 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}`);
+        }
+      }
+    }
+
     // Memory markdown files
     if (source === "all" || source === "memory") {
       console.log("📚 导入记忆文件...");
@@ -1587,10 +1640,11 @@ program
 program
   .command("dream")
   .description("运行 dream 离线整固管线 (Orient/Gather/Consolidate/Prune)")
-  .option("--scope <scope>", "目标 scope(前缀或精确)", "cc")
+  .option("--scope <scope>", "目标 scope(默认前缀家族匹配;加 --exact-scope 变精确)", "cc")
+  .option("--exact-scope", "把 --scope 当成一个具体 scope 名精确匹配,不做前缀家族展开(调度入口必带)")
   .option("--auto", "扫描 activity-counter 中写计数达标的所有 scope，逐个跑 dream（单 scope 失败不阻断其他）")
   .option("--force", "跳过 min-writes 门槛强制运行")
-  .action(async (options: { scope: string; auto?: boolean; force?: boolean }) => {
+  .action(async (options: { scope: string; auto?: boolean; force?: boolean; exactScope?: boolean }) => {
     const config = loadConfig();
     const { store, embedder, llm } = createComponents(config);
     // Same activity-stats file the store writes per-scope counts to (beside the LanceDB dir).
@@ -1602,20 +1656,76 @@ program
       const eligible = listScopesAboveThreshold(DEFAULT_DREAM_CONFIG.minWritesForDream, { statsPath: activityStatsPath });
       // 巨型 scope 交给专用 schedule,不占日常轮次的 wall-clock 预算(理由见
       // DreamConfig.autoExcludeScopes:07-30 那轮 6h 只跑了 15/507,而 memory 独占 79% 的条数)。
-      const { run: scopes, deferred } = partitionAutoDreamScopes(eligible, DEFAULT_DREAM_CONFIG.autoExcludeScopes);
+      const { run: nonMemoryScopes, deferred } = partitionAutoDreamScopes(eligible, DEFAULT_DREAM_CONFIG.autoExcludeScopes);
       if (deferred.length > 0) {
         // 不静默:被挪走的 scope 必须在日志里看得见,否则"今天怎么没跑 memory"只能靠翻代码回答。
         // 前缀刻意用 `[dream]` 而不是 `dream --auto:`——后者是 dream-checkup.sh 抓「达标 scope 数」
         // 的锚点,多一行同前缀的会混进它的取数。
         console.log(`[dream] ${deferred.length} 个 scope 交给专用 schedule，本轮不跑 → ${deferred.join(", ")}`);
       }
+
+      // 2026-08-16 策略排除（互审 C2/K5）：与上面的 deferred **语义不同,别合并**——
+      // deferred 是"别处会跑",这里是"没有任何 schedule 会跑"。日志措辞必须分开,
+      // 否则将来查"pivot 怎么没巩固"会被误导去找那个并不存在的专用 job。
+      // 同时清写计数:runDream 对它返回 skipped 不会 resetWriteCount,不清则计数无限
+      // 累积、每天都进达标队列白跑一次(这正是 07-02 那个"处理完不出队"bug 的形状)。
+      const neverDream = DEFAULT_DREAM_CONFIG.neverDreamScopes;
+      const policyExcluded = nonMemoryScopes.filter(s => neverDream.includes(s));
+      const afterPolicy = nonMemoryScopes.filter(s => !neverDream.includes(s));
+      if (policyExcluded.length > 0) {
+        const prunedPolicy = await pruneWriteCounts(s => neverDream.includes(s), { statsPath: activityStatsPath });
+        console.log(
+          `[dream] ${policyExcluded.length} 个 scope 按策略不参与巩固（neverDreamScopes，无专用 schedule）` +
+          ` → ${policyExcluded.join(", ")}；已清写计数 ${prunedPolicy.length} 个`,
+        );
+      }
+
+      // 2026-08-14 transcript scope 整体出队（dream 写爆库根治的准入侧）：
+      // transcript 是原文层（shared-behaviors §5.3——原文归 Deja/ingest 管，提炼归
+      // pivot 池），历史会话被 ingest 批量灌入就把写计数打过门槛，2026-08 实测达标
+      // 队列 95% 是 codex/cc 会话 scope、dream 派生产物 96.6% 落在不参与日常检索的
+      // transcript scope 上——巩固算力几乎全部空转，还把 _versions 写到 7.7GB。
+      // 出队同时清扫计数（含未达标条目——历史会话只增不减，不清则 stats 文件无限膨胀；
+      // ingest 白天会再写回、次日 04:00 再清，稳态保持小）。判定用 memory-boundaries
+      // 的 isTranscriptScope（接新端时那边本来就要求同步前缀清单）。
+      const scopes = afterPolicy.filter(s => !isTranscriptScope(s));
+      const transcriptEligible = afterPolicy.length - scopes.length;
+      const prunedTranscripts = await pruneWriteCounts(isTranscriptScope, { statsPath: activityStatsPath });
+      if (prunedTranscripts.length > 0 || transcriptEligible > 0) {
+        console.log(
+          `[dream] transcript 原文层不参与巩固（§5.3）：清扫 ${prunedTranscripts.length} 个 scope 的写计数` +
+          `（其中达标 ${transcriptEligible} 个）→ 样例: ${prunedTranscripts.slice(0, 5).join(", ")}`,
+        );
+      }
+
+      // 2026-08-14 全库 GC 兜底（互审 C5-P0）：dream 是 auto-gc 的唯一生产触发点，而
+      // maybeRunGc 藏在 runDreamInner 里 —— transcript 出队后 durable 队列可为空，若在
+      // 进循环前就 exit，全库 GC 检查会静默消失、归档管线停转。这里无条件补调一次：
+      // GC 自带 24h stamp + 跨进程锁，循环内已触发过则本次 too_soon 跳过，幂等零成本。
+      // 失败只记日志不并入 blocked：GC 是 best-effort 维护，明天还有机会。
+      const runGcBackstop = async (): Promise<void> => {
+        try {
+          const gc = await maybeRunGc(store, DEFAULT_DREAM_CONFIG.gc);
+          console.log(
+            `[dream] 全库 GC 兜底: ${gc.triggered
+              ? `archived ${gc.archivedCount}, dissolved version groups ${gc.dissolvedVersionGroups}`
+              : gc.dissolvedVersionGroups > 0
+                ? `dissolved version groups ${gc.dissolvedVersionGroups}; archive skipped — ${gc.reason}`
+              : `skipped — ${gc.reason}`}`,
+          );
+        } catch (err) {
+          console.error(`[dream] 全库 GC 兜底失败（不阻断本轮判定）: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      };
+
       if (scopes.length === 0) {
-        // 两种空:一种是真没人达标,一种是达标的全被挪走了——混成一句会让排障从这里开始跑偏。
+        // 三种空分开说:真没人达标 / 达标的全被挪走或全是 transcript——混成一句会让排障跑偏。
         console.log(
           eligible.length === 0
             ? "dream --auto: 无达标 scope（写计数均低于门槛）"
-            : "dream --auto: 达标 scope 全部交给专用 schedule，本轮无事可做",
+            : "dream --auto: 达标 scope 均为 transcript（已清扫）、已交专用 schedule 或按策略排除，本轮无事可做",
         );
+        await runGcBackstop();
         console.log("[[DREAM_STATUS]] skip");
         process.exit(0);
       }
@@ -1625,7 +1735,7 @@ program
       // 把 07-25~27 三天的调度全堵死（上一次没结束，launchd 起不了新的）。
       // 天花板见 DreamConfig.autoRunBudgetMs 的注释——截断会让靠后 scope 系统性饿死，
       // 真解是 session scope TTL，不是把预算调大。
-      const budgetMs = Number(process.env.RECALLNEST_DREAM_BUDGET_MS ?? DEFAULT_DREAM_CONFIG.autoRunBudgetMs);
+      const budgetMs = dreamBudgetMs(DEFAULT_DREAM_CONFIG.autoRunBudgetMs);
       const deadline = Date.now() + budgetMs;
 
       let fatalFailures = 0;
@@ -1647,7 +1757,11 @@ program
         }
         processed++;
         try {
-          const result = await runDream({ store, llm, embedder, scope, force: Boolean(options.force), activityStatsPath, kgStore });
+          // scopeMatch: "exact" —— 这些 scope 名直接来自 activity-stats 的键，是具体
+          // scope 不是 family selector。无冒号的键（实测 11 个，含 `cc` / `global` /
+          // `memory`）走前缀会把整个家族卷进来：`cc` 一旦达标就以 `LIKE 'cc%'` 把 08-14
+          // 刚出队的 transcript 原文层整批捞回（2026-08-16 互审 K4）。
+          const result = await runDream({ store, llm, embedder, scope, force: Boolean(options.force), activityStatsPath, kgStore, scopeMatch: "exact" });
           tally[result.output.kind]++;
           effectsTotal += result.output.effectsWritten;
           if (result.output.degraded) degradedScopes.push(`${scope}=${result.output.degraded}`);
@@ -1665,6 +1779,10 @@ program
         }
       }
 
+      // 全库 GC 兜底：循环内的 per-scope GC 若已触发过，这里 too_soon 幂等跳过；
+      // 若全部 scope 都 skip/失败没走到 prune 阶段，这里补上当天唯一一次 GC 检查。
+      await runGcBackstop();
+
       // 旧语义是「任一 scope 抛异常即 blocked」，在 475 个 scope 的规模下等于「有一个撞上
       // store-write 锁就整轮红」，而整轮红会让 shell 脚本重试 → 重跑全量。改为：代码/数据
       // 缺陷一票否决，环境性失败要成规模才算整轮失败。比例按已处理数算，不按总数。
@@ -1702,6 +1820,9 @@ program
         force: Boolean(options.force),
         activityStatsPath,
         kgStore,
+        // 手动调用默认保留 family（`--scope cc` 扫 `cc:*` 是既有用法）；
+        // 调度入口（weekly job）必须显式带 --exact-scope。
+        scopeMatch: options.exactScope ? "exact" : "family",
       });
 
       console.log(formatDreamResult(result));
@@ -1936,6 +2057,92 @@ program
 
 // ─── doctor ──────────────────────────────────────────────────────────────────
 
+program
+  .command("memory-utility")
+  .description("价值回溯：查一条 memory 参与过的任务成功率与 utility（不传 id 时按 scope 批量）")
+  .argument("[memoryId]", "memory id（完整 UUID 或前缀）")
+  .option("--scope <scope>", "批量模式：扫这个 scope 下的条目")
+  .option("--category <category>", "批量模式：只看这个 category")
+  .option("--limit <n>", "批量模式扫描上限", "500")
+  .option("--min-samples <n>", "批量模式只列出有效样本量 ≥ 此值的条目", "0")
+  .option("--links <n>", "展示最近 N 条参与记录", "5")
+  .option("--apply", "把算出的 utility 写回 metadata（默认只读，不写）")
+  .option("--observations-dir <dir>", "从指定目录读 workflow observations（默认生产目录）")
+  .option("--json", "输出 JSON")
+  .action(async (memoryId, options) => {
+    const { store } = createComponents(loadConfig());
+    const observationStore = options.observationsDir
+      ? new WorkflowObservationStore(expandHome(options.observationsDir))
+      : new WorkflowObservationStore();
+    // 全量拉 observation：join 要看的是历史全集，不是最近 200 条。
+    const observations = await observationStore.listRecent({ limit: 100_000 });
+    const showLinks = Number(options.links) || 0;
+
+    if (memoryId) {
+      const entry = await store.getById(memoryId);
+      if (!entry) {
+        console.error(`未找到 memory: ${memoryId}`);
+        process.exitCode = 1;
+        return;
+      }
+      const summary = computeMemoryUtility(entry, observations);
+      if (options.apply) {
+        await store.patchMetadata(entry.id, (meta) => applyUtilityToMeta(meta, summary));
+      }
+      if (options.json) {
+        console.log(JSON.stringify({ ...summary, applied: Boolean(options.apply) }, null, 2));
+        return;
+      }
+      console.log(formatMemoryUtility(summary, { showLinks }));
+      console.log(`  observations 池: ${observations.length} 条`);
+      if (options.apply) console.log("  已写回 metadata.utility");
+      return;
+    }
+
+    if (!options.scope) {
+      console.error("需要 <memoryId> 或 --scope");
+      process.exitCode = 1;
+      return;
+    }
+
+    const limit = Number(options.limit) || 500;
+    const minSamples = Number(options.minSamples) || 0;
+    const entries = await store.listPage({
+      scopeFilter: [options.scope],
+      category: options.category,
+      limit,
+      offset: 0,
+    });
+
+    const summaries = entries
+      .map((entry) => computeMemoryUtility(entry, observations))
+      .filter((s) => s.effectiveSamples >= minSamples && s.total > 0)
+      .sort((a, b) => (b.utility ?? 0) - (a.utility ?? 0));
+
+    if (options.apply) {
+      for (const summary of summaries) {
+        await store.patchMetadata(summary.memoryId, (meta) => applyUtilityToMeta(meta, summary));
+      }
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify({ scanned: entries.length, matched: summaries.length, summaries }, null, 2));
+      return;
+    }
+
+    console.log(`scope=${options.scope} 扫描 ${entries.length} 条，其中 ${summaries.length} 条有参与记录`);
+    console.log(`observations 池: ${observations.length} 条`);
+    for (const summary of summaries.slice(0, 20)) {
+      const utility = summary.utility === null ? "  null" : summary.utility.toFixed(4).padStart(7);
+      console.log(
+        `${utility}  samples=${summary.effectiveSamples.toFixed(2).padStart(6)}`
+        + `  exact=${String(summary.exactCount).padStart(3)} session=${String(summary.sessionCount).padStart(3)}`
+        + `  ${summary.memoryId.slice(0, 8)}`,
+      );
+    }
+    if (options.apply) console.log(`已写回 ${summaries.length} 条的 metadata.utility`);
+  });
+
 program
   .command("workflow-observe")
   .description("记录一条 workflow primitive observation，作为自进化观测层的 append-only 输入")
@@ -1949,9 +2156,14 @@ program
   .option("--tags <tags>", "逗号分隔 tags")
   .option("--tools <tools>", "逗号分隔 tools")
   .option("--idempotency-key <key>", "同一请求重试时用于替换旧 observation 的稳定键")
+  .option("--reader-id <id>", "P0 join key：读者身份（默认本进程）。CLI 每次是新进程，跨会话关联要显式传")
+  .option("--recalled-ids <ids>", "P0 join key：逗号分隔的 memory id，本次任务实际用到的记忆")
   .option("--json", "输出 JSON")
   .action(async (workflowId, summary, options) => {
     const store = new WorkflowObservationStore();
+    // CLI 是一次性进程，检索账本必然是空的（这次进程没检索过），所以不做自动补，
+    // 只认显式传入——自动补在这里只会写出一个恒空的字段，看着像记了其实没记。
+    const recalledIds = splitCsvOption(options.recalledIds);
     const record = buildWorkflowObservationRecord({
       workflowId,
       summary,
@@ -1963,6 +2175,8 @@ program
       tags: splitCsvOption(options.tags),
       tools: splitCsvOption(options.tools),
       idempotencyKey: options.idempotencyKey,
+      readerId: options.readerId,
+      ...(recalledIds.length > 0 ? { recalledIds } : {}),
     });
     const stored = await store.save(record);
     if (options.json) {