recallnest 3.0.0 → 4.0.0

package/src/conflict-engine.ts

@@ -8,9 +8,14 @@ import {
   normalizeCanonicalKey,
   parseMetadataObject,
 } from "./memory-boundaries.js";
-import type { MemoryStore } from "./store.js";
-import { archiveBeliefVersion, buildSupersedingBeliefMetadata } from "./belief-history.js";
-import { parseEvolution } from "./memory-evolution.js";
+import type { MemoryEntry, MemoryStore } from "./store.js";
+import {
+  archiveBeliefVersion,
+  BeliefTargetMissingError,
+  buildSupersedingBeliefMetadata,
+  replaceBeliefVersion,
+} from "./belief-history.js";
+import { parseEvolution, type EvolutionMetadata } from "./memory-evolution.js";
 import {
   type ConflictCandidateInput,
   ConflictCandidateInputSchema,
@@ -98,7 +103,8 @@ function buildMergedConflictMetadata(
 
 export interface ResolveConflictDeps {
   // `store`/`upsert` are needed to archive the belief being replaced before overwriting it.
-  store: Pick<MemoryStore, "getById" | "update" | "store"> & Partial<Pick<MemoryStore, "upsert">>;
+  // replaceWithArchivedVersion (real MemoryStore) archives and overwrites under one store-write lock.
+  store: Pick<MemoryStore, "getById" | "update" | "store"> & Partial<Pick<MemoryStore, "upsert" | "replaceWithArchivedVersion">>;
   embedder: Pick<Embedder, "embedPassage">;
   conflictStore: Pick<ConflictCandidateStore, "getById" | "replace">;
 }
@@ -151,28 +157,50 @@ export async function resolveConflictCandidate(
     // Conflict resolution is the most deliberate belief change there is — accepting the
     // incoming version or merging both used to overwrite the existing row in place, losing
     // precisely the "before" side of the decision. Archive it first.
-    const resolvedAtMs = Date.now();
-    const previousEvo = parseEvolution(existing.metadata, existing.timestamp);
-    const { historyId } = await archiveBeliefVersion(
-      { store: deps.store, embedder: deps.embedder },
-      existing,
-      { now: resolvedAtMs },
-    );
-
-    const updated = await deps.store.update(existing.id, {
+    //
+    // With a full MemoryStore the archive and the overwrite share one store-write lock and the
+    // row is re-read inside it (2026-10-17): if it was deleted after the lookup above, nothing
+    // is written and this throws BeliefTargetMissingError — previously the history row was
+    // already committed when update() came back empty.
+    const resolution = input.resolution;
+    const buildUpdates = (current: MemoryEntry, previousEvo: EvolutionMetadata, historyId: string, resolvedAtMs: number) => ({
       text: nextText,
       vector,
-      importance: nextImportance,
+      importance: resolution === "merge" ? Math.max(current.importance, record.incoming.importance) : nextImportance,
       category: nextCategory,
       metadata: buildSupersedingBeliefMetadata(
         nextMetadata,
         previousEvo,
         historyId,
         resolvedAtMs,
-        `conflict:${input.resolution}`,
+        `conflict:${resolution}`,
       ),
       timestamp: resolvedAtMs,
     });
+
+    let updated: MemoryEntry | null;
+    const replace = deps.store.replaceWithArchivedVersion;
+    if (replace) {
+      const result = await replaceBeliefVersion(
+        {
+          store: { replaceWithArchivedVersion: replace.bind(deps.store), getById: deps.store.getById.bind(deps.store) },
+          embedder: deps.embedder,
+        },
+        existing,
+        ({ current, previousEvolution, historyId, now }) => buildUpdates(current, previousEvolution, historyId, now),
+      );
+      if (result.status !== "replaced") throw new BeliefTargetMissingError(existing.id);
+      updated = result.entry;
+    } else {
+      const resolvedAtMs = Date.now();
+      const previousEvo = parseEvolution(existing.metadata, existing.timestamp);
+      const { historyId } = await archiveBeliefVersion(
+        { store: deps.store, embedder: deps.embedder },
+        existing,
+        { now: resolvedAtMs },
+      );
+      updated = await deps.store.update(existing.id, buildUpdates(existing, previousEvo, historyId, resolvedAtMs));
+    }
     if (!updated) {
       throw new Error(`Failed to update durable memory ${existing.id}`);
     }

package/src/consolidation-engine.ts

@@ -2,7 +2,9 @@
  * Semantic Consolidation Engine
  *
  * Borrowed from UltraMemory's consolidation-engine.ts, adapted for RecallNest:
- * - Uses RecallNest's store.vectorSearch() + store.update() (no patchMetadata)
+ * - Uses RecallNest's store.vectorSearch(); metadata writes go through store.patchMetadataBatch()
+ *   (read inside the store-write lock, rows that no longer exist are skipped — never re-inserted).
+ *   This line used to say "store.update() (no patchMetadata)"; that stopped being true on 2026-08-14.
  * - Integrates with RecallNest's existing conflict-engine for conflict creation
  * - Uses RecallNest's metadata structure (boundary.layer, canonicalKey, etc.)
  *
@@ -882,10 +884,20 @@ export interface SynthesisUptakeStats {
   scanned: number;
   /** Derived insights found (cluster_insight / cross_memory_pattern). */
   derivedTotal: number;
-  /** Derived insights with accessCount > 0 — actually read after synthesis. */
+  /** Derived insights with accessCount > 0 — touched by at least one retrieval.
+   *  ⚠️ Inflatable: the MCP search path does not pass `source`, so every search hit
+   *  increments accessCount (retriever.ts reinforcement gate is `source !== "auto-recall"`).
+   *  One person running ~300 queries can move this from 3.7% to 7%+ with the store unchanged
+   *  (2026-08-22 measured: a single 16-query audit moved it 177→186/4749). */
   derivedRead: number;
-  /** derivedRead / derivedTotal; null when no derived insights exist. */
+  /** derivedRead / derivedTotal; null when no derived insights exist. Read as "touched", not "useful". */
   uptakeRate: number | null;
+  /** Derived insights read by ≥2 distinct readers (metadata.distinctReaderCount, maintained by
+   *  access-tracker with reader-id dedup + novelty gating). A single reader's repeated searches
+   *  cannot push an entry past 1, so this is the harder-to-inflate uptake signal. */
+  derivedReadByMultiple: number;
+  /** derivedReadByMultiple / derivedTotal; null when no derived insights exist. */
+  multiReaderRate: number | null;
   /** True when the scan hit the cap before exhausting the store. */
   truncated: boolean;
 }
@@ -894,6 +906,11 @@ export interface SynthesisUptakeStats {
  * Measure how many consolidation/dream products were ever read back.
  * 把"升华产物没人用"从体感变成能报警的数字——uptake 长期为 0 说明
  * 升华管线在产出无人消费的内容（或读打点断链）。
+ *
+ * 两个口径（2026-09-09 加第二个，open-loops「召回可达性抽测」③）：
+ * - uptakeRate：accessCount>0。**只增不减、可被检索廉价刷高**（见字段注释），
+ *   只能读成「被碰过」，不能当「合成产物有用/没用」的证据。保留它是为了历史可比。
+ * - multiReaderRate：distinctReaderCount≥2。一个人反复搜刷不高，是更难被扰动的口径。
  */
 export async function computeSynthesisUptake(
   store: { listPage(opts: { limit?: number; offset?: number; includeVector?: boolean }): Promise<MemoryEntry[]> },
@@ -905,6 +922,7 @@ export async function computeSynthesisUptake(
   let scanned = 0;
   let derivedTotal = 0;
   let derivedRead = 0;
+  let derivedReadByMultiple = 0;
   let offset = 0;
   let truncated = false;
 
@@ -918,6 +936,7 @@ export async function computeSynthesisUptake(
       try {
         const meta = JSON.parse(e.metadata || "{}") as Record<string, unknown>;
         if (typeof meta.accessCount === "number" && meta.accessCount > 0) derivedRead++;
+        if (typeof meta.distinctReaderCount === "number" && meta.distinctReaderCount >= 2) derivedReadByMultiple++;
       } catch { /* broken metadata → counts as unread */ }
     }
     offset += page.length;
@@ -933,6 +952,8 @@ export async function computeSynthesisUptake(
     derivedTotal,
     derivedRead,
     uptakeRate: derivedTotal > 0 ? derivedRead / derivedTotal : null,
+    derivedReadByMultiple,
+    multiReaderRate: derivedTotal > 0 ? derivedReadByMultiple / derivedTotal : null,
     truncated,
   };
 }

package/src/context-collapse-renderer.ts

@@ -11,6 +11,8 @@
  * Reuses existing L0/L1/L2 text stored in metadata by the multi-vector pipeline.
  */
 
+import { fullTextScoreThreshold } from "./env-config.js";
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -137,7 +139,12 @@ export function collapseResults(
   items: CollapseInput[],
   config?: Partial<CollapseConfig>,
 ): CollapseOutput[] {
-  const cfg: CollapseConfig = { ...DEFAULT_COLLAPSE_CONFIG, ...config };
+  // L2 的默认线跟着流行度模式走（legacy 0.85、bounded 0.80，每次调用现读）；调用方显式传的 thresholds 原样用。
+  const defaults: CollapseConfig = {
+    ...DEFAULT_COLLAPSE_CONFIG,
+    thresholds: { ...DEFAULT_COLLAPSE_CONFIG.thresholds, l2: fullTextScoreThreshold() },
+  };
+  const cfg: CollapseConfig = { ...defaults, ...config };
   const { thresholds, tokenBudget, stalenessThresholdDays } = cfg;
 
   // Sort by score descending (highest relevance first)

package/src/context-composer-stable.ts

@@ -1,6 +1,7 @@
 import type { PinAsset } from "./memory-assets.js";
 import type { RetrievalResult } from "./retriever.js";
 import type { SessionCheckpointRecord } from "./session-schema.js";
+import { isFallbackSummary } from "./session-engine.js";
 import { selectPinnedContext } from "./context-composer-pins.js";
 import { cleanText, dedupeText } from "./context-composer-text.js";
 import { selectStableResults } from "./context-composer-stable-selection.js";
@@ -74,7 +75,10 @@ function buildCheckpointStableContext(
   if (!checkpoint) return [];
 
   const items = [
-    checkpoint.summary ? `Checkpoint summary: ${checkpoint.summary}` : "",
+    // 兜底文案不占 slot：它零信息，占着会把真正有内容的 decision / next 挤出 limit。
+    checkpoint.summary && !isFallbackSummary(checkpoint.summary)
+      ? `Checkpoint summary: ${checkpoint.summary}`
+      : "",
     checkpoint.task ? `Checkpoint focus: ${checkpoint.task}` : "",
     checkpoint.decisions[0] ? `Checkpoint decision: ${checkpoint.decisions[0]}` : "",
     checkpoint.nextActions[0] ? `Checkpoint next: ${checkpoint.nextActions[0]}` : "",

package/src/context-composer.ts

@@ -1,4 +1,5 @@
 import { listPinAssets, type PinAsset } from "./memory-assets.js";
+import { CHECKPOINT_MIRROR_SCOPE } from "./memory-boundaries.js";
 import * as envConfig from "./env-config.js";
 import { buildStableContextSections } from "./context-composer-stable.js";
 import {
@@ -15,7 +16,7 @@ import {
 } from "./context-composer-task-results.js";
 import type { RetrievalContext, RetrievalResult } from "./retriever.js";
 import type { EssentialContext, ResumeContextResponse, SessionCheckpointRecord } from "./session-schema.js";
-import { ResumeContextRequestSchema, ResumeContextResponseSchema } from "./session-schema.js";
+import { COLLAPSED_ITEMS_MAX, ResumeContextRequestSchema, ResumeContextResponseSchema } from "./session-schema.js";
 import { formatCheckpointRecallSummary } from "./session-output.js";
 import {
   STRONG_WORKFLOW_CUE_TERMS,
@@ -59,6 +60,9 @@ async function retrieveCandidates(
   },
 ): Promise<RetrievalResult[]> {
   const { category, query, limit, scope } = params;
+  // Checkpoint mirror rows are for search_memory; resume_context already reads this session's own
+  // checkpoint from the checkpoint store, and its stable / task sections stay as they were.
+  const excludeScopes = [CHECKPOINT_MIRROR_SCOPE];
 
   if (!scope) {
     return retriever.retrieve({
@@ -66,6 +70,7 @@ async function retrieveCandidates(
       limit,
       ...(category ? { category } : {}),
       source: "auto-recall",
+      excludeScopes,
     });
   }
 
@@ -76,12 +81,14 @@ async function retrieveCandidates(
       ...(category ? { category } : {}),
       scopeFilter: [scope],
       source: "auto-recall",
+      excludeScopes,
     }),
     retriever.retrieve({
       query,
       limit: Math.min(10, limit * 2),
       ...(category ? { category } : {}),
       source: "auto-recall",
+      excludeScopes,
     }),
   ]);
 
@@ -454,8 +461,10 @@ export async function composeResumeContext(
     score: r.score,
     timestamp: r.entry.timestamp,
   }));
+  // collapseResults 按分数从高到低输出；五个分区（加补充查询）去重后可能超过 20 条，
+  // 超出部分截掉，否则整个 resume_context 被 schema 的上限拒掉（2026-09-24 limitPerSection=4 实测）
   const collapsedItems = collapseInput.length > 0
-    ? collapseResults(collapseInput)
+    ? collapseResults(collapseInput).slice(0, COLLAPSED_ITEMS_MAX)
     : undefined;
 
   // CC-8: Build essential context from pinned memories, top patterns, and open loops.