@cleocode/core 2026.4.31 → 2026.4.36

package/src/memory/brain-retrieval.ts

@@ -23,6 +23,8 @@ import { getBrainAccessor } from '../store/brain-accessor.js';
 import type {
   BRAIN_OBSERVATION_SOURCE_TYPES,
   BRAIN_OBSERVATION_TYPES,
+  BrainMemoryTier,
+  BrainSourceConfidence,
 } from '../store/brain-schema.js';
 import { sessionExistsInTasksDb } from '../store/cross-db-cleanup.js';
 import { getDb } from '../store/sqlite.js';
@@ -34,7 +36,8 @@ import type {
   BrainNarrativeRow,
   BrainTimelineNeighborRow,
 } from './brain-row-types.js';
-import { searchBrain } from './brain-search.js';
+import { hybridSearch, searchBrain } from './brain-search.js';
+import { searchSimilar } from './brain-similarity.js';
 import { addGraphEdge, upsertGraphNode } from './graph-auto-populate.js';
 import { computeObservationQuality } from './quality-scoring.js';
 
@@ -62,6 +65,12 @@ export interface SearchBrainCompactParams {
   dateEnd?: string;
   /** T418: filter results to observations produced by a specific agent (Wave 8 mental models). */
   agent?: string;
+  /**
+   * When true (default), use Reciprocal Rank Fusion to combine FTS5 and
+   * vector search results for higher recall and better ranking.
+   * When false, fall back to FTS5-only search (faster, no embeddings needed).
+   */
+  useRRF?: boolean;
 }
 
 /** Result from searchBrainCompact. */
@@ -127,6 +136,14 @@ export interface ObserveBrainParams {
   sourceType?: BrainObservationSourceType;
   /** T417: agent provenance — the name of the spawned agent producing this observation. */
   agent?: string;
+  /**
+   * T549 Wave 1-A: source reliability level.
+   * Overrides the default routing. If omitted, routing is determined automatically:
+   * - sourceType 'manual' → 'owner'
+   * - sourceType 'session-debrief' → 'task-outcome'
+   * - otherwise → 'agent'
+   */
+  sourceConfidence?: BrainSourceConfidence;
 }
 
 /** Result from observeBrain. */
@@ -155,20 +172,109 @@ export async function searchBrainCompact(
   projectRoot: string,
   params: SearchBrainCompactParams,
 ): Promise<SearchBrainCompactResult> {
-  const { query, limit, tables, dateStart, dateEnd, agent } = params;
+  const { query, limit, tables, dateStart, dateEnd, agent, useRRF = true } = params;
 
   if (!query?.trim()) {
     return { results: [], total: 0, tokensEstimated: 0 };
   }
 
-  // T418: when agent filter is set, restrict search to observations table only
-  const effectiveTables =
-    agent !== undefined && agent !== null
-      ? (['observations'] as Array<'decisions' | 'patterns' | 'learnings' | 'observations'>)
-      : tables;
+  const effectiveLimit = limit ?? 10;
+
+  // T418: agent filter always forces FTS-only on observations table
+  const agentFilter = agent !== undefined && agent !== null;
+
+  // ----- RRF path (default) -----
+  if (useRRF && !agentFilter) {
+    // Run FTS (for dates + table-level data) and RRF fusion in parallel.
+    // FTS gives us row-level dates; RRF gives us the fused ranking order.
+    const [ftsResult, rrfResults] = await Promise.all([
+      searchBrain(projectRoot, query, { limit: effectiveLimit * 3, tables }).catch(() => ({
+        decisions: [],
+        patterns: [],
+        learnings: [],
+        observations: [],
+      })),
+      hybridSearch(query, projectRoot, { limit: effectiveLimit * 2 }),
+    ]);
+
+    // Build a date map from FTS rows (id -> date string)
+    const dateMap = new Map<string, string>();
+    for (const d of ftsResult.decisions) {
+      const raw = d as Record<string, unknown>;
+      dateMap.set(d.id, (d.createdAt ?? (raw['created_at'] as string)) || '');
+    }
+    for (const p of ftsResult.patterns) {
+      const raw = p as Record<string, unknown>;
+      dateMap.set(p.id, (p.extractedAt ?? (raw['extracted_at'] as string)) || '');
+    }
+    for (const l of ftsResult.learnings) {
+      const raw = l as Record<string, unknown>;
+      dateMap.set(l.id, (l.createdAt ?? (raw['created_at'] as string)) || '');
+    }
+    for (const o of ftsResult.observations) {
+      const raw = o as Record<string, unknown>;
+      dateMap.set(o.id, (o.createdAt ?? (raw['created_at'] as string)) || '');
+    }
+
+    // Apply table filter when specified (map singular type names to plural table names)
+    const singularToTable: Record<string, string> = {
+      decision: 'decisions',
+      pattern: 'patterns',
+      learning: 'learnings',
+      observation: 'observations',
+    };
+
+    let results: BrainCompactHit[] = rrfResults
+      .map((r) => ({
+        id: r.id,
+        type: r.type as 'decision' | 'pattern' | 'learning' | 'observation',
+        title: r.title.slice(0, 80),
+        date: dateMap.get(r.id) ?? '',
+        relevance: r.score,
+      }))
+      .filter((r) => {
+        // Only include items that the FTS scan returned (ensures quality gating is respected)
+        return dateMap.has(r.id);
+      });
+
+    if (tables && tables.length > 0) {
+      results = results.filter((r) =>
+        tables.includes(
+          singularToTable[r.type] as 'decisions' | 'patterns' | 'learnings' | 'observations',
+        ),
+      );
+    }
+
+    // Apply date filters client-side
+    if (dateStart) results = results.filter((r) => !r.date || r.date >= dateStart);
+    if (dateEnd) results = results.filter((r) => !r.date || r.date <= dateEnd);
+
+    results = results.slice(0, effectiveLimit);
+
+    for (const hit of results) {
+      hit._next = memoryFindHitNext(hit.id);
+    }
+
+    if (results.length > 0) {
+      const returnedIds = results.map((r) => r.id);
+      setImmediate(() => {
+        incrementCitationCounts(projectRoot, returnedIds).catch(() => {});
+        logRetrieval(projectRoot, query, returnedIds, 'find-rrf', results.length * 50).catch(
+          () => {},
+        );
+      });
+    }
+
+    return { results, total: results.length, tokensEstimated: results.length * 50 };
+  }
+
+  // ----- FTS-only path (useRRF=false or agent filter) -----
+  const effectiveTables = agentFilter
+    ? (['observations'] as Array<'decisions' | 'patterns' | 'learnings' | 'observations'>)
+    : tables;
 
   const searchResult = await searchBrain(projectRoot, query, {
-    limit: limit ?? 10,
+    limit: effectiveLimit,
     tables: effectiveTables,
   });
 
@@ -178,7 +284,7 @@ export async function searchBrainCompact(
   // We handle both naming conventions for robustness.
   let results: BrainCompactHit[] = [];
 
-  if (!agent) {
+  if (!agentFilter) {
     for (const d of searchResult.decisions) {
       const raw = d as Record<string, unknown>;
       results.push({
@@ -213,7 +319,7 @@ export async function searchBrainCompact(
   for (const o of searchResult.observations) {
     const raw = o as Record<string, unknown>;
     // T418: apply agent post-filter when specified
-    if (agent) {
+    if (agentFilter) {
       const rowAgent = o.agent ?? (raw['agent'] as string | null) ?? null;
       if (rowAgent !== agent) continue;
     }
@@ -226,18 +332,23 @@ export async function searchBrainCompact(
   }
 
   // Apply date filters client-side if provided
-  if (dateStart) {
-    results = results.filter((r) => r.date >= dateStart);
-  }
-  if (dateEnd) {
-    results = results.filter((r) => r.date <= dateEnd);
-  }
+  if (dateStart) results = results.filter((r) => r.date >= dateStart);
+  if (dateEnd) results = results.filter((r) => r.date <= dateEnd);
 
   // Enrich each hit with _next progressive disclosure directives
   for (const hit of results) {
     hit._next = memoryFindHitNext(hit.id);
   }
 
+  // Citation tracking + retrieval logging (non-blocking)
+  if (results.length > 0) {
+    const returnedIds = results.map((r) => r.id);
+    setImmediate(() => {
+      incrementCitationCounts(projectRoot, returnedIds).catch(() => {});
+      logRetrieval(projectRoot, query, returnedIds, 'find', results.length * 50).catch(() => {});
+    });
+  }
+
   return {
     results,
     total: results.length,
@@ -488,6 +599,21 @@ export async function fetchBrainEntries(
     }
   }
 
+  // Citation tracking + retrieval logging (non-blocking)
+  if (results.length > 0) {
+    const fetchedIds = results.map((r) => r.id);
+    setImmediate(() => {
+      incrementCitationCounts(projectRoot, fetchedIds).catch(() => {});
+      logRetrieval(
+        projectRoot,
+        fetchedIds.join(','),
+        fetchedIds,
+        'fetch',
+        results.length * 500,
+      ).catch(() => {});
+    });
+  }
+
   return {
     results,
     notFound,
@@ -551,6 +677,7 @@ export async function observeBrain(
     sourceSessionId,
     sourceType,
     agent,
+    sourceConfidence: sourceConfidenceParam,
   } = params;
 
   if (!text?.trim()) {
@@ -561,6 +688,30 @@ export async function observeBrain(
   const title = titleParam ?? text.slice(0, 120);
   const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
 
+  // T549 Wave 1-A: Tier routing for observations.
+  // Observations always start as short-term episodic entries.
+  // sourceConfidence routing (spec §4.1 Decision Tree):
+  //   - sourceType 'manual' → 'owner' (owner-stated facts skip short-term in consolidator)
+  //   - sourceType 'session-debrief' → 'task-outcome' (synthesized summaries)
+  //   - otherwise → 'agent' (default for all hook/agent writes)
+  // Source confidence routing (spec §4.1 Decision Tree):
+  //   - sourceType 'manual' → 'owner' (owner-stated facts are ground truth)
+  //   - sourceType 'session-debrief' → 'task-outcome' (verified by completion)
+  //   - otherwise → 'agent' (default for all hook/agent writes)
+  // Owner and task-outcome sources are auto-verified as ground truth.
+  // Agent-inferred entries start unverified — consolidator promotes via corroboration.
+  const resolvedSourceConfidence: BrainSourceConfidence =
+    sourceConfidenceParam ??
+    (sourceType === 'manual'
+      ? 'owner'
+      : sourceType === 'session-debrief'
+        ? 'task-outcome'
+        : 'agent');
+  const memoryTier: BrainMemoryTier = 'short';
+  const memoryType = 'episodic' as const;
+  const verified =
+    resolvedSourceConfidence === 'owner' || resolvedSourceConfidence === 'task-outcome';
+
   // Content-hash dedup: SHA-256 prefix of title+text
   const contentHash = createHash('sha256')
     .update(title + text)
@@ -603,8 +754,13 @@ export async function observeBrain(
     }
   }
 
-  // Compute quality score from text richness and title length.
-  const qualityScore = computeObservationQuality({ text, title });
+  // Compute quality score from text richness, title length, and T549 source multiplier.
+  const qualityScore = computeObservationQuality({
+    text,
+    title,
+    sourceConfidence: resolvedSourceConfidence,
+    memoryTier,
+  });
 
   const id = `O-${Date.now().toString(36)}-${(observeSeq++ % 1000).toString(36)}`;
   const accessor = await getBrainAccessor(projectRoot);
@@ -621,6 +777,11 @@ export async function observeBrain(
     agent: agent ?? null,
     qualityScore,
     createdAt: now,
+    // T549 Wave 1-A: tier/type/confidence assigned at write time
+    memoryTier,
+    memoryType,
+    sourceConfidence: resolvedSourceConfidence,
+    verified,
   });
 
   // Populate embedding if provider is available (T5387).
@@ -846,3 +1007,454 @@ export async function populateEmbeddings(
 
   return { processed, skipped, errors };
 }
+
+// ============================================================================
+// Budget-Aware Retrieval (T549 Wave 3-A)
+// ============================================================================
+
+/** Options for budget-aware retrieval. */
+export interface BudgetedRetrievalOptions {
+  /** Filter by cognitive types (semantic / episodic / procedural). */
+  types?: Array<'semantic' | 'episodic' | 'procedural'>;
+  /** Filter by memory tiers (short / medium / long). */
+  tiers?: Array<'short' | 'medium' | 'long'>;
+  /** When true, only return verified entries. Default: false. */
+  verified?: boolean;
+}
+
+/** A single entry returned by budget-aware retrieval. */
+export interface BudgetedEntry {
+  id: string;
+  type: string;
+  title: string;
+  text: string;
+  /** Fused relevance score: FTS50% + vector40% + graph10% × qualityScore. */
+  score: number;
+  /** Estimated token cost for this entry (~chars/4). */
+  tokensEstimated: number;
+  /** Memory tier for this entry. */
+  memoryTier?: string;
+  /** Cognitive type for this entry. */
+  memoryType?: string;
+}
+
+/** Result from retrieveWithBudget. */
+export interface BudgetedResult {
+  entries: BudgetedEntry[];
+  /** Total tokens consumed by returned entries. */
+  tokensUsed: number;
+  /** Tokens remaining from the original budget. */
+  tokensRemaining: number;
+  /** Number of entries excluded due to budget constraints. */
+  excluded: number;
+}
+
+/**
+ * Budget-aware hybrid retrieval combining FTS5, vector KNN, and graph neighbor scores.
+ *
+ * Strategy (parallel where possible):
+ *   A. FTS5 BM25 search (always)  — keyword precision (50% weight)
+ *   B. Vector KNN search (optional) — semantic recall (40% weight, skipped if no embeddings)
+ *   C. Graph neighbors (optional) — associative context (10% weight, skipped if graph empty)
+ *
+ * Score fusion: final = (fts*0.50 + vec*0.40 + graph*0.10) × qualityScore
+ * Recency boost: +0.05 for entries updated in last 7 days.
+ * Type priority: procedural entries get +0.10 (always-useful rules).
+ *
+ * Budget enforcement:
+ *   - Rank top-50 candidates by fused score.
+ *   - Walk list, accumulate token cost (≈ textLen/4), stop at budget.
+ *   - Episodic entries dropped first when budget is tight.
+ *
+ * Citation tracking: increments citationCount for returned entries in background (setImmediate).
+ *
+ * @param projectRoot - Project root directory
+ * @param query - Text to search for
+ * @param tokenBudget - Maximum tokens to spend on results (default 500)
+ * @param options - Optional filters (types, tiers, verified)
+ * @returns Retrieved entries within budget with token accounting
+ */
+export async function retrieveWithBudget(
+  projectRoot: string,
+  query: string,
+  tokenBudget = 500,
+  options?: BudgetedRetrievalOptions,
+): Promise<BudgetedResult> {
+  if (!query?.trim()) {
+    return { entries: [], tokensUsed: 0, tokensRemaining: tokenBudget, excluded: 0 };
+  }
+
+  // -------------------------------------------------------------------------
+  // Run search strategies in parallel
+  // -------------------------------------------------------------------------
+  const [ftsResult, vecResults, graphNeighbors] = await Promise.all([
+    // A. FTS5
+    searchBrain(projectRoot, query, { limit: 30 }).catch(() => ({
+      decisions: [],
+      patterns: [],
+      learnings: [],
+      observations: [],
+    })),
+    // B. Vector KNN (degrades gracefully when unavailable)
+    searchSimilar(query, projectRoot, 20).catch(
+      () => [] as ReturnType<typeof searchSimilar> extends Promise<infer T> ? T : never[],
+    ),
+    // C. Graph neighbors from top FTS hit
+    Promise.resolve([] as Array<{ id: string; graphScore: number }>),
+  ]);
+
+  // -------------------------------------------------------------------------
+  // Build ID → score map from FTS results
+  // -------------------------------------------------------------------------
+  interface ScoredEntry {
+    id: string;
+    type: string;
+    title: string;
+    text: string;
+    ftsScore: number;
+    vecScore: number;
+    graphScore: number;
+    qualityScore: number;
+    memoryTier?: string;
+    memoryType?: string;
+    updatedAt?: string;
+  }
+
+  const candidateMap = new Map<string, ScoredEntry>();
+
+  // FTS results (normalized score 0.5 starting point — BM25 doesn't give 0..1)
+  const FTS_BASE = 0.5;
+  for (const d of ftsResult.decisions) {
+    const raw = d as Record<string, unknown>;
+    const id = d.id;
+    const tier = (d.memoryTier ?? (raw['memory_tier'] as string | undefined)) || undefined;
+    const mtype = (d.memoryType ?? (raw['memory_type'] as string | undefined)) || undefined;
+    const updatedAt = (d.updatedAt ?? (raw['updated_at'] as string | undefined)) || undefined;
+    candidateMap.set(id, {
+      id,
+      type: 'decision',
+      title: d.decision.slice(0, 120),
+      text: `${d.decision} — ${d.rationale}`,
+      ftsScore: FTS_BASE,
+      vecScore: 0,
+      graphScore: 0,
+      qualityScore: d.qualityScore ?? 0.5,
+      memoryTier: tier,
+      memoryType: mtype,
+      updatedAt,
+    });
+  }
+
+  for (const p of ftsResult.patterns) {
+    const raw = p as Record<string, unknown>;
+    const id = p.id;
+    const tier = (p.memoryTier ?? (raw['memory_tier'] as string | undefined)) || undefined;
+    const mtype = (p.memoryType ?? (raw['memory_type'] as string | undefined)) || undefined;
+    const updatedAt = (p.updatedAt ?? (raw['updated_at'] as string | undefined)) || undefined;
+    candidateMap.set(id, {
+      id,
+      type: 'pattern',
+      title: p.pattern.slice(0, 120),
+      text: `${p.pattern} — ${p.context}`,
+      ftsScore: FTS_BASE,
+      vecScore: 0,
+      graphScore: 0,
+      qualityScore: p.qualityScore ?? 0.5,
+      memoryTier: tier,
+      memoryType: mtype,
+      updatedAt,
+    });
+  }
+
+  for (const l of ftsResult.learnings) {
+    const raw = l as Record<string, unknown>;
+    const id = l.id;
+    const tier = (l.memoryTier ?? (raw['memory_tier'] as string | undefined)) || undefined;
+    const mtype = (l.memoryType ?? (raw['memory_type'] as string | undefined)) || undefined;
+    const updatedAt = (l.updatedAt ?? (raw['updated_at'] as string | undefined)) || undefined;
+    candidateMap.set(id, {
+      id,
+      type: 'learning',
+      title: l.insight.slice(0, 120),
+      text: `${l.insight} (source: ${l.source})`,
+      ftsScore: FTS_BASE,
+      vecScore: 0,
+      graphScore: 0,
+      qualityScore: l.qualityScore ?? 0.5,
+      memoryTier: tier,
+      memoryType: mtype,
+      updatedAt,
+    });
+  }
+
+  for (const o of ftsResult.observations) {
+    const raw = o as Record<string, unknown>;
+    const id = o.id;
+    const tier = (o.memoryTier ?? (raw['memory_tier'] as string | undefined)) || undefined;
+    const mtype = (o.memoryType ?? (raw['memory_type'] as string | undefined)) || undefined;
+    const updatedAt = (o.updatedAt ?? (raw['updated_at'] as string | undefined)) || undefined;
+    candidateMap.set(id, {
+      id,
+      type: 'observation',
+      title: o.title.slice(0, 120),
+      text: o.narrative ?? o.title,
+      ftsScore: FTS_BASE,
+      vecScore: 0,
+      graphScore: 0,
+      qualityScore: o.qualityScore ?? 0.5,
+      memoryTier: tier,
+      memoryType: mtype,
+      updatedAt,
+    });
+  }
+
+  // B. Merge vector scores (distance → similarity: similarity = 1 - distance)
+  for (const v of vecResults) {
+    const simScore = Math.max(0, 1 - v.distance);
+    const existing = candidateMap.get(v.id);
+    if (existing) {
+      existing.vecScore = simScore;
+    } else {
+      candidateMap.set(v.id, {
+        id: v.id,
+        type: v.type,
+        title: v.title.slice(0, 120),
+        text: v.text,
+        ftsScore: 0,
+        vecScore: simScore,
+        graphScore: 0,
+        qualityScore: 0.5,
+        memoryTier: undefined,
+        memoryType: undefined,
+      });
+    }
+  }
+
+  // C. Merge graph scores
+  for (const g of graphNeighbors) {
+    const existing = candidateMap.get(g.id);
+    if (existing) {
+      existing.graphScore = g.graphScore;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Score fusion + ranking
+  // -------------------------------------------------------------------------
+  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
+    .toISOString()
+    .replace('T', ' ')
+    .slice(0, 19);
+
+  const candidates = Array.from(candidateMap.values()).map((c) => {
+    // Fused score
+    let score = c.ftsScore * 0.5 + c.vecScore * 0.4 + c.graphScore * 0.1;
+
+    // Quality multiplier
+    score *= c.qualityScore;
+
+    // Recency boost for recently-updated entries
+    if (c.updatedAt && c.updatedAt >= sevenDaysAgo) {
+      score += 0.05;
+    }
+
+    // Type priority boost for procedural entries (always-useful rules)
+    if (c.memoryType === 'procedural' || c.type === 'pattern') {
+      score += 0.1;
+    }
+
+    return { ...c, score };
+  });
+
+  // -------------------------------------------------------------------------
+  // Apply option filters (types, tiers, verified)
+  // -------------------------------------------------------------------------
+
+  // We'll apply verified filter by checking the DB if requested
+  let filtered = candidates;
+
+  if (options?.types && options.types.length > 0) {
+    const allowedTypes = new Set(options.types);
+    filtered = filtered.filter((c) => {
+      if (!c.memoryType) return true; // unknown type — include
+      return allowedTypes.has(c.memoryType as 'semantic' | 'episodic' | 'procedural');
+    });
+  }
+
+  if (options?.tiers && options.tiers.length > 0) {
+    const allowedTiers = new Set(options.tiers);
+    filtered = filtered.filter((c) => {
+      if (!c.memoryTier) return true; // unknown tier — include
+      return allowedTiers.has(c.memoryTier as 'short' | 'medium' | 'long');
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Sort: procedural first, then by score descending
+  // -------------------------------------------------------------------------
+  filtered.sort((a, b) => {
+    const aProcedural = a.memoryType === 'procedural' || a.type === 'pattern' ? 1 : 0;
+    const bProcedural = b.memoryType === 'procedural' || b.type === 'pattern' ? 1 : 0;
+    if (aProcedural !== bProcedural) return bProcedural - aProcedural;
+    return b.score - a.score;
+  });
+
+  // Cap candidate list at top 50
+  const topCandidates = filtered.slice(0, 50);
+
+  // -------------------------------------------------------------------------
+  // Budget enforcement — episodic entries are dropped first when budget tight
+  // -------------------------------------------------------------------------
+
+  // Sort for budget walk: procedural first, semantic second, episodic last
+  const typeOrder = (c: ScoredEntry & { score: number }): number => {
+    if (c.memoryType === 'procedural' || c.type === 'pattern') return 0;
+    if (c.memoryType === 'semantic' || c.type === 'decision' || c.type === 'learning') return 1;
+    return 2; // episodic
+  };
+
+  const budgetOrdered = [...topCandidates].sort((a, b) => {
+    const orderDiff = typeOrder(a) - typeOrder(b);
+    if (orderDiff !== 0) return orderDiff;
+    return b.score - a.score;
+  });
+
+  const result: BudgetedEntry[] = [];
+  let tokensUsed = 0;
+  let excluded = 0;
+
+  for (const candidate of budgetOrdered) {
+    const entryTokens = Math.ceil(candidate.text.length / 4);
+
+    if (tokensUsed + entryTokens > tokenBudget) {
+      excluded++;
+      continue;
+    }
+
+    result.push({
+      id: candidate.id,
+      type: candidate.type,
+      title: candidate.title,
+      text: candidate.text,
+      score: candidate.score,
+      tokensEstimated: entryTokens,
+      memoryTier: candidate.memoryTier,
+      memoryType: candidate.memoryType,
+    });
+    tokensUsed += entryTokens;
+  }
+
+  // -------------------------------------------------------------------------
+  // Citation tracking — non-blocking background increment
+  // -------------------------------------------------------------------------
+  if (result.length > 0) {
+    const returnedIds = result.map((e) => e.id);
+    setImmediate(() => {
+      incrementCitationCounts(projectRoot, returnedIds).catch(() => {
+        /* best-effort */
+      });
+    });
+  }
+
+  return {
+    entries: result,
+    tokensUsed,
+    tokensRemaining: tokenBudget - tokensUsed,
+    excluded,
+  };
+}
+
+// ============================================================================
+// Citation Count Increment (non-blocking helper)
+// ============================================================================
+
+/**
+ * Increment citationCount for a list of entry IDs.
+ *
+ * Routes each ID to the correct table based on its ID prefix. All updates
+ * are best-effort — errors are silently swallowed.
+ *
+ * @param projectRoot - Project root for brain.db resolution
+ * @param ids - Entry IDs whose citation counts should be incremented
+ */
+async function incrementCitationCounts(projectRoot: string, ids: string[]): Promise<void> {
+  if (ids.length === 0) return;
+
+  const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
+  await getBrainDb(projectRoot);
+  const nativeDb = getBrainNativeDb();
+  if (!nativeDb) return;
+
+  const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+  for (const id of ids) {
+    let table: string;
+    if (id.startsWith('D-') || /^D\d/.test(id)) {
+      table = 'brain_decisions';
+    } else if (id.startsWith('P-') || /^P\d/.test(id)) {
+      table = 'brain_patterns';
+    } else if (id.startsWith('L-') || /^L\d/.test(id)) {
+      table = 'brain_learnings';
+    } else {
+      table = 'brain_observations';
+    }
+
+    try {
+      nativeDb
+        .prepare(
+          `UPDATE ${table} SET citation_count = citation_count + 1, updated_at = ? WHERE id = ?`,
+        )
+        .run(now, id);
+    } catch {
+      /* best-effort — column may not exist in older schemas */
+    }
+  }
+}
+
+/**
+ * Log a retrieval event to brain_retrieval_log for co-retrieval analysis.
+ *
+ * Creates the table on first use if it doesn't exist (self-healing).
+ * Best-effort: errors are silently swallowed.
+ */
+async function logRetrieval(
+  projectRoot: string,
+  query: string,
+  entryIds: string[],
+  source: string,
+  tokensUsed?: number,
+): Promise<void> {
+  if (entryIds.length === 0) return;
+
+  const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
+  await getBrainDb(projectRoot);
+  const nativeDb = getBrainNativeDb();
+  if (!nativeDb) return;
+
+  // Self-healing: create table if not exists
+  const createSql =
+    'CREATE TABLE IF NOT EXISTS brain_retrieval_log (' +
+    'id INTEGER PRIMARY KEY AUTOINCREMENT,' +
+    'query TEXT NOT NULL,' +
+    'entry_ids TEXT NOT NULL,' +
+    'entry_count INTEGER NOT NULL,' +
+    'source TEXT NOT NULL,' +
+    'tokens_used INTEGER,' +
+    "created_at TEXT NOT NULL DEFAULT (datetime('now'))" +
+    ')';
+  try {
+    nativeDb.prepare(createSql).run();
+  } catch {
+    return;
+  }
+
+  try {
+    nativeDb
+      .prepare(
+        'INSERT INTO brain_retrieval_log (query, entry_ids, entry_count, source, tokens_used) VALUES (?, ?, ?, ?, ?)',
+      )
+      .run(query, entryIds.join(','), entryIds.length, source, tokensUsed ?? null);
+  } catch {
+    /* best-effort */
+  }
+}