recallnest 2.6.1 → 3.0.0

package/src/memory-promotion.ts

@@ -244,3 +244,283 @@ export function formatPromoteScanResult(result: PromoteScanResult): string {
   }
   return lines.join("\n");
 }
+
+// ---------------------------------------------------------------------------
+// Synthesis promotion: evidence → durable for dream-synthesized conclusions
+// ---------------------------------------------------------------------------
+
+/**
+ * The layering this implements is "evidence retained → current projection → eligible for
+ * recall → ranked result". `scanMemoryPromotions` above covers one road into the durable
+ * layer: transcript-downgraded facts that recur often enough to be worth keeping. This
+ * covers the other one, which had no road at all.
+ *
+ * `buildDerivedBoundary` (consolidation-engine) stamps every dream-synthesized insight and
+ * cross-memory pattern as `layer: "evidence"`, deliberately — a model re-reading its own
+ * memories is a lead to its sources, not authority over them. But
+ * `shouldUseStableMemoryResult` refuses anything on the evidence layer, so the consequence
+ * was absolute: **a synthesized conclusion could never take part in stable memory, no
+ * matter how well supported it was.** The synthesis contract added in `efdb043` made those
+ * conclusions checkable (a verdict may abstain, and evidence ids are validated against the
+ * cluster) without giving them anywhere to go.
+ *
+ * ## Why the gate is not the one above
+ *
+ * The recurrence gate — "the same fact showed up in N separate places" — is the wrong
+ * question to ask a synthesis. A synthesis is *already* a cross-entry aggregate; demanding
+ * that the dream produce the same conclusion three times would be counting one thing three
+ * ways. What it carries instead is its own support set, so that is what gets checked:
+ * enough distinct sources, still live, under a contract version that validated them.
+ *
+ * ## What promotion does and does not touch
+ *
+ * The synthesis row is never modified — archive-first, and the evidence has to stay
+ * readable as evidence. Promotion writes a *separate* durable entry through the same
+ * `promoteMemory` path everything else uses, so it inherits canonicalKey dedup (re-running
+ * revises rather than duplicating), secret redaction, and `promotedFrom` provenance
+ * pointing back at the synthesis. The durable copy is what later recall can lean on.
+ */
+
+/** Synthesis contract version required before a derived row is eligible. */
+export const MIN_PROMOTABLE_CONTRACT_VERSION = 2;
+
+export interface SynthesisPromoteScanConfig {
+  /** Min distinct, still-live evidence memories behind the conclusion (default 2). */
+  minDistinctEvidence: number;
+  /** Min importance of the synthesis itself (default 0.6). */
+  minImportance: number;
+  /** Max derived rows fetched from the store (default 2000). */
+  listLimit: number;
+  /** When true (default), report candidates without writing anything. */
+  dryRun: boolean;
+}
+
+export const DEFAULT_SYNTHESIS_PROMOTE_CONFIG: SynthesisPromoteScanConfig = {
+  minDistinctEvidence: 2,
+  minImportance: 0.6,
+  listLimit: 2000,
+  dryRun: true,
+};
+
+/** Why an otherwise-derived row was not promoted. Reported, never silent. */
+export type SynthesisSkipReason =
+  | "pre_contract"
+  | "already_promoted"
+  | "evidence_unresolvable"
+  | "too_few_distinct_evidence"
+  | "below_importance";
+
+export interface SynthesisPromoteCandidate {
+  seedId: string;
+  seedText: string;
+  /** Durable category the conclusion is promoted into (from boundary.originalCategory). */
+  category: DurableMemoryCategory;
+  contractVersion: number;
+  /** Distinct evidence ids that are still active in the store. */
+  evidenceIds: string[];
+  importance: number;
+  /** Filled after a real promotion; null in dryRun mode. */
+  promoted: StoredPromotedMemoryRecord | null;
+}
+
+export interface SynthesisPromoteScanResult {
+  candidates: SynthesisPromoteCandidate[];
+  /** Derived rows examined (carrying a distillation boundary), before gating. */
+  scannedSyntheses: number;
+  /** Per-reason counts for everything examined and rejected. */
+  skipped: Record<SynthesisSkipReason, number>;
+  promoted: number;
+  dryRun: boolean;
+}
+
+export interface SynthesisPromoteScanDeps {
+  store: Pick<MemoryStore, "list"> & {
+    getById?(id: string): Promise<MemoryEntry | null>;
+    get?(id: string): Promise<MemoryEntry | null>;
+  };
+  promote: PromoteFn;
+}
+
+function readContractVersion(metadata?: string): number | null {
+  const parsed = parseMetadataObject(metadata);
+  const raw = parsed?.synthesis_contract;
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+}
+
+/** Ids the model itself named as support, deduplicated and order-preserved. */
+function readEvidenceIds(metadata?: string): string[] | null {
+  const parsed = parseMetadataObject(metadata);
+  const raw = parsed?.evidenceMemories;
+  if (!Array.isArray(raw)) return null;
+  const ids = raw.filter((id): id is string => typeof id === "string" && id.trim().length > 0);
+  return [...new Set(ids)];
+}
+
+/** A dream-synthesized derivative — evidence layer written by the distillation path. */
+function isSynthesisRow(entry: MemoryEntry): boolean {
+  const boundary = extractBoundaryMetadata(entry.metadata);
+  return boundary?.layer === "evidence" && boundary.authority === "distillation";
+}
+
+async function loadEntry(
+  deps: SynthesisPromoteScanDeps,
+  id: string,
+): Promise<MemoryEntry | null> {
+  if (deps.store.getById) return deps.store.getById(id);
+  if (deps.store.get) return deps.store.get(id);
+  return null;
+}
+
+/**
+ * Find synthesized conclusions whose own support set justifies a durable copy.
+ *
+ * Abstains rather than guesses: a row whose evidence ids cannot be resolved at all is
+ * counted under `evidence_unresolvable` and left alone. That mirrors the abstention path
+ * in `scanForPromotions`' cross-source check — when the provenance needed for the judgement
+ * is missing, not judging is the correct answer, not judging leniently.
+ */
+export async function scanSynthesisPromotions(
+  deps: SynthesisPromoteScanDeps,
+  scope: string,
+  config?: Partial<SynthesisPromoteScanConfig>,
+): Promise<SynthesisPromoteScanResult> {
+  const cfg: SynthesisPromoteScanConfig = { ...DEFAULT_SYNTHESIS_PROMOTE_CONFIG, ...config };
+
+  const result: SynthesisPromoteScanResult = {
+    candidates: [],
+    scannedSyntheses: 0,
+    skipped: {
+      pre_contract: 0,
+      already_promoted: 0,
+      evidence_unresolvable: 0,
+      too_few_distinct_evidence: 0,
+      below_importance: 0,
+    },
+    promoted: 0,
+    dryRun: cfg.dryRun,
+  };
+
+  // Synthesized insights take the cluster's majority category, so this cannot be narrowed
+  // to one category the way the downgraded-evidence scan is.
+  const rows = await deps.store.list([scope], undefined, cfg.listLimit, 0);
+  const syntheses = rows.filter((e) => isActiveMemory(e.metadata) && isSynthesisRow(e));
+  result.scannedSyntheses = syntheses.length;
+
+  for (const entry of syntheses) {
+    const contractVersion = readContractVersion(entry.metadata);
+    // Derivatives written before the synthesis contract were never validated — the whole
+    // point of the version stamp is that "which code produced this" stops being a guess.
+    if (contractVersion === null || contractVersion < MIN_PROMOTABLE_CONTRACT_VERSION) {
+      result.skipped.pre_contract += 1;
+      continue;
+    }
+
+    if (hasPromotedToMarker(entry.metadata)) {
+      result.skipped.already_promoted += 1;
+      continue;
+    }
+
+    const declared = readEvidenceIds(entry.metadata);
+    if (declared === null || declared.length === 0) {
+      result.skipped.evidence_unresolvable += 1;
+      continue;
+    }
+
+    // Evidence that has since been superseded or archived no longer supports anything.
+    const resolved: string[] = [];
+    let lookupFailed = false;
+    for (const id of declared) {
+      const source = await loadEntry(deps, id);
+      if (source === null) {
+        lookupFailed = true;
+        continue;
+      }
+      if (isActiveMemory(source.metadata)) resolved.push(id);
+    }
+
+    // Cannot see any of the support: abstain instead of promoting on an unchecked claim.
+    if (resolved.length === 0 && lookupFailed) {
+      result.skipped.evidence_unresolvable += 1;
+      continue;
+    }
+
+    if (resolved.length < cfg.minDistinctEvidence) {
+      result.skipped.too_few_distinct_evidence += 1;
+      continue;
+    }
+
+    if ((entry.importance ?? 0) < cfg.minImportance) {
+      result.skipped.below_importance += 1;
+      continue;
+    }
+
+    const boundary = extractBoundaryMetadata(entry.metadata);
+    const category = (boundary?.originalCategory ?? "events") as DurableMemoryCategory;
+
+    const candidate: SynthesisPromoteCandidate = {
+      seedId: entry.id,
+      seedText: entry.text,
+      category,
+      contractVersion,
+      evidenceIds: resolved,
+      importance: entry.importance,
+      promoted: null,
+    };
+
+    if (!cfg.dryRun) {
+      candidate.promoted = await deps.promote({
+        memoryId: entry.id,
+        category,
+        scope,
+        importance: entry.importance,
+      });
+      result.promoted += 1;
+    }
+
+    result.candidates.push(candidate);
+  }
+
+  return result;
+}
+
+export function formatSynthesisPromoteResult(result: SynthesisPromoteScanResult): string {
+  const skippedTotal = Object.values(result.skipped).reduce((a, b) => a + b, 0);
+  const lines = [
+    `Synthesis promote-scan: ${result.scannedSyntheses} synthesized conclusion(s) examined, ${skippedTotal} skipped.`,
+  ];
+
+  // Always print the rejection breakdown: a scan that promotes nothing should still say
+  // why, or "nothing found" and "everything filtered" look the same from outside.
+  const reasons = (Object.entries(result.skipped) as Array<[SynthesisSkipReason, number]>)
+    .filter(([, n]) => n > 0)
+    .map(([reason, n]) => `${reason}=${n}`);
+  if (reasons.length > 0) lines.push(`Skipped: ${reasons.join(", ")}`);
+
+  if (result.candidates.length === 0) {
+    lines.push("No promotion candidates found.");
+    return lines.join("\n");
+  }
+
+  lines.push(
+    result.dryRun
+      ? `Found ${result.candidates.length} candidate(s) (dry-run, nothing written):\n`
+      : `Promoted ${result.promoted} of ${result.candidates.length} candidate(s):\n`,
+  );
+
+  for (const [i, c] of result.candidates.entries()) {
+    lines.push(`### ${i + 1}. [${c.category}] ${c.seedText.split("\n")[0].slice(0, 80)}`);
+    lines.push(
+      `Evidence: ${c.evidenceIds.length} distinct (${c.evidenceIds.map((id) => id.slice(0, 8)).join(", ")})`,
+    );
+    lines.push(`Contract: v${c.contractVersion} | importance: ${c.importance.toFixed(2)} | seed: ${c.seedId.slice(0, 8)}`);
+    if (c.promoted) {
+      lines.push(
+        c.promoted.disposition === "conflict" && c.promoted.conflictId
+          ? `-> conflict ${c.promoted.conflictId.slice(0, 8)} (manual review)`
+          : `-> durable ${c.promoted.id.slice(0, 8)} (${c.promoted.disposition}, key ${c.promoted.canonicalKey})`,
+      );
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}

package/src/memory-store-port.ts

@@ -1,4 +1,5 @@
 import type { MemoryEntry, MemorySearchResult } from "./store.js";
+import type { ScopeMatchMode } from "./scope-policy.js";
 
 export interface MemoryStoreStats {
   totalCount: number;
@@ -18,8 +19,16 @@ export type MemoryStoreUpdate = {
 };
 
 export interface MemoryStorePort {
-  stats(scopeFilter?: string[]): Promise<MemoryStoreStats>;
-  list(scopeFilter?: string[], category?: string, limit?: number, offset?: number): Promise<MemoryEntry[]>;
+  /** scopeMatch 见 scope-policy.ts 的 ScopeMatchMode：缺省 "family"（历史行为，
+   *  无冒号 scope 按前缀），"exact" 由调用方在"我给的是一个具体 scope 名"时显式声明。 */
+  stats(scopeFilter?: string[], scopeMatch?: ScopeMatchMode): Promise<MemoryStoreStats>;
+  list(
+    scopeFilter?: string[],
+    category?: string,
+    limit?: number,
+    offset?: number,
+    scopeMatch?: ScopeMatchMode,
+  ): Promise<MemoryEntry[]>;
   /** 按 id 批量取真实向量。list()/listPage() 为性能恒返回 vector:[]（假空数组），
    *  任何要做相似度/聚类的消费者必须用这个回填——promote_scan 与 dream 3b 都栽过同一坑。 */
   getVectors(ids: string[]): Promise<Map<string, number[]>>;
@@ -42,5 +51,25 @@ export interface MemoryStorePort {
     patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>,
     scopeFilter?: string[],
   ): Promise<MemoryEntry | null>;
-  vectorSearch(vector: number[], limit?: number, minScore?: number, scopeFilter?: string[]): Promise<MemorySearchResult[]>;
+  /** metadata 批量读改写：单锁单 commit 写一批行（≤200/批）。patchFn 在锁内以库中
+   *  最新行为底座、按数组序依次应用（同批闭包可传递决策）。单条失败跳过不炸整批，
+   *  返回成功写入数。dream 3a/3b/auto-gc 的写放大治理入口（2026-08-14）。 */
+  patchMetadataBatch(
+    patches: Array<{
+      id: string;
+      patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>;
+    }>,
+    scopeFilter?: string[],
+  ): Promise<number>;
+  /** Remove version-group metadata from groups with only one surviving member.
+   *  Implementations should take one membership snapshot and apply repairs under
+   *  the same write lock so concurrent group creation cannot invalidate the plan. */
+  repairSingletonVersionGroups(): Promise<number>;
+  vectorSearch(
+    vector: number[],
+    limit?: number,
+    minScore?: number,
+    scopeFilter?: string[],
+    scopeMatch?: ScopeMatchMode,
+  ): Promise<MemorySearchResult[]>;
 }

package/src/memory-utility.ts

@@ -0,0 +1,314 @@
+/**
+ * Memory Utility — 价值回溯（MemOS Reflect2Evolve 的零 LLM 变体）。
+ *
+ * 借鉴来源：MemOS 自进化记忆系统借鉴评估（2026-06-13 审计，C1「价值回溯算术内核」）。
+ * MemOS 原式两处烧 LLM（任务级 R_human 三轴 rubric + 步级反思权重 α_t），
+ * 这里两处都换成库里现成的确定性信号：
+ *   R_human → workflow observation 的四档 outcome 查表（OUTCOME_REWARD）
+ *   α_t     → join 强度（任务级精确命中 vs 会话级弱关联），见 JOIN_WEIGHT
+ * 回溯本体在 MemOS 里就是纯算术，这里同样零 LLM、零网络。
+ *
+ * ⚠️ **这一列不写进 `importance`**，理由是硬的：
+ *   1. importance 是**阈值语义**——`resolveTier` 拿 ≥0.95 判 core、`isDecayExempt`
+ *      拿 core+≥0.95 判**永不衰减**（decay-engine.ts:180-186）。一条效用高的记忆
+ *      被顶过 0.95 就顺手拿到永久免衰减，这是串扰不是特性。
+ *   2. 那一列已经有写手：STC 的 retroactive-boost 在改它，传播的是**语义相关性**；
+ *      价值回溯传播的是**因果贡献**。两件事不该共用一列，否则互相盖。
+ *   3. importance 不能为负，而负值那半最值钱——「上次这么干失败了」在 importance 里没有容器装。
+ * utility 落在 metadata（与 tier/accessCount/readerIds 同族），只喂检索排序：
+ * `resolveTier` 与 `isDecayExempt` 都不读这个字段，tier 与豁免行为天然零变化。
+ */
+
+import type { MemoryEntry } from "./store.js";
+import type {
+  WorkflowObservationOutcome,
+  WorkflowObservationRecord,
+} from "./workflow-observation-schema.js";
+
+// ---------------------------------------------------------------------------
+// 常量
+// ---------------------------------------------------------------------------
+
+/**
+ * outcome → 回报值。取代 MemOS 的 LLM 三轴打分（目标 0.45／过程 0.30／满意 0.25）。
+ * 数值可调，关键是它**确定性、零成本**——LLM 打的分没法在 7 万条库上重放。
+ */
+export const OUTCOME_REWARD: Record<WorkflowObservationOutcome, number> = {
+  success: 0.8,
+  corrected: 0.2,
+  missed: -0.3,
+  failure: -0.8,
+};
+
+/**
+ * join 强度权重，充当 MemOS α_t（反思权重）的位置。
+ * exact = observation 自己列出了这条 memory；
+ * session = 只知道「同一个会话读过这条、且那个会话报了这个结果」，弱得多——
+ * 一个会话会跑很多任务，readerIds 又是累积的，不加权就会把无关任务的成败摊到这条头上。
+ */
+export const JOIN_WEIGHT = { exact: 1.0, session: 0.25 } as const;
+
+/** 半衰期（天）。旧结果该让位给新结果，与 MemOS priority 式的 0.5^(Δdays/30) 同形。 */
+export const UTILITY_HALF_LIFE_DAYS = 30;
+
+/** 低于这个有效样本量时不下结论（utility=null）。 */
+export const MIN_EFFECTIVE_SAMPLES = 0.5;
+
+export type JoinKind = keyof typeof JOIN_WEIGHT;
+
+// ---------------------------------------------------------------------------
+// 类型
+// ---------------------------------------------------------------------------
+
+export interface MemoryOutcomeLink {
+  observationId: string;
+  workflowId: string;
+  outcome: WorkflowObservationOutcome;
+  recordedAt: string;
+  join: JoinKind;
+  summary: string;
+}
+
+export interface MemoryOutcomeSummary {
+  memoryId: string;
+  /** 参与过的任务总数（exact + session）。 */
+  total: number;
+  exactCount: number;
+  sessionCount: number;
+  counts: Record<WorkflowObservationOutcome, number>;
+  /** success / total。没有样本时为 null——0% 和「没数据」不是一回事。 */
+  successRate: number | null;
+  /** 只看精确 join 的成功率，null 表示没有精确样本。 */
+  exactSuccessRate: number | null;
+  /**
+   * 效用值 ∈ [-0.8, 0.8]，可为负。样本不足时为 null。
+   * null 与 0 语义不同：null = 没数据，0 = 有数据但正负相抵。
+   */
+  utility: number | null;
+  /** 时间折扣后的有效样本量，用于判断这个 utility 有多可信。 */
+  effectiveSamples: number;
+  /**
+   * utility 是拿哪部分样本算的。
+   * `exact` = 有精确 join 样本，会话级样本被排除在计算之外（默认策略，见 summarizeMemoryOutcomes）；
+   * `session` = 只有会话级样本，聊胜于无；`none` = 没样本。
+   */
+  utilityBasis: "exact" | "session" | "none";
+  links: MemoryOutcomeLink[];
+}
+
+// ---------------------------------------------------------------------------
+// join
+// ---------------------------------------------------------------------------
+
+/** 从 memory metadata 里取 readerIds（会话级 join 的另一半 key）。 */
+export function readReaderIds(metadata?: string): string[] {
+  try {
+    const meta = JSON.parse(metadata || "{}") as Record<string, unknown>;
+    return Array.isArray(meta.readerIds)
+      ? meta.readerIds.filter((r): r is string => typeof r === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 把一条 memory 和 workflow observations 配对起来——本方案要补的那个 join key。
+ *
+ * 两条路，精确的优先：
+ *   exact   —— observation.recalledIds 直接点名了这条 memory
+ *   session —— observation.readerId 在这条 memory 的 readerIds 里（同一会话读过它）
+ * 同一条 observation 只算一次，exact 覆盖 session。
+ */
+export function linkMemoryToObservations(
+  memoryId: string,
+  memoryMetadata: string | undefined,
+  observations: readonly WorkflowObservationRecord[],
+): MemoryOutcomeLink[] {
+  const readerIds = new Set(readReaderIds(memoryMetadata));
+  const links: MemoryOutcomeLink[] = [];
+
+  for (const obs of observations) {
+    const exact = Array.isArray(obs.recalledIds) && obs.recalledIds.includes(memoryId);
+    const session = !exact && !!obs.readerId && readerIds.has(obs.readerId);
+    if (!exact && !session) continue;
+    links.push({
+      observationId: obs.observationId,
+      workflowId: obs.workflowId,
+      outcome: obs.outcome,
+      recordedAt: obs.recordedAt,
+      join: exact ? "exact" : "session",
+      summary: obs.summary,
+    });
+  }
+
+  return links.sort((a, b) => Date.parse(b.recordedAt) - Date.parse(a.recordedAt));
+}
+
+// ---------------------------------------------------------------------------
+// 汇总 + 效用
+// ---------------------------------------------------------------------------
+
+function emptyCounts(): Record<WorkflowObservationOutcome, number> {
+  return { success: 0, failure: 0, corrected: 0, missed: 0 };
+}
+
+/**
+ * 汇总一条 memory 的参与记录，算出成功率与 utility。
+ *
+ * utility = Σ(w_join · decay · R) / Σ(w_join · decay)
+ * 加权平均而不是求和：一条被读一百次的记忆不该仅凭次数就压过一条被读三次但每次都救场的。
+ */
+export function summarizeMemoryOutcomes(
+  memoryId: string,
+  links: readonly MemoryOutcomeLink[],
+  now = Date.now(),
+  options: { preferExact?: boolean } = {},
+): MemoryOutcomeSummary {
+  const preferExact = options.preferExact ?? true;
+  const counts = emptyCounts();
+  let exactCount = 0;
+  let sessionCount = 0;
+  let exactSuccess = 0;
+  const acc = {
+    exact: { reward: 0, weight: 0 },
+    session: { reward: 0, weight: 0 },
+  };
+
+  for (const link of links) {
+    counts[link.outcome]++;
+    if (link.join === "exact") {
+      exactCount++;
+      if (link.outcome === "success") exactSuccess++;
+    } else {
+      sessionCount++;
+    }
+
+    const ageDays = Math.max(0, (now - Date.parse(link.recordedAt)) / 86_400_000);
+    const decay = Math.pow(0.5, ageDays / UTILITY_HALF_LIFE_DAYS);
+    const weight = JOIN_WEIGHT[link.join] * decay;
+    acc[link.join].reward += weight * OUTCOME_REWARD[link.outcome];
+    acc[link.join].weight += weight;
+  }
+
+  // 有精确样本时不掺会话级样本 —— 这不是洁癖，是 2026-08-23 落地当天的实测结论：
+  // 同一个会话跑多个任务时，readerId join 会把无关任务的成败摊到每条被读过的记忆头上。
+  // 实测那次 5 条记忆的会话级成功率全是 44%（同一批 observation），
+  // 而精确成功率是 100% / 33% / 0% —— 后者才带信息，前者是会话噪声的常数。
+  // 一条从没被精确点名过的记忆（历史 observation / CLI 上报）仍退回会话级，聊胜于无。
+  const useExact = preferExact && acc.exact.weight >= MIN_EFFECTIVE_SAMPLES;
+  const basisAcc = useExact
+    ? acc.exact
+    : { reward: acc.exact.reward + acc.session.reward, weight: acc.exact.weight + acc.session.weight };
+
+  const total = links.length;
+  const hasUtility = basisAcc.weight >= MIN_EFFECTIVE_SAMPLES;
+  return {
+    memoryId,
+    total,
+    exactCount,
+    sessionCount,
+    counts,
+    successRate: total > 0 ? counts.success / total : null,
+    exactSuccessRate: exactCount > 0 ? exactSuccess / exactCount : null,
+    utility: hasUtility ? basisAcc.reward / basisAcc.weight : null,
+    effectiveSamples: basisAcc.weight,
+    utilityBasis: !hasUtility ? "none" : useExact ? "exact" : "session",
+    links: [...links],
+  };
+}
+
+/** 一步到位：memory + observations → 汇总。 */
+export function computeMemoryUtility(
+  entry: Pick<MemoryEntry, "id" | "metadata">,
+  observations: readonly WorkflowObservationRecord[],
+  now = Date.now(),
+  options: { preferExact?: boolean } = {},
+): MemoryOutcomeSummary {
+  return summarizeMemoryOutcomes(
+    entry.id,
+    linkMemoryToObservations(entry.id, entry.metadata, observations),
+    now,
+    options,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 写回 metadata
+// ---------------------------------------------------------------------------
+
+/** metadata 里 utility 三件套的字段名。改名要同步 retriever 的 applyUtilityWeight。 */
+export const UTILITY_FIELD = "utility";
+export const UTILITY_SAMPLES_FIELD = "utilitySamples";
+export const UTILITY_UPDATED_FIELD = "utilityUpdatedAt";
+export const UTILITY_BASIS_FIELD = "utilityBasis";
+
+/** 从 metadata 读 utility；没有/坏了都返回 null（不是 0——见上文语义说明）。 */
+export function readUtility(metadata?: string): number | null {
+  try {
+    const meta = JSON.parse(metadata || "{}") as Record<string, unknown>;
+    const value = meta[UTILITY_FIELD];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 把 utility 写进 metadata 对象（纯函数，调用方负责落库）。
+ * utility=null 时**清除**旧值，而不是写 0：证据没了就该退回「没数据」，不是退回「中性」。
+ */
+export function applyUtilityToMeta(
+  meta: Record<string, unknown>,
+  summary: MemoryOutcomeSummary,
+  now = Date.now(),
+): Record<string, unknown> {
+  const next = { ...meta };
+  if (summary.utility === null) {
+    delete next[UTILITY_FIELD];
+    delete next[UTILITY_SAMPLES_FIELD];
+    delete next[UTILITY_BASIS_FIELD];
+    delete next[UTILITY_UPDATED_FIELD];
+    return next;
+  }
+  next[UTILITY_FIELD] = Number(summary.utility.toFixed(4));
+  next[UTILITY_SAMPLES_FIELD] = Number(summary.effectiveSamples.toFixed(4));
+  next[UTILITY_BASIS_FIELD] = summary.utilityBasis;
+  next[UTILITY_UPDATED_FIELD] = now;
+  return next;
+}
+
+// ---------------------------------------------------------------------------
+// 输出
+// ---------------------------------------------------------------------------
+
+function pct(value: number | null): string {
+  return value === null ? "n/a" : `${Math.round(value * 100)}%`;
+}
+
+export function formatMemoryUtility(summary: MemoryOutcomeSummary, options: { showLinks?: number } = {}): string {
+  const lines: string[] = [];
+  lines.push(`Memory ${summary.memoryId}`);
+  lines.push(`  参与任务: ${summary.total} 条 (精确 ${summary.exactCount} / 会话级 ${summary.sessionCount})`);
+  lines.push(
+    `  outcome:  success=${summary.counts.success} corrected=${summary.counts.corrected}`
+    + ` missed=${summary.counts.missed} failure=${summary.counts.failure}`,
+  );
+  lines.push(`  成功率:   ${pct(summary.successRate)}  (仅精确 join: ${pct(summary.exactSuccessRate)})`);
+  lines.push(
+    `  utility:  ${summary.utility === null ? "null（样本不足，不下结论）" : summary.utility.toFixed(4)}`
+    + `  [基于 ${summary.utilityBasis} join，有效样本 ${summary.effectiveSamples.toFixed(2)}]`,
+  );
+
+  const limit = options.showLinks ?? 0;
+  if (limit > 0 && summary.links.length > 0) {
+    lines.push("  最近参与:");
+    for (const link of summary.links.slice(0, limit)) {
+      lines.push(
+        `    ${link.recordedAt.slice(0, 10)} [${link.join}] ${link.workflowId} → ${link.outcome}`
+        + `  ${link.summary.slice(0, 60)}`,
+      );
+    }
+  }
+  return lines.join("\n");
+}