recallnest 2.3.0 → 2.6.0

package/src/consolidation-engine.ts

@@ -17,12 +17,15 @@
  * LLM-free — deterministic clustering and merge only.
  */
 
-import type { MemoryEntry, MemorySearchResult, MemoryStore } from "./store.js";
+import type { MemoryEntry, MemorySearchResult } from "./store.js";
+import { deterministicId } from "./store.js";
+import type { MemoryStorePort } from "./memory-store-port.js";
 import { createVersionGroup } from "./version-manager.js";
 import { isActiveMemory, parseEvolution, buildSupersedeMetadata, buildConsolidatedMetadata, patchEvolution } from "./memory-evolution.js";
 import { cosineSimilarity } from "./multi-vector.js";
 import type { LLMClient } from "./llm-client.js";
 import type { Embedder } from "./embedder.js";
+import { logWarn } from "./stderr-log.js";
 
 // ---------------------------------------------------------------------------
 // Config & Types
@@ -35,12 +38,22 @@ export interface ConsolidationConfig {
   mergeThreshold: number;
   /** Maximum entries to scan per consolidation run (default 500) */
   maxEntriesPerRun: number;
+  /**
+   * KG evidence: triple-set Jaccard at/above this merges a grey-zone pair
+   * (vector sim between clusterThreshold and mergeThreshold). Default 0.5 —
+   * provisional until calibrated on production data (plan Q3).
+   */
+  tripleJaccardThreshold?: number;
+  /** KG evidence: both sides need at least this many triples to qualify (default 2) */
+  minTriplesForEvidence?: number;
 }
 
 export const DEFAULT_CONSOLIDATION_CONFIG: ConsolidationConfig = {
   clusterThreshold: 0.82,
   mergeThreshold: 0.92,
   maxEntriesPerRun: 500,
+  tripleJaccardThreshold: 0.5,
+  minTriplesForEvidence: 2,
 };
 
 export interface ConflictEvent {
@@ -54,10 +67,52 @@ export interface ConsolidationResult {
   clustersFound: number;
   mergedCount: number;
   relationsAdded: number;
+  /** Of mergedCount, how many were below mergeThreshold and merged on KG triple evidence */
+  tripleEvidenceMerges: number;
   conflictsDetected: ConflictEvent[];
   scope: string;
 }
 
+// ---------------------------------------------------------------------------
+// KG evidence source (duck-typed subset of KGStore)
+// ---------------------------------------------------------------------------
+
+/** The two triple fields consolidation needs — structurally satisfied by KGTriple. */
+export interface ConsolidationTripleEvidence {
+  id: string;
+  mention_count: number;
+}
+
+export interface ConsolidationKGSource {
+  getTriplesBySourceMemories(memoryIds: string[]): Promise<Map<string, ConsolidationTripleEvidence[]>>;
+}
+
+/**
+ * Jaccard overlap of two triple-id sets. Below `minSize` on either side the
+ * evidence is considered too weak and 0 is returned (a single shared triple
+ * must not merge two memories on its own).
+ */
+export function tripleJaccard(
+  a: ReadonlySet<string> | undefined,
+  b: ReadonlySet<string> | undefined,
+  minSize = 2,
+): number {
+  if (!a || !b || a.size < minSize || b.size < minSize) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter++;
+  return inter / (a.size + b.size - inter);
+}
+
+/**
+ * Mention-frequency boost in canonical selection: tie-breaker ONLY, never an
+ * override of a clear canonicalScore gap (an entry with one hot triple must
+ * not demote a substantially more important memory to consolidated status).
+ * α=0.06 keeps the boost differentiating (m=1 → 1.042, m=9 → 1.138) while the
+ * 1.1 cap bounds the maximum flip at ~10% of the base score — effectively ties.
+ */
+const MENTION_ALPHA = 0.06;
+const MENTION_BOOST_CAP = 1.1;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -108,7 +163,7 @@ export function detectHeuristicContradiction(textA: string, textB: string): bool
 // Store interface (duck-typed to avoid hard dependency)
 // ---------------------------------------------------------------------------
 
-type ConsolidationStore = Pick<MemoryStore, "list" | "getById" | "vectorSearch" | "update">;
+type ConsolidationStore = Pick<MemoryStorePort, "list" | "getById" | "vectorSearch" | "update">;
 
 // ---------------------------------------------------------------------------
 // Engine
@@ -118,17 +173,25 @@ export class ConsolidationEngine {
   constructor(
     private store: ConsolidationStore,
     private config: ConsolidationConfig = DEFAULT_CONSOLIDATION_CONFIG,
+    /** Optional KG evidence source — absent = pure vector behavior, unchanged */
+    private kgSource: ConsolidationKGSource | null = null,
   ) {}
 
   async run(scope: string): Promise<ConsolidationResult> {
-    const { clusterThreshold, mergeThreshold, maxEntriesPerRun } = this.config;
+    const {
+      clusterThreshold,
+      mergeThreshold,
+      maxEntriesPerRun,
+      tripleJaccardThreshold = 0.5,
+      minTriplesForEvidence = 2,
+    } = this.config;
 
     // 1. Fetch entries in scope
     const entries = await this.store.list([scope], undefined, maxEntriesPerRun, 0);
     const active = entries.filter(isActive);
 
     if (active.length === 0) {
-      return { originalCount: 0, clustersFound: 0, mergedCount: 0, relationsAdded: 0, conflictsDetected: [], scope };
+      return { originalCount: 0, clustersFound: 0, mergedCount: 0, relationsAdded: 0, tripleEvidenceMerges: 0, conflictsDetected: [], scope };
     }
 
     // 2. Group by category
@@ -142,6 +205,7 @@ export class ConsolidationEngine {
     let clustersFound = 0;
     let mergedCount = 0;
     let relationsAdded = 0;
+    let tripleEvidenceMerges = 0;
     const conflictsDetected: ConflictEvent[] = [];
 
     // 3. Cluster within each category
@@ -161,8 +225,18 @@ export class ConsolidationEngine {
           full.vector, 10, clusterThreshold, [scope],
         );
 
+        // Seeds are active-only (above), but vectorSearch filters by scope alone, so
+        // superseded belief-history rows surface here too. A rephrased belief sits well
+        // above mergeThreshold from its own archived version, and canonicalScore has no
+        // recency term — importance × access count are both inherited by the history row,
+        // so the two tie and the "weaker" one is picked arbitrarily. Lose that coin flip
+        // and the live belief gets marked consolidated, dropping out of default retrieval
+        // while the abandoned version stands in as canonical.
         const members = similar.filter(
-          s => s.entry.id !== entry.id && !clustered.has(s.entry.id) && s.entry.category === entry.category,
+          s => s.entry.id !== entry.id
+            && !clustered.has(s.entry.id)
+            && s.entry.category === entry.category
+            && isActive(s.entry),
         );
 
         if (members.length === 0) continue;
@@ -183,8 +257,27 @@ export class ConsolidationEngine {
         }
         if (memberEntries.length < 2) continue;
 
-        // Determine canonical: highest canonicalScore
-        const sorted = [...memberEntries].sort((a, b) => canonicalScore(b) - canonicalScore(a));
+        // KG triple evidence for this cluster (single batch query; best-effort —
+        // on failure consolidation proceeds vector-only)
+        const tripleIdsByMember = new Map<string, Set<string>>();
+        const maxMentionByMember = new Map<string, number>();
+        if (this.kgSource) {
+          try {
+            const triplesByMember = await this.kgSource.getTriplesBySourceMemories(memberEntries.map(e => e.id));
+            for (const [mid, triples] of triplesByMember) {
+              tripleIdsByMember.set(mid, new Set(triples.map(t => t.id)));
+              maxMentionByMember.set(mid, triples.reduce((m, t) => Math.max(m, t.mention_count), 0));
+            }
+          } catch { /* KG evidence is best-effort */ }
+        }
+
+        // Determine canonical: highest canonicalScore, frequency-boosted when
+        // KG evidence exists (memories carrying often-mentioned facts win ties)
+        const mentionBoost = (e: MemoryEntry) =>
+          Math.min(MENTION_BOOST_CAP, 1 + MENTION_ALPHA * Math.log((maxMentionByMember.get(e.id) ?? 0) + 1));
+        const sorted = [...memberEntries].sort(
+          (a, b) => canonicalScore(b) * mentionBoost(b) - canonicalScore(a) * mentionBoost(a),
+        );
         const canonical = sorted[0];
 
         if (!canonical.vector?.length) continue;
@@ -199,7 +292,16 @@ export class ConsolidationEngine {
         for (const member of sorted.slice(1)) {
           const sim = scoreMap.get(member.id) ?? clusterThreshold;
 
-          if (sim >= mergeThreshold) {
+          // Second evidence source: two memories whose extracted fact sets
+          // overlap heavily are duplicates even when vector sim sits in the
+          // grey zone (the "pairwise near-duplicates" the 0.92 bar misses).
+          const jaccard = tripleJaccard(
+            tripleIdsByMember.get(canonical.id),
+            tripleIdsByMember.get(member.id),
+            minTriplesForEvidence,
+          );
+
+          if (sim >= mergeThreshold || jaccard >= tripleJaccardThreshold) {
             // Tier 3.3: Version coexistence — both stay but grouped.
             await createVersionGroup(this.store, canonical, member, scope);
             // C-1: Also mark the weaker entry as consolidated via evolution metadata
@@ -214,6 +316,7 @@ export class ConsolidationEngine {
               await this.store.update(canonical.id, { metadata: updatedCanon }, [scope]);
             }
             mergedCount++;
+            if (sim < mergeThreshold) tripleEvidenceMerges++;
           } else {
             // Link: add clustered_with relation
             const memberMeta = parseMetadata(member);
@@ -245,7 +348,7 @@ export class ConsolidationEngine {
       }
     }
 
-    return { originalCount: active.length, clustersFound, mergedCount, relationsAdded, conflictsDetected, scope };
+    return { originalCount: active.length, clustersFound, mergedCount, relationsAdded, tripleEvidenceMerges, conflictsDetected, scope };
   }
 }
 
@@ -262,6 +365,14 @@ export interface ClusterConsolidationResult {
   entriesLinked: number;
   /** CC-9: Set when consecutive low-yield rounds trigger early termination */
   earlyStop?: "diminishing_returns";
+  /**
+   * 本轮被吸收的 LLM 调用失败数（超时 / 网络 / 熔断抛出）。
+   *
+   * 计出来是为了让「吸收」不等于「静默」：吸收前，单个 cluster 撞 15s 超时会把整个
+   * scope 的 dream 炸掉（2026-08-09 memory 轮次连挂两次的根因）；吸收后若不计数，
+   * 「LLM 全程不可用」和「今天没料可炼」会长得一模一样。
+   */
+  llmFailures: number;
 }
 
 /**
@@ -278,7 +389,7 @@ export async function clusterAndConsolidate(params: {
   entries: MemoryEntry[];
   embedder: Pick<Embedder, "embedPassage">;
   llm: LLMClient;
-  store: Pick<MemoryStore, "store" | "update">;
+  store: Pick<MemoryStorePort, "store" | "update">;
   scope: string;
   /** Minimum cluster size to trigger consolidation (default: 3) */
   minClusterSize?: number;
@@ -306,6 +417,7 @@ export async function clusterAndConsolidate(params: {
     insightsGenerated: 0,
     patternsExtracted: 0,
     entriesLinked: 0,
+    llmFailures: 0,
   };
 
   // Filter to active entries with vectors
@@ -370,8 +482,26 @@ export async function clusterAndConsolidate(params: {
     }
 
     // Generate insight via LLM from cluster member texts
+    //
+    // 单个 cluster 的 LLM 失败不该炸掉整个 scope。llm-client 的 chat() 在 catch 里是
+    // `throw err`（记完熔断计数后原样抛），所以 15s AbortController 超时会一路冒到
+    // runDream 之外 —— 2026-08-09 memory 轮次连挂两次正是这条路径：memory 是最大
+    // scope、cluster 最多，撞上一次超时的概率接近 1，且两次挂的位置不同（不是某对
+    // 内容有毒，是这一阶段本来就没有防护）。隔壁 llm-consolidation.ts:68 的同类调用
+    // 一直有 try/catch，本处缺的是同一层保护。
+    //
+    // 吸收成 null 而不是新开一条分支：generateL0 返回 null（熔断打开 / 空响应）本来
+    // 就是合法路径，下面 `if (!insight)` 已经按「零产出轮次」处理。失败另计 llmFailures，
+    // 避免吸收变静默。
     const combinedText = cluster.map(m => m.text).join("\n---\n");
-    const insight = await llm.generateL0(combinedText);
+    let insight: string | null;
+    try {
+      insight = await llm.generateL0(combinedText);
+    } catch (err) {
+      result.llmFailures++;
+      logWarn(`[WARN] cluster insight LLM 调用失败，本簇跳过: ${err instanceof Error ? err.message : String(err)}`);
+      insight = null;
+    }
 
     if (!insight) {
       // CC-9: No insight produced — this is a zero-yield round
@@ -400,8 +530,13 @@ export async function clusterAndConsolidate(params: {
     // Embed the insight text
     const insightVector = await params.embedder.embedPassage(insight);
 
-    // Store the insight as a new memory
+    // Store the insight as a new memory. P0-2/P1-2: derive a deterministic id from the
+    // (sorted) source member ids so re-running dream/consolidate on the same cluster
+    // upserts the same insight row instead of appending a near-duplicate each run
+    // (the highest-frequency dup-id source). Cross-run stable because sourceIds are stable.
+    const sortedSourceIds = cluster.map(m => m.id).slice().sort();
     const insightEntry = await store.store({
+      id: deterministicId(scope, `cluster-insight:${sortedSourceIds.join(",")}`),
       text: insight,
       vector: insightVector,
       category: bestCat,
@@ -439,11 +574,27 @@ export async function clusterAndConsolidate(params: {
 
     // HP-5: Cross-memory pattern extraction
     if (extractPatterns && cluster.length >= 3) {
-      const patternText = await llm.extractPattern(cluster.map(m => m.text));
+      // 同上：pattern 抽取失败也只丢这一簇的 pattern，不连坐已经写好的 insight。
+      let patternText: string | null;
+      try {
+        patternText = await llm.extractPattern(cluster.map(m => m.text));
+      } catch (err) {
+        result.llmFailures++;
+        logWarn(`[WARN] pattern 抽取 LLM 调用失败，本簇跳过: ${err instanceof Error ? err.message : String(err)}`);
+        patternText = null;
+      }
       if (patternText) {
-        const patternImportance = Math.min(maxImportance + 0.1, 1.0);
+        // 与同函数上方的 cluster insight 取同一个值：派生物继承源里最高的 importance，
+        // 不额外加成。原本这里是 maxImportance + 0.1，会让 LLM 抽出的 pattern 比它的
+        // 任何一条源记忆都重要——而 importance >= 0.95 在本仓库里是「人工 pin」的专用
+        // 语义（cli.ts pin 操作把值抬到 0.95；auto-gc 视其为永不归档、decay-engine 视其
+        // 为永不衰减）。于是任何一条源 >= 0.85 的 cluster，其派生 pattern 都会自动跨进
+        // 人类锚点频段。加成想表达的「pattern 比源更有价值」若要保留，应走独立通道
+        // （检索 boost / 独立 tier / 显式 flag），不该占用这个频段。
+        const patternImportance = maxImportance;
         const patternVector = await params.embedder.embedPassage(patternText);
         const patternEntry = await store.store({
+          id: deterministicId(scope, `cluster-pattern:${sortedSourceIds.join(",")}`),
           text: patternText,
           vector: patternVector,
           category: "patterns",
@@ -492,7 +643,7 @@ export function formatConsolidationResult(result: ConsolidationResult): string {
     `Consolidation complete for scope: ${result.scope}`,
     `Scanned: ${result.originalCount} active entries`,
     `Clusters found: ${result.clustersFound}`,
-    `Merged (versioned): ${result.mergedCount}`,
+    `Merged (versioned): ${result.mergedCount}${result.tripleEvidenceMerges > 0 ? ` (${result.tripleEvidenceMerges} on triple evidence)` : ""}`,
     `Relations added: ${result.relationsAdded}`,
     `Conflicts detected: ${result.conflictsDetected.length}`,
   ];
@@ -509,6 +660,89 @@ export function formatConsolidationResult(result: ConsolidationResult): string {
 // LC-P2: Cluster-aware deduplication for retrieval results
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether an entry is a consolidation derivative — a cluster insight or a
+ * cross-memory pattern the LLM wrote from other entries, rather than something
+ * captured from the outside world.
+ *
+ * Single source of truth for the two metadata flags: retrieval uses it to
+ * collapse a derivative with its sources, and the dream gather uses it to keep
+ * derivatives from being re-consolidated as if they were raw material.
+ */
+export function isDerivedInsight(metadata: string | undefined): boolean {
+  if (!metadata) return false;
+  try {
+    const meta = JSON.parse(metadata) as Record<string, unknown>;
+    return meta.cluster_insight === true || meta.cross_memory_pattern === true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Synthesis uptake (Artel archivist_metrics.synthesis_uptake_rate 的对应物)
+// ---------------------------------------------------------------------------
+
+export interface SynthesisUptakeStats {
+  /** Entries scanned across the store (may be capped). */
+  scanned: number;
+  /** Derived insights found (cluster_insight / cross_memory_pattern). */
+  derivedTotal: number;
+  /** Derived insights with accessCount > 0 — actually read after synthesis. */
+  derivedRead: number;
+  /** derivedRead / derivedTotal; null when no derived insights exist. */
+  uptakeRate: number | null;
+  /** True when the scan hit the cap before exhausting the store. */
+  truncated: boolean;
+}
+
+/**
+ * Measure how many consolidation/dream products were ever read back.
+ * 把"升华产物没人用"从体感变成能报警的数字——uptake 长期为 0 说明
+ * 升华管线在产出无人消费的内容（或读打点断链）。
+ */
+export async function computeSynthesisUptake(
+  store: { listPage(opts: { limit?: number; offset?: number; includeVector?: boolean }): Promise<MemoryEntry[]> },
+  // 50K 覆盖当前 ~34K 生产库全量（2026-07-23 实测 cap 20K 只扫 57%，truncated 结论不完整）；
+  // metadata-only 分页扫描秒级，memory_stats 是低频人工工具，扫全比抽样值钱。
+  scanCap = 50_000,
+  pageSize = 1_000,
+): Promise<SynthesisUptakeStats> {
+  let scanned = 0;
+  let derivedTotal = 0;
+  let derivedRead = 0;
+  let offset = 0;
+  let truncated = false;
+
+  for (;;) {
+    const page = await store.listPage({ limit: pageSize, offset, includeVector: false });
+    if (page.length === 0) break;
+    for (const e of page) {
+      scanned++;
+      if (!isDerivedInsight(e.metadata)) continue;
+      derivedTotal++;
+      try {
+        const meta = JSON.parse(e.metadata || "{}") as Record<string, unknown>;
+        if (typeof meta.accessCount === "number" && meta.accessCount > 0) derivedRead++;
+      } catch { /* broken metadata → counts as unread */ }
+    }
+    offset += page.length;
+    if (page.length < pageSize) break;
+    if (offset >= scanCap) {
+      truncated = true;
+      break;
+    }
+  }
+
+  return {
+    scanned,
+    derivedTotal,
+    derivedRead,
+    uptakeRate: derivedTotal > 0 ? derivedRead / derivedTotal : null,
+    truncated,
+  };
+}
+
 /**
  * LC-P2: When a cluster insight and its source memories both appear in
  * retrieval results, keep only the cluster insight (it subsumes the
@@ -523,15 +757,13 @@ export function deduplicateByClusterInsight<T extends { entry: MemoryEntry; scor
   const coveredByInsight = new Set<string>();
 
   for (const r of results) {
-    if (!r.entry.metadata) continue;
+    if (!isDerivedInsight(r.entry.metadata)) continue;
     try {
-      const meta = JSON.parse(r.entry.metadata);
-      if (meta.cluster_insight === true || meta.cross_memory_pattern === true) {
-        const sources: unknown[] = meta.evolution?.sourceMemories;
-        if (Array.isArray(sources)) {
-          for (const id of sources) {
-            if (typeof id === "string") coveredByInsight.add(id);
-          }
+      const meta = JSON.parse(r.entry.metadata as string);
+      const sources: unknown[] = meta.evolution?.sourceMemories;
+      if (Array.isArray(sources)) {
+        for (const id of sources) {
+          if (typeof id === "string") coveredByInsight.add(id);
         }
       }
     } catch { /* skip unparseable */ }

package/src/context-composer-stable-selection.ts

@@ -162,7 +162,13 @@ function formatStableResult(category: StableCategory, result: RetrievalResult):
   // F1: Tag low-confidence memories in resume_context output
   const conf = getConfidence(result.entry);
   const tag = conf < 0.5 ? " [低置信]" : "";
-  return cleanText(`${STABLE_CATEGORY_LABELS[category]}: ${text}${tag}`, 230);
+  // 220 是 stableContext 的 schema 上限（session-schema.ts:61），不是随手写的数：
+  // 这里曾是 230，比上限大 10，而 interleaveUnique（context-composer-stable.ts:199-206）
+  // 不再截一次 —— 于是任何 221~230 字符的行都会让 composeResumeContext 末尾的
+  // ResumeContextResponseSchema.parse（context-composer.ts:541）抛
+  // "stableContext must be at most 220 characters"，整个 resume_context 调用失败。
+  // 改这个数之前先看 schema，两边必须一起动。
+  return cleanText(`${STABLE_CATEGORY_LABELS[category]}: ${text}${tag}`, 220);
 }
 
 export function selectStableResults(

package/src/context-composer.ts

@@ -1,4 +1,5 @@
 import { listPinAssets, type PinAsset } from "./memory-assets.js";
+import * as envConfig from "./env-config.js";
 import { buildStableContextSections } from "./context-composer-stable.js";
 import {
   buildAssociativeNestEntityFallbackQuery,
@@ -32,6 +33,8 @@ type ResumeCategory = "profile" | "preferences" | "entities" | "patterns" | "cas
 
 interface ResumeRetriever {
   retrieve(context: RetrievalContext): Promise<RetrievalResult[]>;
+  /** Optional: 影子记录 resume reconstruction 引用的记忆（injection-vs-use）。未实现则 no-op。 */
+  recordReconstructionUsage?(citedIds: string[]): Promise<void>;
 }
 
 interface CheckpointLookup {
@@ -467,7 +470,7 @@ export async function composeResumeContext(
   let reconstructedContext: string | undefined;
   let reconstructionConfidence: number | undefined;
   let reconstructionContradictions: Array<{ memoryIds: [string, string]; description: string }> | undefined;
-  const constructiveFlag = process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL === "true";
+  const constructiveFlag = envConfig.constructiveRetrieval();
   if (constructiveFlag && deps.llm?.isAvailable?.()) {
     const allReconResults = [...profileResults, ...preferenceResults, ...entityResults, ...filteredPatterns, ...filteredCases];
     if (allReconResults.length >= 3) {
@@ -489,6 +492,10 @@ export async function composeResumeContext(
         if (recon.contradictions.length > 0) {
           reconstructionContradictions = recon.contradictions;
         }
+        // Shadow usage：resume reconstruction 真正引用的记忆记 use 计数（不动 ranking/forget）。
+        if (recon.sources.length > 0) {
+          await deps.retriever.recordReconstructionUsage?.(recon.sources.map(s => s.id));
+        }
       } catch { /* silent fallback */ }
     }
   }

package/src/data-checkup.ts

@@ -16,6 +16,7 @@ import type { MemoryEntry, MemoryStore } from "./store.js";
 import { resolveTier, type MemoryTier } from "./decay-engine.js";
 import { measureInterferenceDensity } from "./interference-detector.js";
 import { readHeartbeats, checkSourceStaleness, formatAge } from "./source-heartbeat.js";
+import { deriveUsageStatus, isUsageSignalActive, type UsageStatus } from "./usage-tracker.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -30,6 +31,8 @@ export interface CheckResult {
 export interface CheckupReport {
   checks: CheckResult[];
   totalEntries: number;
+  /** Total entries in store; when > totalEntries, only the most recent were scanned. */
+  totalAvailable: number;
   timestamp: string;
 }
 
@@ -39,15 +42,33 @@ export interface CheckupReport {
 
 /** Check 1: All vectors should have the same dimension. */
 function checkVectorDimensions(entries: MemoryEntry[]): CheckResult {
+  // 只对真正取到向量的条目判维度一致性;取不到向量的(dim=0)单独计数后跳过——
+  // 否则会把"未补到向量"误报成"维度不一致",或把"全 0 维空向量"假报成健康。
   const dims = new Map<number, number>(); // dim → count
+  let missingVectors = 0;
   for (const e of entries) {
     const d = e.vector?.length ?? 0;
+    if (d === 0) { missingVectors++; continue; }
     dims.set(d, (dims.get(d) ?? 0) + 1);
   }
 
-  if (dims.size <= 1) {
+  const withVectors = entries.length - missingVectors;
+  if (entries.length === 0) {
+    return { name: "vector_dimensions", status: "ok", detail: "No entries to check" };
+  }
+  if (withVectors === 0) {
+    return {
+      name: "vector_dimensions",
+      status: "warning",
+      detail: `No retrievable vectors among ${entries.length} entries — dimension consistency not verified`,
+    };
+  }
+
+  const suffix = missingVectors > 0 ? ` (${missingVectors} without retrievable vector, skipped)` : "";
+
+  if (dims.size === 1) {
     const dim = dims.keys().next().value ?? 0;
-    return { name: "vector_dimensions", status: "ok", detail: `All ${entries.length} entries have dimension ${dim}` };
+    return { name: "vector_dimensions", status: "ok", detail: `All ${withVectors} vectors have dimension ${dim}${suffix}` };
   }
 
   const sorted = [...dims.entries()].sort((a, b) => b[1] - a[1]);
@@ -56,7 +77,7 @@ function checkVectorDimensions(entries: MemoryEntry[]): CheckResult {
   return {
     name: "vector_dimensions",
     status: "error",
-    detail: `${mismatched} entries have wrong dimension (expected ${expected}): ${sorted.map(([d, c]) => `dim=${d}: ${c}`).join(", ")}`,
+    detail: `${mismatched} entries have wrong dimension (expected ${expected}): ${sorted.map(([d, c]) => `dim=${d}: ${c}`).join(", ")}${suffix}`,
   };
 }
 
@@ -77,7 +98,7 @@ function checkOrphanMemories(entries: MemoryEntry[]): CheckResult {
 function checkTierDistribution(entries: MemoryEntry[]): CheckResult {
   const tierCounts: Record<MemoryTier, number> = { core: 0, working: 0, peripheral: 0 };
   for (const e of entries) {
-    const tier = resolveTier(e.metadata);
+    const tier = resolveTier(e.metadata, e.importance);
     tierCounts[tier]++;
   }
 
@@ -216,15 +237,78 @@ function checkInterferenceDensity(entries: MemoryEntry[]): CheckResult {
 // Main
 // ---------------------------------------------------------------------------
 
+/** Check 8 (P0 B-1 观察): usage 四档分布 — injection-vs-use 影子统计的离线观察口。
+ *  纯报告,不接任何决策;cold = 被反复 surface(accessCount≥6)却从未被
+ *  reconstruction 引用,是第二阶段 decay 联动前要先观察校准的核心对象。 */
+function checkUsageDistribution(entries: MemoryEntry[]): CheckResult {
+  // use 信号未采集时(reconstruction flag 关),useCount 恒零 → "cold" 全是假阳性。
+  // 如实报告信号缺失,不输出不可解释的判定。
+  if (!isUsageSignalActive()) {
+    return {
+      name: "usage_distribution",
+      status: "ok",
+      detail: "use signal inactive (RECALLNEST_CONSTRUCTIVE_RETRIEVAL off) — useCount 无写入路径,cold/warm/hot 不可判,统计跳过。该 flag 因合成召回缺失被 Alice 主动关闭(2026-06-11),usage 线搁置中。",
+    };
+  }
+
+  const counts: Record<UsageStatus, number> = { unused: 0, cold: 0, warm: 0, hot: 0 };
+  const coldSamples: Array<{ id: string; injection: number; ageDays: number; scope: string }> = [];
+  const now = Date.now();
+
+  for (const e of entries) {
+    const status = deriveUsageStatus(e);
+    counts[status]++;
+    if (status === "cold") {
+      let injection = 0;
+      try {
+        const meta = JSON.parse(e.metadata || "{}") as Record<string, unknown>;
+        injection = typeof meta.accessCount === "number" ? meta.accessCount : 0;
+      } catch { /* keep 0 */ }
+      coldSamples.push({
+        id: e.id.slice(0, 8),
+        injection,
+        ageDays: Math.floor((now - e.timestamp) / 86_400_000),
+        scope: e.scope || "(none)",
+      });
+    }
+  }
+
+  const total = entries.length;
+  const coldPct = total > 0 ? (counts.cold / total) * 100 : 0;
+  const top = coldSamples
+    .sort((a, b) => b.injection - a.injection)
+    .slice(0, 20)
+    .map(s => `${s.id}(inj=${s.injection}, ${s.ageDays}d, ${s.scope})`)
+    .join(", ");
+
+  return {
+    name: "usage_distribution",
+    status: coldPct > 10 ? "warning" : "ok",
+    detail:
+      `unused=${counts.unused} cold=${counts.cold} (${coldPct.toFixed(1)}%) ` +
+      `warm=${counts.warm} hot=${counts.hot}` +
+      (coldSamples.length > 0 ? `; cold top-${Math.min(20, coldSamples.length)}: ${top}` : ""),
+  };
+}
+
 export interface CheckupDeps {
-  store: Pick<MemoryStore, "list" | "stats">;
+  store: Pick<MemoryStore, "list" | "stats" | "getVectors">;
   openConflictCount: number;
   /** Optional override path for source-heartbeat.json (used in tests). */
   heartbeatPath?: string;
 }
 
 export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport> {
-  const entries = await deps.store.list(undefined, undefined, 10000, 0);
+  const SCAN_LIMIT = 10000;
+  const listed = await deps.store.list(undefined, undefined, SCAN_LIMIT, 0);
+
+  // list() 为性能不返回向量(vector: []);维度/干扰检查靠向量,否则把"全 0 维"
+  // 误判成健康、干扰分析永远"样本不足"。补回真实向量再检查。
+  const vectorMap = await deps.store.getVectors(listed.map(e => e.id));
+  const entries = listed.map(e => ({ ...e, vector: vectorMap.get(e.id) ?? [] }));
+
+  // 截断披露:库总量 > 已扫,说明只体检了最近 SCAN_LIMIT 条。
+  const totalAvailable = (await deps.store.stats()).totalCount;
 
   return {
     checks: [
@@ -235,16 +319,21 @@ export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport>
       checkVersionGroups(entries),
       checkSourceHealth(deps.heartbeatPath),
       checkInterferenceDensity(entries),
+      checkUsageDistribution(entries),
     ],
     totalEntries: entries.length,
+    totalAvailable,
     timestamp: new Date().toISOString(),
   };
 }
 
 export function formatCheckupReport(report: CheckupReport): string {
+  const truncationNote = report.totalAvailable > report.totalEntries
+    ? ` (of ${report.totalAvailable} total — only the most recent ${report.totalEntries} analyzed)`
+    : "";
   const lines = [
     `Data Checkup Report (${report.timestamp})`,
-    `Total entries scanned: ${report.totalEntries}`,
+    `Total entries scanned: ${report.totalEntries}${truncationNote}`,
     "",
   ];