@steno-ai/engine 0.1.0

package/src/retrieval/embedding-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-cache.d.ts","sourceRoot":"","sources":["embedding-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAK3D,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,UAAU;IANpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAGlB,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,YAAY,EACnB,UAAU,GAAE,MAAa;IAM7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUtC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CA0BvD"}

package/src/retrieval/embedding-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-cache.js","sourceRoot":"","sources":["embedding-cache.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,OAAO,sBAAsB;IAKvB;IACA;IACA;IAND,KAAK,CAAS;IACd,UAAU,CAAS;IAE5B,YACU,KAAuB,EACvB,KAAmB,EACnB,aAAqB,IAAI;QAFzB,UAAK,GAAL,KAAK,CAAkB;QACvB,UAAK,GAAL,KAAK,CAAc;QACnB,eAAU,GAAV,UAAU,CAAe;QAEjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,KAAK,IAAI,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAW,GAAG,CAAC,CAAC;QACnD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,4DAA4D;QAC5D,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,MAAM,eAAe,GAAa,EAAE,CAAC;QAErC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,KAAK,IAAI,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;YAC7D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAW,GAAG,CAAC,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,IAAI,CAAC,MAAM;gBAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC;QAED,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,aAAa,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;YAC1D,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAEnE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChD,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,CAAE,CAAC;gBAChC,OAAO,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,CAAC,CAAE,CAAC;gBACnC,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,KAAK,IAAI,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAE,CAAC,EAAE,CAAC;gBAC/D,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QAED,OAAO,OAAqB,CAAC;IAC/B,CAAC;CACF;AAED,KAAK,UAAU,QAAQ,CAAC,IAAY;IAClC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC1G,CAAC"}

package/src/retrieval/embedding-cache.ts

@@ -0,0 +1,63 @@
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { CacheAdapter } from '../adapters/cache.js';
+
+/**
+ * Wraps an EmbeddingAdapter with caching.
+ * Same query text -> cached embedding (skip OpenAI call).
+ */
+export class CachedEmbeddingAdapter implements EmbeddingAdapter {
+  readonly model: string;
+  readonly dimensions: number;
+
+  constructor(
+    private inner: EmbeddingAdapter,
+    private cache: CacheAdapter,
+    private ttlSeconds: number = 3600, // 1 hour default
+  ) {
+    this.model = inner.model;
+    this.dimensions = inner.dimensions;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const key = `emb:${this.model}:${await hashText(text)}`;
+    const cached = await this.cache.get<number[]>(key);
+    if (cached) return cached;
+
+    const result = await this.inner.embed(text);
+    await this.cache.set(key, result, this.ttlSeconds);
+    return result;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    // For batch, check cache for each, only embed uncached ones
+    const results: (number[] | null)[] = [];
+    const uncachedIndices: number[] = [];
+
+    for (let i = 0; i < texts.length; i++) {
+      const key = `emb:${this.model}:${await hashText(texts[i]!)}`;
+      const cached = await this.cache.get<number[]>(key);
+      results.push(cached);
+      if (!cached) uncachedIndices.push(i);
+    }
+
+    if (uncachedIndices.length > 0) {
+      const uncachedTexts = uncachedIndices.map(i => texts[i]!);
+      const freshEmbeddings = await this.inner.embedBatch(uncachedTexts);
+
+      for (let j = 0; j < uncachedIndices.length; j++) {
+        const idx = uncachedIndices[j]!;
+        results[idx] = freshEmbeddings[j]!;
+        const key = `emb:${this.model}:${await hashText(texts[idx]!)}`;
+        await this.cache.set(key, freshEmbeddings[j]!, this.ttlSeconds);
+      }
+    }
+
+    return results as number[][];
+  }
+}
+
+async function hashText(text: string): Promise<string> {
+  const encoded = new TextEncoder().encode(text);
+  const hash = await crypto.subtle.digest('SHA-256', encoded);
+  return Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2, '0')).join('').slice(0, 16);
+}

package/src/retrieval/fusion.d.ts

@@ -0,0 +1,26 @@
+import type { Candidate, FusionWeights } from './types.js';
+import type { Fact } from '../models/fact.js';
+export interface FusionResult {
+    fact: Fact;
+    score: number;
+    signals: {
+        vectorScore: number;
+        keywordScore: number;
+        graphScore: number;
+        recencyScore: number;
+        salienceScore: number;
+    };
+    source: string;
+    triggeredBy?: string;
+}
+/**
+ * Fuse candidates from multiple retrieval signals into a single ranked list.
+ *
+ * 1. Normalizes weights so they sum to 1.0
+ * 2. Deduplicates by fact ID, keeping the highest score per signal
+ * 3. Computes a weighted sum for each unique fact
+ * 4. Sorts by score descending
+ * 5. Returns the top `limit` results
+ */
+export declare function fuseAndRank(candidates: Candidate[], weights: FusionWeights, limit: number): FusionResult[];
+//# sourceMappingURL=fusion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["fusion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,GACZ,YAAY,EAAE,CA0FhB"}

package/src/retrieval/fusion.js.map

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

package/src/retrieval/fusion.ts

@@ -0,0 +1,129 @@
+import type { Candidate, FusionWeights } from './types.js';
+import type { Fact } from '../models/fact.js';
+
+export interface FusionResult {
+  fact: Fact;
+  score: number;
+  signals: {
+    vectorScore: number;
+    keywordScore: number;
+    graphScore: number;
+    recencyScore: number;
+    salienceScore: number;
+    temporalScore: number;
+  };
+  source: string;
+  triggeredBy?: string;
+}
+
+/**
+ * Fuse candidates from multiple retrieval signals into a single ranked list.
+ *
+ * 1. Normalizes weights so they sum to 1.0
+ * 2. Deduplicates by fact ID, keeping the highest score per signal
+ * 3. Computes a weighted sum for each unique fact
+ * 4. Sorts by score descending
+ * 5. Returns the top `limit` results
+ */
+export function fuseAndRank(
+  candidates: Candidate[],
+  weights: FusionWeights,
+  limit: number,
+): FusionResult[] {
+  if (candidates.length === 0) return [];
+
+  // 1. Normalize weights so they sum to 1.0
+  const sum =
+    weights.vector +
+    weights.keyword +
+    weights.graph +
+    weights.recency +
+    weights.salience +
+    weights.temporal;
+
+  const w: FusionWeights =
+    sum === 0
+      ? { vector: 1/6, keyword: 1/6, graph: 1/6, recency: 1/6, salience: 1/6, temporal: 1/6 }
+      : {
+          vector: weights.vector / sum,
+          keyword: weights.keyword / sum,
+          graph: weights.graph / sum,
+          recency: weights.recency / sum,
+          salience: weights.salience / sum,
+          temporal: weights.temporal / sum,
+        };
+
+  // 2. Deduplicate by fact ID — keep highest score per signal
+  const factMap = new Map<
+    string,
+    {
+      fact: Fact;
+      vectorScore: number;
+      keywordScore: number;
+      graphScore: number;
+      recencyScore: number;
+      salienceScore: number;
+      temporalScore: number;
+      source: string;
+      triggeredBy?: string;
+    }
+  >();
+
+  for (const c of candidates) {
+    const existing = factMap.get(c.fact.id);
+    if (existing) {
+      existing.vectorScore = Math.max(existing.vectorScore, c.vectorScore);
+      existing.keywordScore = Math.max(existing.keywordScore, c.keywordScore);
+      existing.graphScore = Math.max(existing.graphScore, c.graphScore);
+      existing.recencyScore = Math.max(existing.recencyScore, c.recencyScore);
+      existing.salienceScore = Math.max(existing.salienceScore, c.salienceScore);
+      existing.temporalScore = Math.max(existing.temporalScore, c.temporalScore);
+      if (c.triggeredBy) existing.triggeredBy = c.triggeredBy;
+    } else {
+      factMap.set(c.fact.id, {
+        fact: c.fact,
+        vectorScore: c.vectorScore,
+        keywordScore: c.keywordScore,
+        graphScore: c.graphScore,
+        recencyScore: c.recencyScore,
+        salienceScore: c.salienceScore,
+        temporalScore: c.temporalScore,
+        source: c.source,
+        triggeredBy: c.triggeredBy,
+      });
+    }
+  }
+
+  // 3. Compute final score for each unique fact
+  const results: FusionResult[] = [];
+  for (const entry of factMap.values()) {
+    const score =
+      entry.vectorScore * w.vector +
+      entry.keywordScore * w.keyword +
+      entry.graphScore * w.graph +
+      entry.recencyScore * w.recency +
+      entry.salienceScore * w.salience +
+      entry.temporalScore * w.temporal;
+
+    results.push({
+      fact: entry.fact,
+      score,
+      signals: {
+        vectorScore: entry.vectorScore,
+        keywordScore: entry.keywordScore,
+        graphScore: entry.graphScore,
+        recencyScore: entry.recencyScore,
+        salienceScore: entry.salienceScore,
+        temporalScore: entry.temporalScore,
+      },
+      source: entry.source,
+      triggeredBy: entry.triggeredBy,
+    });
+  }
+
+  // 4. Sort by score descending
+  results.sort((a, b) => b.score - a.score);
+
+  // 5. Take top N
+  return results.slice(0, limit);
+}

package/src/retrieval/graph-traversal.d.ts

@@ -0,0 +1,28 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { Candidate } from './types.js';
+export interface GraphSearchConfig {
+    maxDepth: number;
+    maxEntities: number;
+    asOf?: Date;
+}
+/**
+ * Tokenize query into candidate entity names.
+ * Splits on whitespace, filters short words (< 3 chars), lowercases for canonical lookup.
+ */
+export declare function tokenizeQuery(query: string): string[];
+/**
+ * Graph-based retrieval module.
+ *
+ * 1. Extracts potential entity names from query (simple tokenization)
+ * 2. For each token, tries to find matching entities by canonical name
+ * 3. Uses found entity IDs as seeds for graphTraversal
+ * 4. Gets facts connected to discovered entities via getFactsForEntity
+ * 5. Assigns graphScore based on hop distance: 1/(2^hop_depth)
+ *    - 0-hop (seed) = 1.0
+ *    - 1-hop = 0.5
+ *    - 2-hop = 0.25
+ *    - 3-hop = 0.125
+ */
+export declare function graphSearch(storage: StorageAdapter, embedding: EmbeddingAdapter, query: string, tenantId: string, _scope: string, _scopeId: string, limit: number, config?: Partial<GraphSearchConfig>): Promise<Candidate[]>;
+//# sourceMappingURL=graph-traversal.d.ts.map

package/src/retrieval/graph-traversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-traversal.d.ts","sourceRoot":"","sources":["graph-traversal.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,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAUD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAMrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAClC,OAAO,CAAC,SAAS,EAAE,CAAC,CAkKtB"}

package/src/retrieval/graph-traversal.js.map

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

package/src/retrieval/graph-traversal.ts

@@ -0,0 +1,235 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+import type { EmbeddingAdapter } from '../adapters/embedding.js';
+import type { Candidate } from './types.js';
+
+export interface GraphSearchConfig {
+  maxDepth: number;       // default 3, max 5
+  maxEntities: number;    // default 200
+  asOf?: Date;            // point-in-time temporal filter
+}
+
+const DEFAULT_MAX_DEPTH = 2;
+const MAX_ALLOWED_DEPTH = 5;
+const DEFAULT_MAX_ENTITIES = 200;
+const MIN_TOKEN_LENGTH = 2;
+
+/** Known entity types to search against for each token */
+const ENTITY_TYPES = ['person', 'organization', 'location', 'topic', 'concept', 'product', 'event'] as const;
+
+/**
+ * Tokenize query into candidate entity names.
+ * Splits on whitespace and dots, filters short words (< 2 chars), lowercases for canonical lookup.
+ * Also preserves dot-separated names as candidate names (e.g., "clean.ai" → tokens ["clean", "ai"] + candidate "clean.ai")
+ */
+export function tokenizeQuery(query: string): string[] {
+  return query
+    .split(/[\s.]+/)
+    .map((t) => t.replace(/[^\w-]/g, ''))
+    .filter((t) => t.length >= MIN_TOKEN_LENGTH)
+    .map((t) => t.toLowerCase());
+}
+
+/**
+ * Graph-based retrieval module.
+ *
+ * 1. Extracts potential entity names from query (simple tokenization)
+ * 2. For each token, tries to find matching entities by canonical name
+ * 3. Uses found entity IDs as seeds for graphTraversal
+ * 4. Gets facts connected to discovered entities via getFactsForEntity
+ * 5. Assigns graphScore based on hop distance: 1/(2^hop_depth)
+ *    - 0-hop (seed) = 1.0
+ *    - 1-hop = 0.5
+ *    - 2-hop = 0.25
+ *    - 3-hop = 0.125
+ */
+export async function graphSearch(
+  storage: StorageAdapter,
+  embedding: EmbeddingAdapter,
+  query: string,
+  tenantId: string,
+  _scope: string,
+  _scopeId: string,
+  limit: number,
+  config?: Partial<GraphSearchConfig>,
+): Promise<Candidate[]> {
+  const maxDepth = Math.min(config?.maxDepth ?? DEFAULT_MAX_DEPTH, MAX_ALLOWED_DEPTH);
+  const maxEntities = Math.min(config?.maxEntities ?? DEFAULT_MAX_ENTITIES, 500);
+
+  const tokens = tokenizeQuery(query);
+  if (tokens.length === 0) return [];
+
+  const seedEntityIds: string[] = [];
+
+  // Build all candidate names to search for (tokens + multi-word combos + original query forms)
+  // NOTE: We intentionally do NOT always include 'user' — it's linked to nearly every fact
+  // and floods results. The 'user' entity is only included if the query mentions "user" or "me".
+  const candidateNames: string[] = [];
+  if (/\b(user|me|my|i)\b/i.test(query)) {
+    candidateNames.push('user');
+  }
+  for (const token of tokens) {
+    if (token.length >= 2) candidateNames.push(token);
+  }
+  // Add multi-word combos from adjacent tokens
+  if (tokens.length >= 2) {
+    for (let i = 0; i < tokens.length - 1; i++) {
+      candidateNames.push(`${tokens[i]} ${tokens[i + 1]}`);
+      // Also try dot-separated form (for entities like "clean.ai")
+      candidateNames.push(`${tokens[i]}.${tokens[i + 1]}`);
+    }
+  }
+  // Add the full lowercased query as a candidate (catches exact entity names)
+  const fullQuery = query.toLowerCase().trim();
+  if (fullQuery.length >= 2 && !candidateNames.includes(fullQuery)) {
+    candidateNames.push(fullQuery);
+  }
+  // Also add dot-stripped version (e.g., "clean.ai" → "clean ai")
+  const dotStripped = fullQuery.replace(/\./g, ' ').replace(/\s+/g, ' ').trim();
+  if (dotStripped !== fullQuery && !candidateNames.includes(dotStripped)) {
+    candidateNames.push(dotStripped);
+  }
+
+  // ONE query to find all matching entities instead of 78 sequential calls
+  try {
+    const { data } = await (storage as any).client
+      .from('entities')
+      .select('id, canonical_name')
+      .eq('tenant_id', tenantId)
+      .in('canonical_name', candidateNames);
+    if (data) {
+      for (const row of data as Array<{ id: string; canonical_name: string }>) {
+        if (!seedEntityIds.includes(row.id)) {
+          seedEntityIds.push(row.id);
+        }
+      }
+    }
+  } catch (err) {
+    console.error('[steno-graph] Batch entity lookup failed, falling back to sequential:', err instanceof Error ? err.message : err);
+    // Fallback: sequential lookups if batch fails
+    const userEntity = await storage.findEntityByCanonicalName(tenantId, 'user', 'person');
+    if (userEntity) seedEntityIds.push(userEntity.id);
+    for (const token of tokens) {
+      for (const entityType of ENTITY_TYPES) {
+        const entity = await storage.findEntityByCanonicalName(tenantId, token, entityType);
+        if (entity && !seedEntityIds.includes(entity.id)) {
+          seedEntityIds.push(entity.id);
+        }
+      }
+    }
+  }
+
+  if (seedEntityIds.length === 0) return [];
+
+  // 2. Graph traversal from seed entities
+  const traversalResult = await storage.graphTraversal({
+    tenantId,
+    entityIds: seedEntityIds,
+    maxDepth,
+    maxEntities,
+    asOf: config?.asOf,
+  });
+
+  if (traversalResult.entities.length === 0) return [];
+
+  // Build hop-depth map from traversal result using BFS from seed entities
+  // via the edge list returned by the traversal
+  const entityHopMap = new Map<string, number>();
+
+  // Initialize seed entities at depth 0
+  for (const entity of traversalResult.entities) {
+    if (seedEntityIds.includes(entity.id)) {
+      entityHopMap.set(entity.id, 0);
+    }
+  }
+
+  // Build adjacency list from edges
+  const adjacency = new Map<string, string[]>();
+  for (const edge of traversalResult.edges) {
+    if (!adjacency.has(edge.sourceId)) adjacency.set(edge.sourceId, []);
+    if (!adjacency.has(edge.targetId)) adjacency.set(edge.targetId, []);
+    adjacency.get(edge.sourceId)!.push(edge.targetId);
+    adjacency.get(edge.targetId)!.push(edge.sourceId);
+  }
+
+  // BFS to compute min hop depth for all reachable entities
+  const queue = [...entityHopMap.keys()];
+  while (queue.length > 0) {
+    const currentId = queue.shift()!;
+    const currentDepth = entityHopMap.get(currentId)!;
+    const neighbors = adjacency.get(currentId) ?? [];
+    for (const neighborId of neighbors) {
+      if (!entityHopMap.has(neighborId)) {
+        entityHopMap.set(neighborId, currentDepth + 1);
+        queue.push(neighborId);
+      }
+    }
+  }
+
+  // Any entity not reached by BFS gets maxDepth
+  for (const entity of traversalResult.entities) {
+    if (!entityHopMap.has(entity.id)) {
+      entityHopMap.set(entity.id, maxDepth);
+    }
+  }
+
+  // 3. Get facts for ALL discovered entities in ONE query via fact_entities join
+  //    This replaces N sequential getFactsForEntity calls with 1 batch query.
+  const candidateMap = new Map<string, Candidate>();
+  const entityIds = traversalResult.entities.map(e => e.id);
+
+  if (entityIds.length > 0) {
+    const PER_ENTITY_LIMIT = Math.max(3, Math.ceil(limit / Math.max(entityIds.length, 1)));
+
+    // Single query: get all facts linked to any of these entities
+    try {
+      const batchResult = await storage.getFactsForEntities(
+        tenantId, entityIds, PER_ENTITY_LIMIT
+      );
+
+      for (const { entityId, fact } of batchResult) {
+        const hopDepth = entityHopMap.get(entityId) ?? maxDepth;
+        const graphScore = 1 / Math.pow(2, hopDepth);
+        const existing = candidateMap.get(fact.id);
+        if (existing) {
+          if (graphScore > existing.graphScore) {
+            existing.graphScore = graphScore;
+          }
+        } else {
+          candidateMap.set(fact.id, {
+            fact,
+            vectorScore: 0,
+            keywordScore: 0,
+            graphScore,
+            recencyScore: 0,
+            salienceScore: 0,
+            temporalScore: 0,
+            source: 'graph' as const,
+          });
+        }
+      }
+    } catch (err) {
+      console.error('[steno-graph] Batch getFactsForEntities failed, falling back to sequential:', err instanceof Error ? err.message : err);
+      // Fallback to sequential if batch not supported
+      for (const entity of traversalResult.entities) {
+        const hopDepth = entityHopMap.get(entity.id) ?? maxDepth;
+        const graphScore = 1 / Math.pow(2, hopDepth);
+        try {
+          const factsResult = await storage.getFactsForEntity(tenantId, entity.id, { limit: 3 });
+          for (const fact of factsResult.data) {
+            if (!candidateMap.has(fact.id)) {
+              candidateMap.set(fact.id, {
+                fact, vectorScore: 0, keywordScore: 0, graphScore,
+                recencyScore: 0, salienceScore: 0, temporalScore: 0, source: 'graph' as const,
+              });
+            }
+          }
+        } catch (err) { console.error('[steno-graph] getFactsForEntity failed for entity:', entity.id, err instanceof Error ? err.message : err); }
+      }
+    }
+  }
+
+  // 4. Return candidates, sorted by graphScore descending, limited
+  return Array.from(candidateMap.values())
+    .sort((a, b) => b.graphScore - a.graphScore)
+    .slice(0, limit);
+}

package/src/retrieval/index.ts

@@ -0,0 +1,13 @@
+export * from './types.js';
+export * from './vector-search.js';
+export { keywordSearch } from './keyword-search.js';
+export { graphSearch, tokenizeQuery } from './graph-traversal.js';
+export type { GraphSearchConfig } from './graph-traversal.js';
+export { matchTriggers, evaluateCondition, cosineSimilarity } from './trigger-matcher.js';
+export { scoreSalience, type SalienceConfig } from './salience-scorer.js';
+export { fuseAndRank, type FusionResult } from './fusion.js';
+export { surfaceContradictions, buildTimeline } from './contradiction-surfacer.js';
+export { search, type SearchConfig } from './search.js';
+export { rerank } from './reranker.js';
+export { compoundSearchSignal } from './compound-search.js';
+export { CachedEmbeddingAdapter } from './embedding-cache.js';

package/src/retrieval/keyword-search.ts

@@ -0,0 +1,39 @@
+import type { StorageAdapter } from '../adapters/storage.js';
+import type { Candidate } from './types.js';
+
+export async function keywordSearch(
+  storage: StorageAdapter,
+  query: string,
+  tenantId: string,
+  scope: string,
+  scopeId: string,
+  limit: number,
+  asOf?: Date,
+): Promise<Candidate[]> {
+  const results = await storage.keywordSearch({
+    query,
+    tenantId,
+    scope,
+    scopeId,
+    limit,
+    validOnly: true,
+    asOf,
+  });
+
+  if (results.length === 0) return [];
+
+  // Normalize rank scores to [0, 1] range.
+  // ts_rank returns arbitrary positive values; normalize by dividing by max.
+  const maxRank = Math.max(...results.map((r) => r.rankScore));
+
+  return results.map((r) => ({
+    fact: r.fact,
+    vectorScore: 0,
+    keywordScore: maxRank > 0 ? r.rankScore / maxRank : 0,
+    graphScore: 0,
+    recencyScore: 0,
+    salienceScore: 0,
+    temporalScore: 0,
+    source: 'keyword' as const,
+  }));
+}

package/src/retrieval/query-expansion.d.ts

@@ -0,0 +1,20 @@
+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 declare function expandQuery(llm: LLMAdapter, query: string): Promise<string[]>;
+/**
+ * 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 declare function expandQueryHeuristic(query: string): string[];
+//# sourceMappingURL=query-expansion.d.ts.map

package/src/retrieval/query-expansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-expansion.d.ts","sourceRoot":"","sources":["query-expansion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAoCnB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA0B5D"}

package/src/retrieval/query-expansion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-expansion.js","sourceRoot":"","sources":["query-expansion.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAe,EACf,KAAa;IAEb,2DAA2D;IAC3D,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC;YAClC;gBACE,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE;;;;;;;sEAOqD;aAC/D;YACD;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,KAAK;aACf;SACF,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,CAAC;QAEjD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC5C,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YACtC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;YACjF,CAAC,CAAC,EAAE,CAAC;QAEP,0CAA0C;QAC1C,OAAO,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;QAClD,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAElC,2CAA2C;IAC3C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACjF,OAAO,CAAC,IAAI,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,+BAA+B;IAC/B,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,kCAAkC;IAClC,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACrH,MAAM,SAAS,GAAG,KAAK;aACpB,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC;aACvC,OAAO,CAAC,yBAAyB,EAAE,EAAE,CAAC;aACtC,OAAO,CAAC,oCAAoC,EAAE,EAAE,CAAC;aACjD,OAAO,CAAC,+BAA+B,EAAE,EAAE,CAAC;aAC5C,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtB,IAAI,SAAS,KAAK,KAAK;YAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC7B,CAAC"}