clawmem 0.5.1 → 0.7.0

package/src/hooks/context-surfacing.ts

@@ -30,6 +30,7 @@ import { enrichResults } from "../search-utils.ts";
 import { sanitizeSnippet } from "../promptguard.ts";
 import { shouldSkipRetrieval, isRetrievedNoise } from "../retrieval-gate.ts";
 import { MAX_QUERY_LENGTH } from "../limits.ts";
+import { writeRecallEvents, hashQuery } from "../recall-buffer.ts";
 
 // =============================================================================
 // Config
@@ -69,18 +70,44 @@ export async function contextSurfacing(
   input: HookInput
 ): Promise<HookOutput> {
   let prompt = input.prompt?.trim();
-  if (!prompt || prompt.length < MIN_PROMPT_LENGTH) return makeEmptyOutput("context-surfacing");
+
+  // Compute turn_index FIRST, before any early returns.
+  // Every transcript-visible early return must log an empty context_usage row
+  // to keep turn_index aligned with transcript turns for per-turn attribution.
+  if (input.sessionId) {
+    try {
+      let turnIndex = 0;
+      try {
+        const existing = store.db.prepare(
+          `SELECT COUNT(*) as cnt FROM context_usage WHERE session_id = ? AND hook_name = 'context-surfacing'`
+        ).get(input.sessionId) as { cnt: number };
+        turnIndex = existing.cnt;
+      } catch { /* fallback to 0 */ }
+      (input as any)._turnIndex = turnIndex;
+    } catch { /* non-fatal */ }
+  }
+
+  if (!prompt || prompt.length < MIN_PROMPT_LENGTH) {
+    logEmptyTurn(store, input);
+    return makeEmptyOutput("context-surfacing");
+  }
 
   // Bound query length to prevent DoS on search indices
   if (prompt.length > MAX_QUERY_LENGTH) prompt = prompt.slice(0, MAX_QUERY_LENGTH);
 
-  // Skip slash commands
-  if (prompt.startsWith("/")) return makeEmptyOutput("context-surfacing");
+  // Skip slash commands — log empty turn for alignment
+  if (prompt.startsWith("/")) {
+    logEmptyTurn(store, input);
+    return makeEmptyOutput("context-surfacing");
+  }
 
   // Adaptive retrieval gate: skip greetings, shell commands, affirmations, etc.
-  if (shouldSkipRetrieval(prompt)) return makeEmptyOutput("context-surfacing");
+  if (shouldSkipRetrieval(prompt)) {
+    logEmptyTurn(store, input);
+    return makeEmptyOutput("context-surfacing");
+  }
 
-  // Heartbeat / duplicate suppression (IO4)
+  // Heartbeat / duplicate suppression (IO4) — NOT transcript-visible user turns
   if (isHeartbeatPrompt(prompt)) return makeEmptyOutput("context-surfacing");
   if (wasPromptSeenRecently(store, "context-surfacing", prompt)) {
     return makeEmptyOutput("context-surfacing");
@@ -157,7 +184,7 @@ export async function contextSurfacing(
     }
   }
 
-  if (results.length === 0) return makeEmptyOutput("context-surfacing");
+  if (results.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
 
   // Budget-aware deep escalation (deep profile only):
   // If the fast path finished quickly and found results, spend remaining time budget
@@ -215,7 +242,7 @@ export async function contextSurfacing(
     !FILTERED_PATHS.some(p => r.displayPath.includes(p))
   );
 
-  if (results.length === 0) return makeEmptyOutput("context-surfacing");
+  if (results.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
 
   // Filter out snoozed documents
   const now = new Date();
@@ -231,7 +258,7 @@ export async function contextSurfacing(
     return true;
   });
 
-  if (results.length === 0) return makeEmptyOutput("context-surfacing");
+  if (results.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
 
   // Deduplicate by filepath (keep best score per path)
   const deduped = new Map<string, SearchResult>();
@@ -273,7 +300,7 @@ export async function contextSurfacing(
       : 0;
 
     // Activation floor: if even the best result is too weak, bail entirely
-    if (bestScore < profile.activationFloor) return makeEmptyOutput("context-surfacing");
+    if (bestScore < profile.activationFloor) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
 
     const adaptiveMin = Math.max(bestScore * profile.minScoreRatio, profile.absoluteFloor);
     scored = allScored.filter(r => r.compositeScore >= adaptiveMin);
@@ -282,7 +309,7 @@ export async function contextSurfacing(
     scored = allScored.filter(r => r.compositeScore >= minScore);
   }
 
-  if (scored.length === 0) return makeEmptyOutput("context-surfacing");
+  if (scored.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
 
   // Spreading activation (E11): boost results co-activated with top HOT results
   if (scored.length > 3) {
@@ -325,11 +352,62 @@ export async function contextSurfacing(
   // Build context within token budget (profile-driven)
   const { context, paths, tokens } = buildContext(scored, prompt, tokenBudget);
 
-  if (!context) return makeEmptyOutput("context-surfacing");
+  if (!context) {
+    logEmptyTurn(store, input);
+    return makeEmptyOutput("context-surfacing");
+  }
 
-  // Log the injection
+  // Use pre-computed turn_index from top of function
   if (input.sessionId) {
-    logInjection(store, input.sessionId, "context-surfacing", paths, tokens);
+    const turnIndex = (input as any)._turnIndex ?? 0;
+
+    // Log the injection — returns usage_id for recall event linkage
+    const usageId = logInjection(store, input.sessionId, "context-surfacing", paths, tokens, turnIndex);
+
+    // Record recall events ONLY for docs that made it into the injected context
+    // (post-budget). Docs trimmed by token budget were never seen by the model.
+    // Each event links to its context_usage row via usage_id + turn_index.
+    // Multi-vault: route docs to origin vault's store. Mirror context_usage there too.
+    try {
+      const qHash = hashQuery(prompt);
+      const injectedSet = new Set(paths);
+      const injectedScored = scored.filter(r => injectedSet.has(r.displayPath));
+
+      // Group by vault origin (undefined = general vault)
+      const byVault = new Map<string | undefined, typeof injectedScored>();
+      for (const r of injectedScored) {
+        const vault = (r as any)._fromVault as string | undefined;
+        let group = byVault.get(vault);
+        if (!group) { group = []; byVault.set(vault, group); }
+        group.push(r);
+      }
+
+      const validUsageId = usageId > 0 ? usageId : undefined;
+      for (const [vault, docs] of byVault) {
+        const mappedDocs = docs.map(r => ({ displayPath: r.displayPath, searchScore: r.compositeScore }));
+        if (!vault) {
+          writeRecallEvents(store, input.sessionId, qHash, mappedDocs, validUsageId, turnIndex);
+        } else {
+          try {
+            const vaultStore = resolveStore(vault);
+            // Mirror context_usage row into named vault for correct FK + attribution
+            const vaultPaths = docs.map(r => r.displayPath);
+            const vaultUsageId = vaultStore.insertUsage({
+              sessionId: input.sessionId,
+              timestamp: new Date().toISOString(),
+              hookName: "context-surfacing",
+              injectedPaths: vaultPaths,
+              estimatedTokens: 0,
+              wasReferenced: 0,
+              turnIndex,
+            });
+            writeRecallEvents(vaultStore, input.sessionId, qHash, mappedDocs, vaultUsageId > 0 ? vaultUsageId : undefined, turnIndex);
+          } catch { /* vault unavailable — skip */ }
+        }
+      }
+    } catch {
+      // Non-critical — don't block context surfacing on recall tracking errors
+    }
   }
 
   // Routing hint: detect query intent signals and prepend a tool routing directive
@@ -351,6 +429,19 @@ export async function contextSurfacing(
 // Helpers
 // =============================================================================
 
+/**
+ * Log an empty context_usage row for a skipped turn.
+ * Keeps turn_index aligned with transcript turns so per-turn recall
+ * attribution doesn't drift when some prompts are gated.
+ */
+function logEmptyTurn(store: Store, input: HookInput): void {
+  if (!input.sessionId) return;
+  try {
+    const turnIndex = (input as any)._turnIndex ?? 0;
+    logInjection(store, input.sessionId, "context-surfacing", [], 0, turnIndex);
+  } catch { /* non-fatal */ }
+}
+
 /**
  * Detect causal/temporal/discovery signals in the prompt and return a
  * routing hint that makes the correct tool choice salient at the moment

package/src/hooks/feedback-loop.ts

@@ -10,12 +10,18 @@
  */
 
 import type { Store } from "../store.ts";
+import { resolveStore } from "../store.ts";
+import { listVaults } from "../config.ts";
 import type { HookInput, HookOutput } from "../hooks.ts";
 import {
   makeEmptyOutput,
   readTranscript,
   validateTranscriptPath,
 } from "../hooks.ts";
+import {
+  segmentTranscriptIntoTurns,
+  attributeRecallReferences,
+} from "../recall-attribution.ts";
 
 // =============================================================================
 // Handler
@@ -129,6 +135,33 @@ export async function feedbackLoop(
     // Non-critical — don't block feedback loop on utility tracking errors
   }
 
+  // Recall tracking: per-turn attribution using transcript segmentation.
+  // Reads full transcript, segments into turns, zips with context_usage rows,
+  // checks references per-turn rather than session-globally.
+  try {
+    const allMessages = readTranscript(transcriptPath, 500);
+    const turns = segmentTranscriptIntoTurns(allMessages);
+    const usages = store.getUsageForSession(sessionId);
+
+    // General vault attribution
+    attributeRecallReferences(store, sessionId, usages, turns);
+
+    // Cross-vault: attribute recall events in any configured named vaults.
+    // Each vault has its own context_usage rows (mirrored during context-surfacing).
+    const vaultNames = listVaults();
+    for (const vaultName of vaultNames) {
+      try {
+        const vaultStore = resolveStore(vaultName);
+        const vaultUsages = vaultStore.getUsageForSession(sessionId);
+        if (vaultUsages.length > 0) {
+          attributeRecallReferences(vaultStore, sessionId, vaultUsages, turns);
+        }
+      } catch { /* vault unavailable — skip */ }
+    }
+  } catch {
+    // Non-critical — don't block feedback loop on recall tracking errors
+  }
+
   // Silent return — feedback loop doesn't inject context
   return makeEmptyOutput("feedback-loop");
 }
@@ -195,6 +228,13 @@ function trackUtilitySignals(
 // Reference Detection
 // =============================================================================
 
+// Recall attribution logic is in src/recall-attribution.ts
+// (attributeRecallReferences, segmentTranscriptIntoTurns)
+
+// =============================================================================
+// Reference Detection
+// =============================================================================
+
 function checkTitleReference(store: Store, path: string, text: string): boolean {
   try {
     const parts = path.split("/");

package/src/hooks/session-bootstrap.ts

@@ -260,10 +260,11 @@ function getCurrentFocus(
   cutoff.setDate(cutoff.getDate() - DECISION_LOOKBACK_DAYS);
   const cutoffStr = cutoff.toISOString();
 
-  // Gather recent decisions, preferences, and active problems
+  // Gather recent decisions, preferences, active problems, and deductive insights
   const decisions = store.getDocumentsByType("decision", 10);
   const preferences = store.getDocumentsByType("preference", 5);
   const problems = store.getDocumentsByType("problem", 5);
+  const deductions = store.getDocumentsByType("deductive", 5);
 
   // Rank by: pinned first, then recency, then access_count
   const now = Date.now();
@@ -285,7 +286,11 @@ function getCurrentFocus(
   // Preferences are durable — no date filter, just rank
   const rankedPrefs = [...preferences].sort((a, b) => rankDoc(b) - rankDoc(a));
 
-  if (recentDecisions.length === 0 && rankedPrefs.length === 0 && activeProblems.length === 0) {
+  const recentDeductions = deductions
+    .filter(d => d.modifiedAt >= cutoffStr)
+    .sort((a, b) => rankDoc(b) - rankDoc(a));
+
+  if (recentDecisions.length === 0 && rankedPrefs.length === 0 && activeProblems.length === 0 && recentDeductions.length === 0) {
     return null;
   }
 
@@ -338,6 +343,19 @@ function getCurrentFocus(
     }
   }
 
+  // Cross-session deductions (derived insights with source provenance)
+  if (recentDeductions.length > 0) {
+    lines.push("**Derived Insights:**");
+    charCount += 24;
+    for (const d of recentDeductions) {
+      if (charCount >= maxChars) break;
+      const entry = `- ${d.title} (${d.modifiedAt.slice(0, 10)})`;
+      lines.push(entry);
+      paths.push(`${d.collection}/${d.path}`);
+      charCount += entry.length + 2;
+    }
+  }
+
   return lines.length > 1 ? { text: lines.join("\n"), paths } : null;
 }
 

package/src/hooks.ts

@@ -385,23 +385,28 @@ export function logInjection(
   sessionId: string,
   hookName: string,
   injectedPaths: string[],
-  estimatedTokens: number
-): void {
+  estimatedTokens: number,
+  turnIndex?: number
+): number {
   try {
-    store.insertUsage({
+    const usageId = store.insertUsage({
       sessionId,
       timestamp: new Date().toISOString(),
       hookName,
       injectedPaths,
       estimatedTokens,
       wasReferenced: 0,
+      turnIndex,
     });
 
     // Record co-activation for all injected paths (E3)
     if (injectedPaths.length >= 2) {
       store.recordCoActivation(injectedPaths);
     }
+
+    return usageId;
   } catch {
     // Non-fatal: don't crash hook if usage logging fails
+    return -1;
   }
 }

package/src/mcp.ts

@@ -2277,6 +2277,11 @@ This is the recommended entry point for ALL memory queries.`,
       const config = loadConfig();
       const policy = config.lifecycle;
 
+      // Recall tracking summary
+      const recallStats = store.getRecallStatsAll(1);
+      const highDiversity = recallStats.filter(r => r.diversityScore >= 0.4 && r.spacingScore >= 0.5 && r.recallCount >= 3);
+      const highNoise = recallStats.filter(r => r.recallCount >= 5 && r.negativeCount > r.recallCount * 0.8);
+
       const lines = [
         `Active: ${stats.active}`,
         `Archived (auto): ${stats.archived}`,
@@ -2286,6 +2291,10 @@ This is the recommended entry point for ALL memory queries.`,
         `Never accessed: ${stats.neverAccessed}`,
         `Oldest access: ${stats.oldestAccess?.slice(0, 10) || "n/a"}`,
         "",
+        `Recall tracking: ${recallStats.length} docs tracked`,
+        `  Pin candidates (high diversity+spacing): ${highDiversity.length}`,
+        `  Snooze candidates (surfaced often, rarely referenced): ${highNoise.length}`,
+        "",
         `Policy: ${policy ? `archive after ${policy.archive_after_days}d, purge after ${policy.purge_after_days ?? "never"}, dry_run=${policy.dry_run}` : "none configured"}`,
       ];
 
@@ -2322,7 +2331,29 @@ This is the recommended entry point for ALL memory queries.`,
         const lines = candidates.map(c =>
           `- ${c.collection}/${c.path} (${c.content_type}, modified ${c.modified_at.slice(0, 10)}, accessed ${c.last_accessed_at?.slice(0, 10) || "never"})`
         );
-        return { content: [{ type: "text", text: `Would archive ${candidates.length} document(s):\n${lines.join("\n") || "(none)"}` }] };
+
+        // Recall-based recommendations
+        const recallStats = store.getRecallStatsAll(3);
+        const pinCandidates = recallStats.filter(r => r.diversityScore >= 0.4 && r.spacingScore >= 0.5 && r.recallCount >= 3);
+        const snoozeCandidates = recallStats.filter(r => r.recallCount >= 5 && r.negativeCount > r.recallCount * 0.8);
+
+        const recallLines: string[] = [];
+        if (pinCandidates.length > 0) {
+          recallLines.push("", "Pin candidates (high diversity, multi-day spread, recall≥3):");
+          for (const r of pinCandidates.slice(0, 5)) {
+            const label = r.collection && r.path ? `${r.collection}/${r.path}` : `doc#${r.docId}`;
+            recallLines.push(`  - ${label} (recalls=${r.recallCount}, queries=${r.uniqueQueries}, days=${r.recallDays}, diversity=${r.diversityScore.toFixed(2)}, spacing=${r.spacingScore.toFixed(2)})`);
+          }
+        }
+        if (snoozeCandidates.length > 0) {
+          recallLines.push("", "Snooze candidates (surfaced often, rarely referenced):");
+          for (const r of snoozeCandidates.slice(0, 5)) {
+            const label = r.collection && r.path ? `${r.collection}/${r.path}` : `doc#${r.docId}`;
+            recallLines.push(`  - ${label} (recalls=${r.recallCount}, referenced=${r.recallCount - r.negativeCount}, noise_ratio=${(r.negativeCount / r.recallCount * 100).toFixed(0)}%)`);
+          }
+        }
+
+        return { content: [{ type: "text", text: `Would archive ${candidates.length} document(s):\n${lines.join("\n") || "(none)"}${recallLines.join("\n")}` }] };
       }
 
       const archived = store.archiveDocuments(candidates.map(c => c.id));

package/src/memory.ts

@@ -20,6 +20,7 @@ export const HALF_LIVES: Record<string, number> = {
   project: 120,
   preference: Infinity,
   decision: Infinity,
+  deductive: Infinity,
   hub: Infinity,
 };
 
@@ -29,6 +30,7 @@ export const HALF_LIVES: Record<string, number> = {
 
 export const TYPE_BASELINES: Record<string, number> = {
   decision: 0.85,
+  deductive: 0.85,
   preference: 0.80,
   hub: 0.80,
   problem: 0.75,
@@ -45,7 +47,7 @@ export const TYPE_BASELINES: Record<string, number> = {
 // Content Type Inference
 // =============================================================================
 
-export type ContentType = "decision" | "preference" | "hub" | "research" | "project" | "handoff" | "conversation" | "progress" | "milestone" | "problem" | "note";
+export type ContentType = "decision" | "deductive" | "preference" | "hub" | "research" | "project" | "handoff" | "conversation" | "progress" | "milestone" | "problem" | "note";
 
 export function inferContentType(path: string, explicitType?: string): ContentType {
   if (explicitType && explicitType in TYPE_BASELINES) return explicitType as ContentType;
@@ -75,7 +77,7 @@ export type MemoryType = "episodic" | "semantic" | "procedural";
  */
 export function inferMemoryType(path: string, contentType: string, body?: string): MemoryType {
   if (["handoff", "progress", "conversation"].includes(contentType)) return "episodic";
-  if (["decision", "hub", "research"].includes(contentType)) return "semantic";
+  if (["decision", "deductive", "hub", "research"].includes(contentType)) return "semantic";
   if (body && /\b(step\s+\d|workflow|recipe|how\s+to|procedure|runbook|playbook)\b/i.test(body)) return "procedural";
   if (path.includes("sop") || path.includes("runbook") || path.includes("playbook")) return "procedural";
   if (contentType === "antipattern") return "semantic";
@@ -150,7 +152,7 @@ export function confidenceScore(
   // Attention decay: reduce confidence if not accessed recently (5% per week)
   // Only apply to episodic/progress content — skip for durable types (decision, hub, research)
   // Also skip if last_accessed_at was backfilled from modified_at (no real access yet)
-  const DECAY_EXEMPT_TYPES = new Set(["decision", "hub", "research", "antipattern", "preference"]);
+  const DECAY_EXEMPT_TYPES = new Set(["decision", "deductive", "hub", "research", "antipattern", "preference"]);
   let attentionDecay = 1.0;
   if (lastAccessedAt && !DECAY_EXEMPT_TYPES.has(contentType)) {
     const lastAccess = typeof lastAccessedAt === "string" ? new Date(lastAccessedAt) : lastAccessedAt;

package/src/recall-attribution.ts

@@ -0,0 +1,182 @@
+/**
+ * Recall Attribution — per-turn reference detection for recall tracking.
+ *
+ * Extracted into a standalone module for testability (per GPT 5.4 High review turn 4).
+ *
+ * Architecture:
+ * 1. Segment the transcript into ordered turns (user → assistant pairs)
+ * 2. Zip context_usage rows (by turn_index) with transcript turns (by position)
+ * 3. For each pair, detect references in that turn's assistant text only
+ * 4. Mark recall_events linked to the usage rows whose turn actually cited the doc
+ */
+
+import type { Store, UsageRow } from "./store.ts";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type TranscriptTurn = {
+  userText: string;
+  assistantText: string;
+};
+
+// =============================================================================
+// Transcript Segmentation
+// =============================================================================
+
+/**
+ * Segment a flat message array into ordered turns.
+ * A turn starts on each "user" message and includes all following "assistant"
+ * messages until the next "user" message.
+ *
+ * @param messages - Ordered array of {role, content} from transcript JSONL
+ * @returns Ordered array of turns
+ */
+export function segmentTranscriptIntoTurns(
+  messages: { role: string; content: string }[]
+): TranscriptTurn[] {
+  const turns: TranscriptTurn[] = [];
+  let currentUser = "";
+  let currentAssistant = "";
+
+  for (const msg of messages) {
+    if (msg.role === "user") {
+      // New turn: flush previous if it has assistant content
+      if (currentUser || currentAssistant) {
+        turns.push({ userText: currentUser, assistantText: currentAssistant });
+      }
+      currentUser = msg.content;
+      currentAssistant = "";
+    } else if (msg.role === "assistant") {
+      currentAssistant += (currentAssistant ? "\n" : "") + msg.content;
+    }
+    // Ignore system/tool messages for attribution purposes
+  }
+
+  // Flush final turn
+  if (currentUser || currentAssistant) {
+    turns.push({ userText: currentUser, assistantText: currentAssistant });
+  }
+
+  return turns;
+}
+
+// =============================================================================
+// Per-Turn Reference Detection
+// =============================================================================
+
+/**
+ * Check if a displayPath (collection/path) is referenced in text.
+ * Matches by: full path, filename (without extension), or doc title.
+ */
+function isPathReferenced(
+  store: Store,
+  displayPath: string,
+  text: string
+): boolean {
+  if (!text || !displayPath) return false;
+
+  // Full path match
+  if (text.includes(displayPath)) return true;
+
+  // Filename match (without extension, min 4 chars)
+  const filename = displayPath.split("/").pop()?.replace(/\.(md|txt)$/i, "");
+  if (filename && filename.length > 3 && text.toLowerCase().includes(filename.toLowerCase())) {
+    return true;
+  }
+
+  // Title match from DB
+  const parts = displayPath.split("/");
+  if (parts.length >= 2) {
+    const collection = parts[0]!;
+    const docPath = parts.slice(1).join("/");
+    const doc = store.findActiveDocument(collection, docPath);
+    if (doc?.title && doc.title.length >= 5 && text.toLowerCase().includes(doc.title.toLowerCase())) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+// =============================================================================
+// Attribution Core
+// =============================================================================
+
+/**
+ * Attribute recall events to specific turns using per-turn reference detection.
+ *
+ * For each context_usage row (ordered by turn_index), finds the corresponding
+ * transcript turn and checks which of that turn's injected docs were cited in
+ * that turn's assistant text. Only marks recall_events linked to turns where
+ * the doc was actually referenced.
+ *
+ * @param store - Store instance for doc resolution and event marking
+ * @param sessionId - Session identifier
+ * @param usages - context_usage rows for this session, ordered by turn_index
+ * @param turns - Transcript turns, ordered by position
+ */
+export function attributeRecallReferences(
+  store: Store,
+  sessionId: string,
+  usages: UsageRow[],
+  turns: TranscriptTurn[]
+): void {
+  // Filter to context-surfacing usages only
+  const surfacingUsages = usages.filter(u => u.hookName === "context-surfacing");
+
+  for (const usage of surfacingUsages) {
+    // Match usage to transcript turn by turn_index
+    const turn = turns[usage.turnIndex];
+    if (!turn || !turn.assistantText) continue;
+
+    // Parse injected paths for this turn
+    let injectedPaths: string[];
+    try { injectedPaths = JSON.parse(usage.injectedPaths) as string[]; }
+    catch { continue; }
+    if (injectedPaths.length === 0) continue;
+
+    // Check which docs from THIS turn were referenced in THIS turn's assistant text
+    const referencedDocIds: number[] = [];
+    for (const path of injectedPaths) {
+      if (!isPathReferenced(store, path, turn.assistantText)) continue;
+
+      const parts = path.split("/");
+      if (parts.length < 2) continue;
+      const collection = parts[0]!;
+      const docPath = parts.slice(1).join("/");
+      const doc = store.findActiveDocument(collection, docPath);
+      if (doc) referencedDocIds.push(doc.id);
+    }
+
+    if (referencedDocIds.length === 0) continue;
+
+    // Mark only recall events linked to THIS usage row
+    for (const docId of referencedDocIds) {
+      // Primary: usage_id-linked events (current schema)
+      const linked = store.db.prepare(`
+        SELECT id FROM recall_events
+        WHERE usage_id = ? AND doc_id = ? AND was_referenced = 0
+      `).all(usage.id, docId) as { id: number }[];
+
+      if (linked.length > 0) {
+        const ids = linked.map(r => r.id);
+        const placeholders = ids.map(() => "?").join(",");
+        store.db.prepare(`
+          UPDATE recall_events SET was_referenced = 1
+          WHERE id IN (${placeholders})
+        `).run(...ids);
+      } else {
+        // Fallback: pre-migration events without usage_id — match by turn_index
+        store.db.prepare(`
+          UPDATE recall_events SET was_referenced = 1
+          WHERE id IN (
+            SELECT id FROM recall_events
+            WHERE session_id = ? AND doc_id = ? AND turn_index = ? AND was_referenced = 0
+          )
+        `).run(sessionId, docId, usage.turnIndex);
+      }
+    }
+  }
+}