@steno-ai/engine 0.1.0

package/src/retrieval/query-expansion.ts

@@ -0,0 +1,86 @@
+import type { LLMAdapter } from '../adapters/llm.js';
+
+/**
+ * Multi-query expansion — like Hydra DB's Adaptive Query Expansion.
+ *
+ * Takes a single query and generates 3-4 semantically diverse reformulations.
+ * Each captures a different interpretation of the user's intent:
+ * - Paraphrases
+ * - Temporal concretizations ("last week" → "projects from March 18-25")
+ * - Domain-specific restatements
+ *
+ * All expanded queries are searched in parallel for higher recall.
+ */
+export async function expandQuery(
+  llm: LLMAdapter,
+  query: string,
+): Promise<string[]> {
+  // Short queries or very specific ones don't need expansion
+  if (query.length < 15 || query.split(' ').length <= 3) {
+    return [query];
+  }
+
+  try {
+    const response = await llm.complete([
+      {
+        role: 'system',
+        content: `You generate search query expansions for a memory retrieval system. Given a user query, produce 3 alternative phrasings that capture different aspects of the intent.
+
+Rules:
+- Each alternative should use different keywords/phrasing
+- Include temporal concretizations if relevant ("recently" → "in the past week")
+- Include domain-specific restatements
+- Keep each alternative concise (under 15 words)
+- Return ONLY a JSON array of strings: ["query1", "query2", "query3"]`,
+      },
+      {
+        role: 'user',
+        content: query,
+      },
+    ], { temperature: 0.3, responseFormat: 'json' });
+
+    const parsed = JSON.parse(response.content);
+    const expansions = Array.isArray(parsed)
+      ? parsed.filter((q): q is string => typeof q === 'string' && q.trim().length > 0)
+      : [];
+
+    // Always include the original query first
+    return [query, ...expansions.slice(0, 3)];
+  } catch {
+    // If expansion fails, just use the original query
+    return [query];
+  }
+}
+
+/**
+ * Fast heuristic expansion — no LLM needed.
+ * Generates simple reformulations using string manipulation.
+ * Use this when you don't have an LLM available or want zero latency.
+ */
+export function expandQueryHeuristic(query: string): string[] {
+  const queries = [query];
+  const lower = query.toLowerCase();
+
+  // Add "User" prefix version if not present
+  if (!lower.startsWith('user') && !lower.includes('my ') && !lower.includes('i ')) {
+    queries.push(`User ${lower}`);
+  }
+
+  // Convert "my X" to "user's X"
+  if (lower.includes('my ')) {
+    queries.push(lower.replace(/\bmy\b/g, "user's"));
+  }
+
+  // Convert questions to statements
+  if (lower.startsWith('what ') || lower.startsWith('who ') || lower.startsWith('where ') || lower.startsWith('when ')) {
+    const statement = lower
+      .replace(/^what (is|are|was|were) /, '')
+      .replace(/^who (is|are|was|were) /, '')
+      .replace(/^where (is|are|was|were|does|did) /, '')
+      .replace(/^when (did|does|was|were|is) /, '')
+      .replace(/\?$/, '');
+    if (statement !== lower) queries.push(statement);
+  }
+
+  return queries.slice(0, 4);
+}

package/src/retrieval/reranker.d.ts

@@ -0,0 +1,15 @@
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { SearchResult } from './types.js';
+/**
+ * Re-rank search results using embedding cosine similarity.
+ * Deterministic, free (uses existing embedding model), no LLM call.
+ *
+ * How it works:
+ * 1. Embed the query
+ * 2. Embed all fact content texts in a single batch call
+ * 3. Compute cosine similarity between query embedding and each fact embedding
+ * 4. Blend the similarity score with the original fusion score
+ * 5. Re-sort by blended score
+ */
+export declare function rerank(embedding: EmbeddingAdapter, query: string, results: SearchResult[], topK?: number): Promise<SearchResult[]>;
+//# sourceMappingURL=reranker.d.ts.map

package/src/retrieval/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,wBAAsB,MAAM,CAC1B,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EAAE,EACvB,IAAI,GAAE,MAAW,GAChB,OAAO,CAAC,YAAY,EAAE,CAAC,CAsBzB"}

package/src/retrieval/reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.js","sourceRoot":"","sources":["reranker.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,SAA2B,EAC3B,KAAa,EACb,OAAuB,EACvB,OAAe,EAAE;IAEjB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IAExC,4CAA4C;IAC5C,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3D,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,cAAc,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC;IACtC,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE3C,wDAAwD;IACxD,MAAM,aAAa,GAAG,GAAG,CAAC,CAAC,sDAAsD;IACjF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAClC,MAAM,WAAW,GAAG,gBAAgB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,CAAE,CAAC,CAAC;QACzE,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,aAAa,CAAC,GAAG,WAAW,GAAG,aAAa,CAAC;QACjF,OAAO,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,wBAAwB;IACxB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAEzC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAW,EAAE,CAAW;IAChD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtD,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QAC5B,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACvB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,KAAK,CAAC;AAC9C,CAAC"}

package/src/retrieval/reranker.ts

@@ -0,0 +1,56 @@
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { SearchResult } from './types.js';
+
+/**
+ * Re-rank search results using embedding cosine similarity.
+ * Deterministic, free (uses existing embedding model), no LLM call.
+ *
+ * How it works:
+ * 1. Embed the query
+ * 2. Embed all fact content texts in a single batch call
+ * 3. Compute cosine similarity between query embedding and each fact embedding
+ * 4. Blend the similarity score with the original fusion score
+ * 5. Re-sort by blended score
+ */
+export async function rerank(
+  embedding: EmbeddingAdapter,
+  query: string,
+  results: SearchResult[],
+  topK: number = 10,
+): Promise<SearchResult[]> {
+  if (results.length === 0) return [];
+  if (results.length <= 1) return results;
+
+  // Embed query + all fact texts in one batch
+  const texts = [query, ...results.map(r => r.fact.content)];
+  const embeddings = await embedding.embedBatch(texts);
+  const queryEmbedding = embeddings[0]!;
+  const factEmbeddings = embeddings.slice(1);
+
+  // Score each result by cosine similarity with the query
+  const RERANK_WEIGHT = 0.4; // 40% embedding similarity, 60% original fusion score
+  const scored = results.map((r, i) => {
+    const rerankScore = cosineSimilarity(queryEmbedding, factEmbeddings[i]!);
+    const blendedScore = r.score * (1 - RERANK_WEIGHT) + rerankScore * RERANK_WEIGHT;
+    return { ...r, score: blendedScore };
+  });
+
+  // Sort by blended score
+  scored.sort((a, b) => b.score - a.score);
+
+  return scored.slice(0, topK);
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dotProduct / denom;
+}

package/src/retrieval/salience-scorer.d.ts

@@ -0,0 +1,15 @@
+import type { Candidate } from './types.js';
+export interface SalienceConfig {
+    halfLifeDays: number;
+    normalizationK: number;
+}
+/**
+ * Score all candidates with recency and salience signals.
+ *
+ * recencyScore = pure time decay (how recently the fact was accessed)
+ * salienceScore = importance x frequency factor (how important and reinforced)
+ *
+ * These are separate signals that feed into fusion with independent weights.
+ */
+export declare function scoreSalience(candidates: Candidate[], config?: Partial<SalienceConfig>): Candidate[];
+//# sourceMappingURL=salience-scorer.d.ts.map

package/src/retrieval/salience-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"salience-scorer.d.ts","sourceRoot":"","sources":["salience-scorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,SAAS,EAAE,EACvB,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAC/B,SAAS,EAAE,CAsCb"}

package/src/retrieval/salience-scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"salience-scorer.js","sourceRoot":"","sources":["salience-scorer.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAuB,EACvB,MAAgC;IAEhC,MAAM,YAAY,GAAG,MAAM,EAAE,YAAY,IAAI,EAAE,CAAC;IAChD,MAAM,cAAc,GAAG,MAAM,EAAE,cAAc,IAAI,EAAE,CAAC;IAEpD,OAAO,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;QAChC,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;QAE3B,sDAAsD;QACtD,sEAAsE;QACtE,mEAAmE;QACnE,mEAAmE;QACnE,0CAA0C;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,GAAG,YAAY,CAAC;QAEvC,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY;YACvC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;YAC9E,CAAC,CAAC,QAAQ,CAAC;QACb,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAElF,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS;YACtC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;YAC3E,CAAC,CAAC,QAAQ,CAAC;QACb,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAEnF,mDAAmD;QACnD,MAAM,YAAY,GAAG,GAAG,GAAG,aAAa,GAAG,GAAG,GAAG,eAAe,CAAC;QAEjE,0CAA0C;QAC1C,kFAAkF;QAClF,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;QACnG,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,GAAG,eAAe,CAAC;QAExD,OAAO;YACL,GAAG,SAAS;YACZ,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YACpD,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;SACvD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/src/retrieval/salience-scorer.ts

@@ -0,0 +1,57 @@
+import type { Candidate } from './types.js';
+
+export interface SalienceConfig {
+  halfLifeDays: number;      // default 30
+  normalizationK: number;    // default 50
+}
+
+/**
+ * Score all candidates with recency and salience signals.
+ *
+ * recencyScore = pure time decay (how recently the fact was accessed)
+ * salienceScore = importance x frequency factor (how important and reinforced)
+ *
+ * These are separate signals that feed into fusion with independent weights.
+ */
+export function scoreSalience(
+  candidates: Candidate[],
+  config?: Partial<SalienceConfig>,
+): Candidate[] {
+  const halfLifeDays = config?.halfLifeDays ?? 30;
+  const normalizationK = config?.normalizationK ?? 50;
+
+  return candidates.map(candidate => {
+    const { fact } = candidate;
+
+    // Recency: blend of access recency + creation recency
+    // Access recency = how recently the fact was recalled (reinforcement)
+    // Creation recency = how recently the fact was created (freshness)
+    // Git-style versioning needs creation recency so newer versions of
+    // the same lineage naturally rank higher.
+    const lambda = Math.LN2 / halfLifeDays;
+
+    const daysSinceAccess = fact.lastAccessed
+      ? (Date.now() - new Date(fact.lastAccessed).getTime()) / (1000 * 60 * 60 * 24)
+      : Infinity;
+    const accessRecency = fact.lastAccessed ? Math.exp(-lambda * daysSinceAccess) : 0;
+
+    const daysSinceCreation = fact.createdAt
+      ? (Date.now() - new Date(fact.createdAt).getTime()) / (1000 * 60 * 60 * 24)
+      : Infinity;
+    const creationRecency = fact.createdAt ? Math.exp(-lambda * daysSinceCreation) : 0;
+
+    // Blend: 50% access recency + 50% creation recency
+    const recencyScore = 0.5 * accessRecency + 0.5 * creationRecency;
+
+    // Salience: importance x frequency factor
+    // This captures "how important is this fact AND how often has it been reinforced"
+    const frequencyFactor = Math.min(1.0, Math.log(1 + fact.frequency) / Math.log(1 + normalizationK));
+    const salienceScore = fact.importance * frequencyFactor;
+
+    return {
+      ...candidate,
+      recencyScore: Math.max(0, Math.min(1, recencyScore)),
+      salienceScore: Math.max(0, Math.min(1, salienceScore)),
+    };
+  });
+}

package/src/retrieval/search.d.ts

@@ -0,0 +1,21 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { CacheAdapter } from '../adapters/cache.js';
+import type { LLMAdapter } from '../adapters/llm.js';
+import type { SearchOptions, SearchResponse, FusionWeights } from './types.js';
+export interface SearchConfig {
+    storage: StorageAdapter;
+    embedding: EmbeddingAdapter;
+    cache?: CacheAdapter;
+    defaultWeights?: FusionWeights;
+    salienceHalfLifeDays?: number;
+    salienceNormalizationK?: number;
+    graphMaxDepth?: number;
+    graphMaxEntities?: number;
+    rerankerLLM?: LLMAdapter;
+    rerank?: boolean;
+    /** LLM for query expansion (optional — falls back to heuristic expansion) */
+    expansionLLM?: LLMAdapter;
+}
+export declare function search(config: SearchConfig, options: SearchOptions): Promise<SearchResponse>;
+//# sourceMappingURL=search.d.ts.map

package/src/retrieval/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAa,MAAM,YAAY,CAAC;AAa1F,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B;AAED,wBAAsB,MAAM,CAC1B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,cAAc,CAAC,CA0KzB"}

package/src/retrieval/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["search.ts"],"names":[],"mappings":"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"}

package/src/retrieval/search.ts

@@ -0,0 +1,271 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { CacheAdapter } from '../adapters/cache.js';
+import type { LLMAdapter } from '../adapters/llm.js';
+import type { SearchOptions, SearchResponse, FusionWeights, Candidate } from './types.js';
+import { DEFAULT_FUSION_WEIGHTS } from './types.js';
+import { compoundSearchSignal } from './compound-search.js';
+import { graphSearch } from './graph-traversal.js';
+import { matchTriggers } from './trigger-matcher.js';
+import { scoreSalience } from './salience-scorer.js';
+import { fuseAndRank } from './fusion.js';
+import { surfaceContradictions } from './contradiction-surfacer.js';
+import { recordAccesses } from '../feedback/tracker.js';
+import { CachedEmbeddingAdapter } from './embedding-cache.js';
+import { rerank } from './reranker.js';
+import { expandQueryHeuristic } from './query-expansion.js';
+import { extractTimeReference, scoreTemporalRelevance } from './temporal-scorer.js';
+
+export interface SearchConfig {
+  storage: StorageAdapter;
+  embedding: EmbeddingAdapter;
+  cache?: CacheAdapter;  // if provided, wraps embedding with cache
+  defaultWeights?: FusionWeights;
+  salienceHalfLifeDays?: number;
+  salienceNormalizationK?: number;
+  graphMaxDepth?: number;
+  graphMaxEntities?: number;
+  rerankerLLM?: LLMAdapter; // Deprecated — use embedding-based reranking instead
+  rerank?: boolean; // If true, re-ranks results using embedding similarity (deterministic, free)
+  /** LLM for query expansion (optional — falls back to heuristic expansion) */
+  expansionLLM?: LLMAdapter;
+}
+
+export async function search(
+  config: SearchConfig,
+  options: SearchOptions,
+): Promise<SearchResponse> {
+  const startTime = Date.now();
+  const limit = Math.min(options.limit ?? 10, 100);
+  const weights = options.weights ?? config.defaultWeights ?? DEFAULT_FUSION_WEIGHTS;
+  const fetchMultiplier = 3; // fetch 3x limit from each signal for better fusion
+
+  // Wrap embedding with cache if available
+  const effectiveEmbedding = config.cache
+    ? new CachedEmbeddingAdapter(config.embedding, config.cache)
+    : config.embedding;
+
+  // 1. Run all signals in PARALLEL — ONE compound search (not multiple)
+  //    Multi-query expansion adds latency (3× embedding calls). Instead:
+  //    - Single compound search with original query (vector + keyword in 1 DB call)
+  //    - Graph search with original query
+  //    - Trigger matching
+  //    All parallel = single round trip time.
+  const t0 = Date.now();
+
+  const tCompound = Date.now();
+  const compoundPromise = compoundSearchSignal(config.storage, effectiveEmbedding, options.query, options.tenantId, options.scope, options.scopeId, limit * fetchMultiplier).catch(() => ({ vectorCandidates: [] as Candidate[], keywordCandidates: [] as Candidate[] }));
+  const tGraph = Date.now();
+  const graphPromise = graphSearch(config.storage, effectiveEmbedding, options.query, options.tenantId, options.scope, options.scopeId, limit * fetchMultiplier, { maxDepth: config.graphMaxDepth, maxEntities: config.graphMaxEntities, asOf: options.temporalFilter?.asOf }).catch(() => [] as Candidate[]);
+  const tTrigger = Date.now();
+  const triggerPromise = matchTriggers(config.storage, effectiveEmbedding, options.query, options.tenantId, options.scope, options.scopeId).catch(() => ({ candidates: [] as Candidate[], triggersMatched: [] as string[] }));
+
+  const [compoundResult, graphSettled, triggerSettled] = await Promise.all([
+    compoundPromise.then(r => { console.error(`[steno-search] compound: ${Date.now() - tCompound}ms (vec=${r.vectorCandidates.length}, kw=${r.keywordCandidates.length})`); return r; }),
+    graphPromise.then(r => { console.error(`[steno-search] graph: ${Date.now() - tGraph}ms (${Array.isArray(r) ? r.length : 0} candidates)`); return r; }),
+    triggerPromise.then(r => { console.error(`[steno-search] trigger: ${Date.now() - tTrigger}ms`); return r; }),
+  ]);
+  console.error(`[steno-search] Signals total: ${Date.now() - t0}ms`);
+
+  const vectorCandidates = compoundResult.vectorCandidates;
+  const keywordCandidates = compoundResult.keywordCandidates;
+  const graphCandidates = Array.isArray(graphSettled) ? graphSettled : [];
+  const triggerResult = triggerSettled;
+  const triggersMatched = triggerResult.triggersMatched;
+
+  // 2. Triple-tier pre-fusion reranking — rerank each stream INDEPENDENTLY
+  //    Only rerank when there are enough candidates to justify the embedding cost
+  //    before fusion, like Hydra DB's triple-tier architecture.
+  const t1 = Date.now();
+
+  // Batch-embed query + all unique candidate contents in ONE call
+  const allPreRerankCandidates = [...vectorCandidates, ...graphCandidates];
+  let queryEmbedding: number[] | null = null;
+  const candidateEmbeddings = new Map<string, number[]>();
+
+  // Only rerank if we have >10 candidates — for small sets the original order is fine
+  if (allPreRerankCandidates.length > 10) {
+    try {
+      const uniqueTexts = new Map<string, string>();
+      for (const c of allPreRerankCandidates) {
+        if (!uniqueTexts.has(c.fact.id)) uniqueTexts.set(c.fact.id, c.fact.content);
+      }
+      const textsToEmbed = [options.query, ...uniqueTexts.values()];
+      const embeddings = await effectiveEmbedding.embedBatch(textsToEmbed);
+      queryEmbedding = embeddings[0]!;
+      let idx = 1;
+      for (const [factId] of uniqueTexts) {
+        candidateEmbeddings.set(factId, embeddings[idx++]!);
+      }
+    } catch {
+      // Reranking fails silently — proceed without it
+    }
+  }
+
+  // Rerank vector candidates
+  if (queryEmbedding && vectorCandidates.length > 1) {
+    const RERANK_W = 0.4;
+    for (const c of vectorCandidates) {
+      const factEmb = candidateEmbeddings.get(c.fact.id);
+      if (factEmb) {
+        const sim = cosineSim(queryEmbedding, factEmb);
+        c.vectorScore = c.vectorScore * (1 - RERANK_W) + sim * RERANK_W;
+      }
+    }
+    vectorCandidates.sort((a, b) => b.vectorScore - a.vectorScore);
+  }
+
+  // Rerank graph candidates
+  if (queryEmbedding && graphCandidates.length > 1) {
+    const RERANK_W = 0.4;
+    for (const c of graphCandidates) {
+      const factEmb = candidateEmbeddings.get(c.fact.id);
+      if (factEmb) {
+        const sim = cosineSim(queryEmbedding, factEmb);
+        c.graphScore = c.graphScore * (1 - RERANK_W) + sim * RERANK_W;
+      }
+    }
+    graphCandidates.sort((a, b) => b.graphScore - a.graphScore);
+  }
+  // Keyword candidates skip reranking — FTS scores shouldn't be overridden by embeddings
+  console.error(`[steno-search] Pre-fusion rerank: ${Date.now() - t1}ms`);
+
+  // 3. Merge all pre-reranked streams
+  const allCandidates: Candidate[] = [
+    ...vectorCandidates,
+    ...keywordCandidates,
+    ...graphCandidates,
+    ...triggerResult.candidates,
+  ];
+
+  if (allCandidates.length === 0) {
+    return {
+      results: [],
+      triggersMatched,
+      totalCandidates: 0,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  // 4. Score salience + recency on all candidates
+  const scoredCandidates = scoreSalience(allCandidates, {
+    halfLifeDays: config.salienceHalfLifeDays,
+    normalizationK: config.salienceNormalizationK,
+  });
+
+  // 4b. Score temporal relevance if query has time reference
+  const timeRef = extractTimeReference(options.query);
+  if (timeRef) {
+    scoreTemporalRelevance(scoredCandidates, timeRef);
+  }
+
+  // 5. Fuse and rank
+  const fusionResults = fuseAndRank(scoredCandidates, weights, limit);
+
+  // 5b. Lineage dedup — keep only the NEWEST version per lineage
+  //     Git-style append-only means multiple versions coexist. For normal queries,
+  //     show only the latest version (by createdAt). For "includeHistory", show all.
+  let dedupedResults = fusionResults;
+  if (!options.includeHistory) {
+    const lineageBest = new Map<string, { idx: number; createdAt: Date; score: number }>();
+    for (let i = 0; i < fusionResults.length; i++) {
+      const r = fusionResults[i]!;
+      const lid = r.fact.lineageId;
+      if (!lid) continue;
+      const existing = lineageBest.get(lid);
+      const createdAt = new Date(r.fact.createdAt);
+      if (!existing || createdAt > existing.createdAt) {
+        lineageBest.set(lid, { idx: i, createdAt, score: r.score });
+      }
+    }
+    const keepIndices = new Set(Array.from(lineageBest.values()).map(v => v.idx));
+    // Also keep facts with no lineage match (unique facts)
+    dedupedResults = fusionResults.filter((r, idx) => {
+      const lid = r.fact.lineageId;
+      if (!lid) return true;
+      return keepIndices.has(idx);
+    });
+  }
+
+  // 5c. Knowledge chain resolution — if a result has metadata.relationType === 'updates',
+  // check if the fact it updates is ALSO in results. If so, suppress the older one.
+  const updatedFactIds = new Set<string>();
+  for (const r of dedupedResults) {
+    const meta = r.fact.metadata as Record<string, unknown> | undefined;
+    if (meta?.relationType === 'updates' && meta?.relatedFactId) {
+      updatedFactIds.add(meta.relatedFactId as string);
+    }
+  }
+  if (updatedFactIds.size > 0) {
+    dedupedResults = dedupedResults.filter(r => !updatedFactIds.has(r.fact.id));
+  }
+
+  // 5d. Token budget trimming — keep highest-scored results that fit within budget
+  if (options.tokenBudget && options.tokenBudget > 0) {
+    let tokenCount = 0;
+    const budgetResults: typeof dedupedResults = [];
+    for (const r of dedupedResults) {
+      // Rough token estimate: content chars / 4, plus sourceChunk if present
+      const factTokens = Math.ceil(r.fact.content.length / 4) +
+        (r.fact.sourceChunk ? Math.ceil(r.fact.sourceChunk.length / 4) : 0);
+      if (tokenCount + factTokens > options.tokenBudget) break;
+      tokenCount += factTokens;
+      budgetResults.push(r);
+    }
+    dedupedResults = budgetResults;
+  }
+
+  // 6. Enrich with contradiction context
+  let results = await surfaceContradictions(config.storage, options.tenantId, dedupedResults);
+  console.error(`[steno-search] Fusion + dedup: ${Date.now() - t1}ms, Total: ${Date.now() - startTime}ms`);
+
+  // 6. Optionally enrich with graph context
+  if (options.includeGraph) {
+    for (const result of results) {
+      const entities = await config.storage.getEntitiesForFact(result.fact.id);
+      const edges: typeof result.graph extends undefined ? never : NonNullable<typeof result.graph>['edges'] = [];
+      for (const entity of entities) {
+        const entityEdges = await config.storage.getEdgesForEntity(options.tenantId, entity.id);
+        edges.push(...entityEdges);
+      }
+      result.graph = { entities, edges };
+    }
+  }
+
+  // 7. Optionally enrich with fact history (previous versions)
+  if (options.includeHistory) {
+    for (const result of results) {
+      const history = await config.storage.getFactsByLineage(options.tenantId, result.fact.lineageId);
+      // Filter out the current fact, sort by version ascending
+      result.history = history
+        .filter(f => f.id !== result.fact.id)
+        .sort((a, b) => a.version - b.version);
+    }
+  }
+
+  // 8. Record memory accesses for metamemory + update decay scores (fire-and-forget)
+  void recordAccesses(config.storage, options.tenantId, options.query, results, {
+    halfLifeDays: config.salienceHalfLifeDays,
+    normalizationK: config.salienceNormalizationK,
+  }).catch(err => console.error('[steno] Failed to record memory accesses:', err));
+
+  return {
+    results,
+    triggersMatched,
+    totalCandidates: allCandidates.length,
+    durationMs: Date.now() - startTime,
+  };
+}
+
+/** Fast cosine similarity for pre-fusion reranking */
+function cosineSim(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}