recallnest 2.6.1 → 3.0.1

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");
+}

package/src/pivot-apply.ts

@@ -36,9 +36,17 @@ import {
 import { assignDefaultConfidence } from "./confidence-tracker.js";
 import { detectLang, tokenizeFts } from "./language-hook.js";
 import { scanForPII, redactSecrets } from "./pii-detector.js";
+import {
+  EvidenceCoordinateSchema,
+  EvidenceWindowSchema,
+  PIVOT_EVIDENCE_CONTRACT_VERSION,
+  PivotEvidenceProvenanceSchema,
+  evidenceWindowIssues,
+} from "./pivot-evidence.js";
 
 export const PIVOT_APPLY_SOURCE = "session_distill";
 export const PIVOT_APPLY_CAPTURE = "pivot_apply_v1";
+export const PIVOT_APPLY_EVIDENCE_CAPTURE = "pivot_apply_v2";
 export const PIVOT_SCOPE = "memory:pivot";
 
 const SHA256_HEX = /^[0-9a-f]{64}$/;
@@ -77,12 +85,46 @@ export const PivotCandidateInputSchema = z
     candidateHash: z.string().regex(SHA256_HEX, "candidateHash must be 64-char sha256 hex"),
     batchId: z.string().min(1).max(64),
     importance: z.number().min(0).max(1),
+    evidenceContractVersion: z.literal(PIVOT_EVIDENCE_CONTRACT_VERSION).optional(),
+    sourceFingerprint: z.string().regex(SHA256_HEX).optional(),
+    anchorCoordinate: EvidenceCoordinateSchema.optional(),
+    evidenceWindows: z.array(EvidenceWindowSchema).max(16).optional(),
   })
   .refine((c) => KIND_CATEGORY[c.kind] === c.proposedCategory, {
     message: "proposedCategory does not match kind (corpus-verified mapping violated)",
+  })
+  .superRefine((candidate, context) => {
+    const fields = [
+      candidate.evidenceContractVersion,
+      candidate.sourceFingerprint,
+      candidate.anchorCoordinate,
+      candidate.evidenceWindows,
+    ];
+    if (fields.every((field) => field === undefined)) return;
+    const provenance = PivotEvidenceProvenanceSchema.safeParse({
+      evidenceContractVersion: candidate.evidenceContractVersion,
+      sourceFingerprint: candidate.sourceFingerprint,
+      anchorCoordinate: candidate.anchorCoordinate,
+      evidenceWindows: candidate.evidenceWindows,
+    });
+    if (!provenance.success) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "evidence provenance must be complete and match contract version 1",
+      });
+      return;
+    }
+    for (const issue of evidenceWindowIssues(provenance.data, candidate.evidence.length, candidate.sessionId)) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: issue });
+    }
   });
 export type PivotCandidateInput = z.infer<typeof PivotCandidateInputSchema>;
 
+export const PivotEvidenceCandidateInputSchema = PivotCandidateInputSchema.refine(
+  (candidate) => candidate.evidenceContractVersion === PIVOT_EVIDENCE_CONTRACT_VERSION,
+  { message: "evidence-coordinate apply requires contract version 1 provenance" },
+);
+
 export type PivotApplyDisposition =
   | "stored"
   | "updated"
@@ -195,10 +237,18 @@ export async function persistPivotCandidate(
   const language = detectLang(text);
   const fts_text = tokenizeFts(text, language);
 
+  const evidenceProvenance = input.evidenceContractVersion === PIVOT_EVIDENCE_CONTRACT_VERSION
+    ? PivotEvidenceProvenanceSchema.parse({
+      evidenceContractVersion: input.evidenceContractVersion,
+      sourceFingerprint: input.sourceFingerprint,
+      anchorCoordinate: input.anchorCoordinate,
+      evidenceWindows: input.evidenceWindows,
+    })
+    : null;
   let metadata = buildStructuredMetadata({
     source: PIVOT_APPLY_SOURCE,
     tags: [...input.tags, "pivot-apply", `batch:${input.batchId}`],
-    capture: PIVOT_APPLY_CAPTURE,
+    capture: evidenceProvenance ? PIVOT_APPLY_EVIDENCE_CAPTURE : PIVOT_APPLY_CAPTURE,
     category: input.proposedCategory,
     canonicalKey: input.canonicalKey,
     extra: {
@@ -210,6 +260,7 @@ export async function persistPivotCandidate(
         reportId: input.reportId,
         candidateHash: input.candidateHash,
         batchId: input.batchId,
+        ...(evidenceProvenance ?? {}),
       },
     },
   });

package/src/pivot-evidence.ts

@@ -0,0 +1,128 @@
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+export const PIVOT_EVIDENCE_CONTRACT_VERSION = 1 as const;
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+export const EvidenceCoordinateSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  ordinal: z.number().int().nonnegative(),
+  role: z.enum(["user", "assistant"]),
+  contentDigest: z.string().regex(SHA256_HEX),
+}).strict();
+export type EvidenceCoordinate = z.infer<typeof EvidenceCoordinateSchema>;
+
+export const EvidenceWindowTurnSchema = z.object({
+  ordinal: z.number().int().nonnegative(),
+  role: z.enum(["user", "assistant"]),
+  contentDigest: z.string().regex(SHA256_HEX),
+  evidenceIndexes: z.array(z.number().int().nonnegative()).min(1).max(16),
+}).strict();
+export type EvidenceWindowTurn = z.infer<typeof EvidenceWindowTurnSchema>;
+
+export const EvidenceWindowSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  startOrdinal: z.number().int().nonnegative(),
+  endOrdinal: z.number().int().nonnegative(),
+  turns: z.array(EvidenceWindowTurnSchema).min(1).max(16),
+}).strict();
+export type EvidenceWindow = z.infer<typeof EvidenceWindowSchema>;
+
+export const PivotEvidenceProvenanceSchema = z.object({
+  evidenceContractVersion: z.literal(PIVOT_EVIDENCE_CONTRACT_VERSION),
+  sourceFingerprint: z.string().regex(SHA256_HEX),
+  anchorCoordinate: EvidenceCoordinateSchema,
+  evidenceWindows: z.array(EvidenceWindowSchema).max(16),
+}).strict();
+export type PivotEvidenceProvenance = z.infer<typeof PivotEvidenceProvenanceSchema>;
+
+export function turnContentDigest(input: {
+  sessionId: string;
+  ordinal: number;
+  role: "user" | "assistant";
+  text: string;
+}): string {
+  const canonical = JSON.stringify({
+    schemaVersion: PIVOT_EVIDENCE_CONTRACT_VERSION,
+    sessionId: input.sessionId,
+    ordinal: input.ordinal,
+    role: input.role,
+    text: input.text.replace(/\u0000/g, "").trim(),
+  });
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+export function evidenceWindowIssues(
+  provenance: PivotEvidenceProvenance,
+  evidenceCount: number,
+  expectedSessionId: string,
+): string[] {
+  const issues: string[] = [];
+  if (provenance.anchorCoordinate.sessionId !== expectedSessionId) {
+    issues.push("anchor coordinate sessionId does not match candidate sessionId");
+  }
+  if (provenance.anchorCoordinate.role !== "user") {
+    issues.push("anchor coordinate must point to a user turn");
+  }
+
+  const seenEvidence = new Set<number>();
+  let previousEnd = -2;
+  for (const [windowIndex, window] of provenance.evidenceWindows.entries()) {
+    if (window.sessionId !== expectedSessionId) {
+      issues.push(`evidence window ${windowIndex} sessionId does not match candidate sessionId`);
+    }
+    const first = window.turns[0];
+    const last = window.turns[window.turns.length - 1];
+    if (window.startOrdinal !== first.ordinal || window.endOrdinal !== last.ordinal) {
+      issues.push(`evidence window ${windowIndex} bounds do not match its turns`);
+    }
+    if (window.startOrdinal <= previousEnd + 1) {
+      issues.push(`evidence window ${windowIndex} overlaps or should be merged with the previous window`);
+    }
+    previousEnd = window.endOrdinal;
+
+    for (let turnIndex = 0; turnIndex < window.turns.length; turnIndex++) {
+      const turn = window.turns[turnIndex];
+      if (turn.ordinal !== window.startOrdinal + turnIndex) {
+        issues.push(`evidence window ${windowIndex} contains a non-contiguous ordinal range`);
+      }
+      const localIndexes = new Set<number>();
+      for (const evidenceIndex of turn.evidenceIndexes) {
+        if (localIndexes.has(evidenceIndex)) {
+          issues.push(`evidence index ${evidenceIndex} is repeated inside one turn`);
+        }
+        localIndexes.add(evidenceIndex);
+        if (evidenceIndex < 0 || evidenceIndex >= evidenceCount) {
+          issues.push(`evidence index ${evidenceIndex} is outside the candidate evidence array`);
+        } else if (seenEvidence.has(evidenceIndex)) {
+          issues.push(`evidence index ${evidenceIndex} is mapped more than once`);
+        } else {
+          seenEvidence.add(evidenceIndex);
+        }
+      }
+    }
+  }
+  for (let index = 0; index < evidenceCount; index++) {
+    if (!seenEvidence.has(index)) issues.push(`evidence index ${index} has no source coordinate`);
+  }
+  return issues;
+}
+
+/**
+ * Add provenance to content-addressed payloads only when the v1 evidence
+ * contract is present. Historical 2026-08-03 candidates remain byte-for-byte
+ * compatible; a partial or malformed new contract fails closed.
+ */
+export function evidenceIdentityPayload(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const record = value as Record<string, unknown>;
+  if (record.evidenceContractVersion === undefined) return {};
+  return PivotEvidenceProvenanceSchema.parse({
+    evidenceContractVersion: record.evidenceContractVersion,
+    sourceFingerprint: record.sourceFingerprint,
+    anchorCoordinate: record.anchorCoordinate,
+    evidenceWindows: record.evidenceWindows,
+  });
+}

package/src/ppr-traversal.ts

@@ -10,7 +10,11 @@ import type { KGTriple, NeighborhoodResult } from "./kg-store.js";
 // ============================================================================
 
 export interface PPRConfig {
-  /** Teleport probability back to seed nodes (default: 0.85) */
+  /**
+   * Probability of CONTINUING to diffuse along an edge at each step.
+   * The teleport-back-to-seed probability is the complement: (1 - dampingFactor).
+   * (The previous version of this comment had the two reversed.)
+   */
   dampingFactor: number;
   /** Max power-iteration rounds (default: 10) */
   maxIterations: number;
@@ -31,6 +35,26 @@ export interface PPRResult {
   path: string[];
 }
 
+/**
+ * NOTE on dampingFactor = 0.85 (measured 2026-08-28, deliberately NOT changed):
+ *
+ * 0.85 is Brin & Page's default, tuned for billion-node web link graphs.
+ * HippoRAG 2 (arXiv 2502.14802, Table 13) uses 0.5 for knowledge graphs.
+ *
+ * Sensitivity measured on our own production KG (60,536 nodes / 66,332 edges,
+ * 10 real seeds, Top-10 Jaccard against alpha=0.85):
+ *   alpha=0.30 -> 0.617 | 0.50 -> 0.648 | 0.70 -> 0.760 | 0.95 -> 0.598
+ *   alpha=0.30 vs alpha=0.95 -> 0.371  (~63% of results differ)
+ * So the parameter IS sensitive. It is nevertheless left at 0.85, because
+ * tuning it does not fix the actual failure mode: at every alpha tested,
+ * generic hub nodes ("user" / "assistant" / "Alice") take ~30% of the top-20
+ * and land at ranks 2-4. Changing alpha only reshuffles the hubs among
+ * themselves.
+ *
+ * Fix the graph first (entity normalization + hub suppression), then tune.
+ * Revisit only after the top-20 hub share drops materially; any change must
+ * go through a shadow run first.
+ */
 export const DEFAULT_PPR_CONFIG: PPRConfig = {
   dampingFactor: 0.85,
   maxIterations: 10,

package/src/recall-ledger.ts

@@ -0,0 +1,76 @@
+/**
+ * Recall Ledger — 进程内的「这次会话读到过哪些记忆」账本。
+ *
+ * 存在的理由（P0 join key）：价值回溯要的是 `(memory_id, outcome)` 配对，而库里
+ * 一边有结果没参与者（workflow observation 不记 memory），一边有参与者没结果
+ * （access-tracker 记命中不记任务成败）。这个模块补的就是中间那一段：
+ * 检索命中时记一笔，`workflow_observe` 上报时把窗口内命中的 id 一起写进 observation。
+ *
+ * 为什么是**进程级**而不是挂在 AccessTracker 实例上：
+ *   `createComponentResolver`（runtime-config.ts:226）按 profileName 缓存 components，
+ *   每个 profile 各有一个 AccessTracker → 各自随机一个 readerId。检索走 profile A、
+ *   上报走 default 时，两边 readerId 对不上，join 直接失效。而 access-tracker.ts:63
+ *   的注释本来就写着「one stdio MCP server process ≈ one CC session」——那句话描述的
+ *   语义单位是**进程**，实现却落在实例上。这里把它扶正，顺带修掉多 profile 时
+ *   readerIds/distinctReaderCount 被同一个会话灌进多个假 reader 的虚高。
+ */
+
+/** 本进程（≈ 本次 CC 会话）的读者身份。所有 AccessTracker 默认共享它。 */
+export const PROCESS_READER_ID = `r-${crypto.randomUUID().slice(0, 8)}`;
+
+/** 默认回看窗口：一次任务从检索到上报 outcome 的常见跨度。 */
+export const DEFAULT_RECALL_WINDOW_MS = 30 * 60_000;
+
+/** 一条 observation 最多带多少个 memory id。防止长会话把整个 top-k 历史灌进 observation。 */
+export const RECALLED_IDS_CAP = 64;
+
+/** 账本自身的常驻上限；超出时按最后命中时间淘汰最老的。 */
+const LEDGER_CAP = 512;
+
+/** memoryId → 最后一次被检索返回的时间戳(ms)。 */
+const hits = new Map<string, number>();
+
+/**
+ * 记录这批 id 在本进程被检索返回过。
+ *
+ * 注意调用点在 novelty/cooldown gate **之前**：那两道闸问的是「值不值得强化衰减半衰期」，
+ * 这里问的是「agent 有没有真的看到这条」。同一批 id 两个问题的答案可以不同，
+ * 用强化闸去过滤 join 参与者会系统性漏掉最常被读到的那些条目。
+ */
+export function recordRecallHits(ids: readonly string[], now = Date.now()): void {
+  for (const id of ids) {
+    if (typeof id === "string" && id.length > 0) hits.set(id, now);
+  }
+  if (hits.size > LEDGER_CAP) {
+    const sorted = [...hits.entries()].sort((a, b) => b[1] - a[1]);
+    hits.clear();
+    for (const [id, ts] of sorted.slice(0, LEDGER_CAP)) hits.set(id, ts);
+  }
+}
+
+/**
+ * 取窗口内被命中过的 memory id，最近命中的排前面。
+ * windowMs <= 0 表示不限时间（仍受 cap 约束）。
+ */
+export function recentRecallHits(
+  windowMs = DEFAULT_RECALL_WINDOW_MS,
+  cap = RECALLED_IDS_CAP,
+  now = Date.now(),
+): string[] {
+  const cutoff = windowMs > 0 ? now - windowMs : Number.NEGATIVE_INFINITY;
+  return [...hits.entries()]
+    .filter(([, ts]) => ts >= cutoff)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, Math.max(0, cap))
+    .map(([id]) => id);
+}
+
+/** 当前账本条目数（诊断/测试用）。 */
+export function recallLedgerSize(): number {
+  return hits.size;
+}
+
+/** 清空账本。测试隔离用；生产路径不调用。 */
+export function resetRecallLedger(): void {
+  hits.clear();
+}