@mnemoai/core 1.1.0

package/src/retriever.ts

@@ -0,0 +1,1510 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Hybrid Retrieval System
+ * Combines vector search + BM25 full-text search with RRF fusion
+ */
+
+import type { MemoryEntry, MemoryStore, MemorySearchResult } from "./store.js";
+import type { Embedder } from "./embedder.js";
+import {
+import { filterNoise } from "./noise-filter.js";
+import type { DecayEngine, DecayableMemory } from "./decay-engine.js";
+import type { TierManager } from "./tier-manager.js";
+import { toLifecycleMemory, getDecayableFromEntry } from "./smart-metadata.js";
+import { getAdaptiveThreshold, recordResonanceScore } from "./resonance-state.js";
+import { requirePro } from "./license.js";
+
+// Pro: Access tracking & query tracking — graceful degradation without license
+type AccessTracker = { bumpAccess: (id: string) => Promise<void> };
+let _parseAccessMetadata: ((m: any) => { accessCount: number; lastAccessedAt: number }) | null = null;
+let _computeEffectiveHalfLife: ((hl: number, ac: number, la: number, rf?: number, mx?: number) => number) | null = null;
+let _recordQuery: ((...args: any[]) => void) | null = null;
+
+if (requirePro("access-tracking")) {
+  import("./access-tracker.js").then((mod) => {
+    _parseAccessMetadata = mod.parseAccessMetadata;
+    _computeEffectiveHalfLife = mod.computeEffectiveHalfLife;
+  }).catch(() => {});
+}
+if (requirePro("query-tracking")) {
+  import("./query-tracker.js").then((mod) => {
+    _recordQuery = mod.recordQuery;
+  }).catch(() => {});
+}
+
+// Fallbacks for Core mode (no access reinforcement)
+function parseAccessMetadata(m: any): { accessCount: number; lastAccessedAt: number } {
+  if (_parseAccessMetadata) return _parseAccessMetadata(m);
+  return { accessCount: 0, lastAccessedAt: 0 };
+}
+function computeEffectiveHalfLife(hl: number, _ac: number, _la: number, _rf?: number, _mx?: number): number {
+  if (_computeEffectiveHalfLife) return _computeEffectiveHalfLife(hl, _ac, _la, _rf, _mx);
+  return hl; // Core: use fixed half-life without reinforcement
+}
+function recordQuery(data: any): void {
+  _recordQuery?.(data);
+}
+import { appendFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ============================================================================
+// Graphiti Graph Search Integration (3rd retrieval path)
+// ============================================================================
+
+/** Lazy-read env at call time — openclaw.json env may inject after module load. */
+function getGraphitiConfig() {
+  return {
+    enabled: process.env.GRAPHITI_ENABLED === "true",
+    baseUrl: process.env.GRAPHITI_BASE_URL || "http://127.0.0.1:18799",
+    timeoutMs: 3000,
+  };
+}
+
+interface GraphitiFact {
+  fact: string;
+  source_node?: string;
+  target_node?: string;
+  from_node?: string;
+  to_node?: string;
+  created_at?: string;
+  valid_at?: string | null;
+  score?: number | null;
+  degree?: number;
+  source?: "search" | "spread";
+}
+
+/**
+ * Query Graphiti /spread for graph-traversal results.
+ * Returns synthetic MemorySearchResult entries. Fails silently (returns []).
+ */
+async function graphitiSpreadSearch(
+  query: string,
+  groupId: string = "default",
+  searchLimit: number = 3,
+  spreadLimit: number = 3,
+): Promise<Array<MemorySearchResult & { rank: number }>> {
+  const cfg = getGraphitiConfig();
+  if (!cfg.enabled) return [];
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), cfg.timeoutMs);
+    const resp = await fetch(`${cfg.baseUrl}/spread`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query,
+        group_id: groupId,
+        search_limit: searchLimit,
+        spread_depth: 1,
+        spread_limit: spreadLimit,
+      }),
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (!resp.ok) return [];
+
+    const facts: GraphitiFact[] = await resp.json();
+    if (!Array.isArray(facts) || facts.length === 0) return [];
+
+    const seen = new Set<string>();
+    const results: Array<MemorySearchResult & { rank: number }> = [];
+
+    for (let i = 0; i < facts.length; i++) {
+      const f = facts[i];
+      const factText = f.fact?.trim();
+      if (!factText || factText.length < 5 || seen.has(factText)) continue;
+      seen.add(factText);
+
+      const nodes = [f.source_node, f.target_node, f.from_node, f.to_node]
+        .filter(Boolean).join(" → ");
+      const text = nodes ? `[图谱] ${factText} (${nodes})` : `[图谱] ${factText}`;
+
+      const baseScore = f.source === "search" ? 0.75 : 0.45;
+      const degreeBoost = f.degree ? Math.min(0.15, Math.log1p(f.degree) * 0.02) : 0;
+
+      results.push({
+        entry: {
+          id: `graphiti-${i}-${Date.now()}`,
+          text,
+          category: "entity" as const,
+          importance: 0.8,
+          timestamp: f.created_at ? new Date(f.created_at).getTime() : Date.now(),
+          scope: "global",
+        },
+        score: Math.min(1.0, baseScore + degreeBoost),
+        rank: i + 1,
+      });
+    }
+    return results;
+  } catch {
+    return []; // Silent fallback
+  }
+}
+
+// ============================================================================
+// Types & Configuration
+// ============================================================================
+
+export interface RetrievalConfig {
+  mode: "hybrid" | "vector";
+  vectorWeight: number;
+  bm25Weight: number;
+  minScore: number;
+  rerank: "cross-encoder" | "lightweight" | "none";
+  candidatePoolSize: number;
+  /** Recency boost half-life in days (default: 14). Set 0 to disable. */
+  recencyHalfLifeDays: number;
+  /** Max recency boost factor (default: 0.10) */
+  recencyWeight: number;
+  /** Filter noise from results (default: true) */
+  filterNoise: boolean;
+  /** Reranker API key (enables cross-encoder reranking) */
+  rerankApiKey?: string;
+  /** Reranker model (default: jina-reranker-v3) */
+  rerankModel?: string;
+  /** Reranker API endpoint (default: https://api.jina.ai/v1/rerank). */
+  rerankEndpoint?: string;
+  /** Reranker provider format. Determines request/response shape and auth header.
+   *  - "jina" (default): Authorization: Bearer, string[] documents, results[].relevance_score
+   *  - "siliconflow": same format as jina (alias, for clarity)
+   *  - "voyage": Authorization: Bearer, string[] documents, data[].relevance_score
+   *  - "pinecone": Api-Key header, {text}[] documents, data[].score */
+  rerankProvider?: "jina" | "siliconflow" | "voyage" | "pinecone" | "ollama";
+  /**
+   * Length normalization: penalize long entries that dominate via sheer keyword
+   * density. Formula: score *= 1 / (1 + log2(charLen / anchor)).
+   * anchor = reference length (default: 500 chars). Entries shorter than anchor
+   * get a slight boost; longer entries get penalized progressively.
+   * Set 0 to disable. (default: 300)
+   */
+  lengthNormAnchor: number;
+  /**
+   * Hard cutoff after rerank: discard results below this score.
+   * Applied after all scoring stages (rerank, recency, importance, length norm).
+   * Higher = fewer but more relevant results. (default: 0.35)
+   */
+  hardMinScore: number;
+  /**
+   * Time decay half-life in days. Entries older than this lose score.
+   * Different from recencyBoost (additive bonus for new entries):
+   * this is a multiplicative penalty for old entries.
+   * Formula: score *= 0.5 + 0.5 * exp(-ageDays / halfLife)
+   * At halfLife days: ~0.68x. At 2*halfLife: ~0.59x. At 4*halfLife: ~0.52x.
+   * Set 0 to disable. (default: 60)
+   */
+  timeDecayHalfLifeDays: number;
+  /** Access reinforcement factor for time decay half-life extension.
+   *  Higher = stronger reinforcement. 0 to disable. (default: 0.5) */
+  reinforcementFactor: number;
+  /** Maximum half-life multiplier from access reinforcement.
+   *  Prevents frequently accessed memories from becoming immortal. (default: 3) */
+  maxHalfLifeMultiplier: number;
+  /** Enable multi-hop query routing: detected multi-hop queries skip Graphiti
+   *  spread and rely on LanceDB secondary retrieval instead. (default: true) */
+  multiHopRouting: boolean;
+}
+
+export interface RetrievalContext {
+  query: string;
+  limit: number;
+  scopeFilter?: string[];
+  category?: string;
+  /** Retrieval source: "manual" for user-triggered, "auto-recall" for system-initiated, "cli" for CLI commands. */
+  source?: "manual" | "auto-recall" | "cli";
+}
+
+export interface RetrievalResult extends MemorySearchResult {
+  sources: {
+    vector?: { score: number; rank: number };
+    bm25?: { score: number; rank: number };
+    graphiti?: { score: number; rank: number };
+    fused?: { score: number };
+    reranked?: { score: number };
+  };
+}
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
+  mode: "hybrid",
+  vectorWeight: 0.7,
+  bm25Weight: 0.3,
+  minScore: 0.3,
+  rerank: "cross-encoder",
+  candidatePoolSize: 20,
+  recencyHalfLifeDays: 14,
+  recencyWeight: 0.1,
+  filterNoise: true,
+  rerankModel: "jina-reranker-v3",
+  rerankEndpoint: "https://api.jina.ai/v1/rerank",
+  lengthNormAnchor: 500,
+  hardMinScore: 0.35,
+  timeDecayHalfLifeDays: 60,
+  reinforcementFactor: 0.5,
+  maxHalfLifeMultiplier: 3,
+  multiHopRouting: true,
+};
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function clampInt(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+function clamp01(value: number, fallback: number): number {
+  if (!Number.isFinite(value)) return Number.isFinite(fallback) ? fallback : 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+function clamp01WithFloor(value: number, floor: number): number {
+  const safeFloor = clamp01(floor, 0);
+  return Math.max(safeFloor, clamp01(value, safeFloor));
+}
+
+// ============================================================================
+// Rerank Provider Adapters
+// ============================================================================
+
+type RerankProvider = "jina" | "siliconflow" | "voyage" | "pinecone" | "ollama";
+
+interface RerankItem {
+  index: number;
+  score: number;
+}
+
+/** Build provider-specific request headers and body */
+function buildRerankRequest(
+  provider: RerankProvider,
+  apiKey: string,
+  model: string,
+  query: string,
+  documents: string[],
+  topN: number,
+): { headers: Record<string, string>; body: Record<string, unknown> } {
+  switch (provider) {
+    case "pinecone":
+      return {
+        headers: {
+          "Content-Type": "application/json",
+          "Api-Key": apiKey,
+          "X-Pinecone-API-Version": "2024-10",
+        },
+        body: {
+          model,
+          query,
+          documents: documents.map((text) => ({ text })),
+          top_n: topN,
+          rank_fields: ["text"],
+        },
+      };
+    case "voyage":
+      return {
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: {
+          model,
+          query,
+          documents,
+          // Voyage uses top_k (not top_n) to limit reranked outputs.
+          top_k: topN,
+        },
+      };
+    case "ollama":
+      // Ollama rerank API: POST /api/rerank (available since Ollama 0.6+)
+      // Models: jina-reranker-v1-turbo, bge-reranker-v2-m3, etc.
+      // No API key needed for local Ollama
+      return {
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: {
+          model,
+          query,
+          documents,
+          top_n: topN,
+        },
+      };
+    case "siliconflow":
+    case "jina":
+    default:
+      return {
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: {
+          model,
+          query,
+          documents,
+          top_n: topN,
+        },
+      };
+  }
+}
+
+/** Parse provider-specific response into unified format */
+function parseRerankResponse(
+  provider: RerankProvider,
+  data: Record<string, unknown>,
+): RerankItem[] | null {
+  const parseItems = (
+    items: unknown,
+    scoreKeys: Array<"score" | "relevance_score">,
+  ): RerankItem[] | null => {
+    if (!Array.isArray(items)) return null;
+    const parsed: RerankItem[] = [];
+    for (const raw of items as Array<Record<string, unknown>>) {
+      const index =
+        typeof raw?.index === "number" ? raw.index : Number(raw?.index);
+      if (!Number.isFinite(index)) continue;
+      let score: number | null = null;
+      for (const key of scoreKeys) {
+        const value = raw?.[key];
+        const n = typeof value === "number" ? value : Number(value);
+        if (Number.isFinite(n)) {
+          score = n;
+          break;
+        }
+      }
+      if (score === null) continue;
+      parsed.push({ index, score });
+    }
+    return parsed.length > 0 ? parsed : null;
+  };
+
+  switch (provider) {
+    case "ollama": {
+      // Ollama: { results: [{ index, relevance_score }] }
+      // Same format as Jina, but also check data[] for compatibility
+      return (
+        parseItems(data.results, ["relevance_score", "score"]) ??
+        parseItems(data.data, ["relevance_score", "score"])
+      );
+    }
+    case "pinecone": {
+      // Pinecone: usually { data: [{ index, score, ... }] }
+      // Also tolerate results[] with score/relevance_score for robustness.
+      return (
+        parseItems(data.data, ["score", "relevance_score"]) ??
+        parseItems(data.results, ["score", "relevance_score"])
+      );
+    }
+    case "voyage": {
+      // Voyage: usually { data: [{ index, relevance_score }] }
+      // Also tolerate results[] for compatibility across gateways.
+      return (
+        parseItems(data.data, ["relevance_score", "score"]) ??
+        parseItems(data.results, ["relevance_score", "score"])
+      );
+    }
+    case "siliconflow":
+    case "jina":
+    default: {
+      // Jina / SiliconFlow: usually { results: [{ index, relevance_score }] }
+      // Also tolerate data[] for compatibility across gateways.
+      return (
+        parseItems(data.results, ["relevance_score", "score"]) ??
+        parseItems(data.data, ["relevance_score", "score"])
+      );
+    }
+  }
+}
+
+// Cosine similarity for reranking fallback
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) {
+    throw new Error("Vector dimensions must match for cosine similarity");
+  }
+
+  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 norm = Math.sqrt(normA) * Math.sqrt(normB);
+  return norm === 0 ? 0 : dotProduct / norm;
+}
+
+// ============================================================================
+// Memory Retriever
+// ============================================================================
+
+const RETRIEVAL_LOG_PATH = join(homedir(), ".openclaw", "memory", "retrieval-log.jsonl");
+
+export class MemoryRetriever {
+  private accessTracker: AccessTracker | null = null;
+  private tierManager: TierManager | null = null;
+
+  constructor(
+    private store: MemoryStore,
+    private embedder: Embedder,
+    private config: RetrievalConfig = DEFAULT_RETRIEVAL_CONFIG,
+    private decayEngine: DecayEngine | null = null,
+  ) { }
+
+  setAccessTracker(tracker: AccessTracker): void {
+    this.accessTracker = tracker;
+  }
+
+  /**
+   * Resonance check: fast vector probe to see if the query "resonates"
+   * with any high-salience memories. Returns true if at least one memory
+   * has cosine similarity above threshold. This mimics human associative
+   * memory — most inputs don't trigger recall, only resonant ones do.
+   */
+  private async resonanceCheck(
+    query: string,
+    scopeFilter?: string[],
+  ): Promise<{ resonates: boolean; topScore: number }> {
+    try {
+      const queryVector = await this.embedder.embedQuery(query);
+      const threshold = getAdaptiveThreshold();
+      const probeResults = await this.store.vectorSearch(
+        queryVector,
+        3,
+        threshold,
+        scopeFilter,
+      );
+      if (probeResults.length === 0) return { resonates: false, topScore: 0 };
+
+      const topScore = Math.max(...probeResults.map(r => r.score));
+
+      // Record top score for adaptive threshold sliding window
+      recordResonanceScore(topScore);
+
+      // At least one result resonates — check if it has meaningful salience
+      // (not just a random match with a low-importance peripheral memory)
+      for (const r of probeResults) {
+        const importance = r.entry.importance ?? 0.5;
+        const similarity = r.score;
+        // Resonance = strong similarity OR moderate similarity + high importance
+        if (similarity >= 0.55 || (similarity >= threshold && importance >= 0.7)) {
+          return { resonates: true, topScore };
+        }
+      }
+      return { resonates: false, topScore };
+    } catch {
+      // If resonance check fails, allow recall (fail-open)
+      return { resonates: true, topScore: 0 };
+    }
+  }
+
+  /**
+   * Strip metadata blocks from auto-recall queries.
+   * OpenClaw core may pass the full message including Conversation info,
+   * Replied message, and Sender metadata JSON blocks. We only want the
+   * actual user text for semantic search.
+   */
+  private cleanAutoRecallQuery(raw: string): string {
+    // Remove ```json ... ``` code blocks (metadata envelopes)
+    let cleaned = raw.replace(/```json[\s\S]*?```/g, "");
+    // Remove known metadata headers
+    cleaned = cleaned.replace(/Conversation info \(untrusted metadata\):/g, "");
+    cleaned = cleaned.replace(/Sender \(untrusted metadata\):/g, "");
+    cleaned = cleaned.replace(/Replied message \(untrusted, for context\):/g, "");
+    // Remove [Queued messages ...] headers
+    cleaned = cleaned.replace(/\[Queued messages[^\]]*\]/g, "");
+    cleaned = cleaned.replace(/---\s*\nQueued #\d+/g, "");
+    // Collapse whitespace
+    cleaned = cleaned.replace(/\n{3,}/g, "\n").trim();
+    // If nothing left after cleaning, return original (safety)
+    return cleaned.length > 2 ? cleaned : raw;
+  }
+
+  /**
+   * Expand date expressions in query to multiple formats for BM25 matching.
+   * "3月17日" → "3月17日 3/17 03-17 2026-03-17"
+   * "2026年3月17日" → "2026年3月17日 3/17 2026-03-17 03-17"
+   * "昨天/前天/上周" → resolved to absolute dates
+   */
+  private expandDateFormats(query: string): string {
+    const now = new Date();
+    const year = now.getFullYear();
+    let expanded = query;
+
+    // Pattern: X月Y日 or X月Y号
+    expanded = expanded.replace(/(\d{1,2})月(\d{1,2})[日号]/g, (match, m, d) => {
+      const mm = String(m).padStart(2, "0");
+      const dd = String(d).padStart(2, "0");
+      return `${match} ${m}/${d} ${year}-${mm}-${dd} ${mm}-${dd}`;
+    });
+
+    // Pattern: YYYY年X月Y日
+    expanded = expanded.replace(/(\d{4})年(\d{1,2})月(\d{1,2})[日号]/g, (match, y, m, d) => {
+      const mm = String(m).padStart(2, "0");
+      const dd = String(d).padStart(2, "0");
+      return `${match} ${m}/${d} ${y}-${mm}-${dd} ${mm}-${dd}`;
+    });
+
+    // Pattern: X.Y or X/Y (might be dates like 3/17)
+    // Don't expand — these are already BM25-friendly
+
+    // Relative dates
+    const relMap: Record<string, number> = {
+      "今天": 0, "昨天": -1, "前天": -2, "大前天": -3,
+    };
+    for (const [word, offset] of Object.entries(relMap)) {
+      if (expanded.includes(word)) {
+        const d = new Date(now.getTime() + offset * 86400000);
+        const iso = d.toISOString().slice(0, 10);
+        const m = d.getMonth() + 1;
+        const day = d.getDate();
+        expanded = expanded.replace(word, `${word} ${iso} ${m}/${day} ${m}月${day}日`);
+      }
+    }
+
+    return expanded;
+  }
+
+  async retrieve(context: RetrievalContext): Promise<RetrievalResult[]> {
+    let { query, limit, scopeFilter, category, source } = context;
+    // Clean metadata pollution from auto-recall queries
+    if (source === "auto-recall") {
+      query = this.cleanAutoRecallQuery(query);
+    }
+    const safeLimit = clampInt(limit, 1, 20);
+    const t0 = performance.now();
+
+    // ── 共振门控：auto-recall 时先做快速共振检测 ──
+    let resonanceTriggered = false;
+    let resonanceTopScore = 0;
+    if (source === "auto-recall") {
+      const { resonates, topScore: probeTopScore } = await this.resonanceCheck(query, scopeFilter);
+      resonanceTriggered = resonates;
+      resonanceTopScore = probeTopScore;
+      if (!resonates) {
+        // Fire-and-forget tracking for gated-out queries
+        const trackEntry = JSON.stringify({
+          ts: new Date().toISOString(),
+          query: query.substring(0, 200),
+          source: source || "manual",
+          queryType: "gated-out",
+          resonanceScore: resonanceTopScore,
+          resonanceTriggered: false,
+          lancedbCount: 0,
+          graphitiCount: 0,
+          rerankCount: 0,
+          finalCount: 0,
+          totalLatencyMs: Math.round(performance.now() - t0),
+          lancedbLatencyMs: 0,
+          graphitiLatencyMs: 0,
+          rerankLatencyMs: 0,
+        }) + "\n";
+        appendFile(RETRIEVAL_LOG_PATH, trackEntry).catch(() => {});
+        recordQuery({
+          timestamp: new Date().toISOString(),
+          query: query.substring(0, 200),
+          source: (source === "auto-recall" ? "auto" : source || "manual") as "auto" | "manual" | "cli",
+          hitCount: 0,
+          topScore: resonanceTopScore,
+          latency_ms: Math.round(performance.now() - t0),
+          queryType: "gated-out",
+          resonancePass: false,
+        });
+        return []; // 无共振 → 不注入记忆
+      }
+    }
+
+    // ── Multi-hop 检测 ──
+    const isMultiHop = this.config.multiHopRouting && this.isMultiHopQuery(query);
+
+    // ── 并发查询：LanceDB + Graphiti ──
+    const tLance0 = performance.now();
+    const lanceDbPromise = (async () => {
+      if (this.config.mode === "vector" || !this.store.hasFtsSupport) {
+        return this.vectorOnlyRetrieval(query, safeLimit, scopeFilter, category);
+      } else {
+        return this.hybridRetrieval(query, safeLimit, scopeFilter, category);
+      }
+    })();
+
+    const tGraphiti0 = performance.now();
+    const graphitiPromise = (async (): Promise<RetrievalResult[]> => {
+      if (process.env.GRAPHITI_ENABLED !== "true") return [];
+      try {
+        const graphitiBase = process.env.GRAPHITI_BASE_URL || "http://127.0.0.1:18799";
+        const scope = scopeFilter?.[0] || "default";
+        const groupId = scope.startsWith("agent:") ? scope.split(":")[1] || "default" : "default";
+
+        // Multi-hop queries skip spread (spread follows single-entity neighborhoods)
+        const useSpread = source === "auto-recall" && !isMultiHop;
+        const endpoint = useSpread ? "/spread" : "/search";
+        const body = useSpread
+          ? { query, group_id: groupId, search_limit: 3, spread_depth: 1, spread_limit: 3 }
+          : { query, group_id: groupId, limit: Math.min(safeLimit, 5) };
+
+        const resp = await fetch(`${graphitiBase}${endpoint}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(5000),
+        });
+        if (!resp.ok) return [];
+
+        const facts = (await resp.json()) as Array<{
+          fact: string; valid_at?: string; expired_at?: string; created_at?: string;
+          degree?: number; source?: string;
+        }>;
+        return facts
+          .filter(f => f.fact && !f.expired_at)
+          .map((f, i) => {
+            const isSpread = f.source === "spread";
+            const degreeBoost = f.degree ? Math.min(0.15, Math.log1p(f.degree) * 0.03) : 0;
+            const baseScore = isSpread ? 0.45 : 0.65;
+            return {
+              entry: {
+                id: `graphiti-${Date.now()}-${i}`,
+                text: f.fact,
+                vector: [],
+                category: "fact" as const,
+                scope: scope,
+                importance: 0.7,
+                timestamp: f.valid_at ? new Date(f.valid_at).getTime() : Date.now(),
+                metadata: JSON.stringify({ source: isSpread ? "graphiti-spread" : "graphiti", valid_at: f.valid_at, degree: f.degree }),
+              },
+              score: baseScore + (0.01 * (facts.length - i)) + degreeBoost,
+              sources: { graphiti: { rank: i + 1 } },
+            } as RetrievalResult;
+          });
+      } catch {
+        return [];
+      }
+    })();
+
+    const [lanceResults, graphitiResults] = await Promise.all([lanceDbPromise, graphitiPromise]);
+    const tLanceMs = Math.round(performance.now() - tLance0);
+    const tGraphitiMs = Math.round(performance.now() - tGraphiti0);
+
+    // Merge: LanceDB results first, append non-duplicate Graphiti facts
+    const lanceTexts = new Set(lanceResults.map(r => r.entry.text.slice(0, 80)));
+    const uniqueGraphiti = graphitiResults.filter(
+      r => !lanceTexts.has(r.entry.text.slice(0, 80))
+    );
+
+    // ── 跨源统一 Rerank（所有结果都过 reranker）──
+    let merged: RetrievalResult[];
+    let rerankCount = 0;
+    const tRerank0 = performance.now();
+    const combined = [...lanceResults, ...uniqueGraphiti];
+    if (this.config.rerank !== "none" && this.config.rerankApiKey && combined.length > 0) {
+      const queryVector = await this.embedder.embedQuery(query);
+      merged = await this.rerankResults(query, queryVector, combined);
+      rerankCount = merged.length;
+      merged = merged.slice(0, safeLimit);
+    } else {
+      merged = combined.slice(0, safeLimit);
+    }
+    const tRerankMs = Math.round(performance.now() - tRerank0);
+
+    // Record access for reinforcement (manual recall only)
+    if (this.accessTracker && source === "manual" && merged.length > 0) {
+      this.accessTracker.recordAccess(
+        merged.filter(r => !r.entry.id.startsWith("graphiti-")).map(r => r.entry.id)
+      );
+    }
+
+    // ── Fire-and-forget tracking log ──
+    const topScore = merged.length > 0 ? Math.max(...merged.map(r => r.score)) : 0;
+    const trackEntry = JSON.stringify({
+      ts: new Date().toISOString(),
+      query: query.substring(0, 200),
+      source: source || "manual",
+      queryType: isMultiHop ? "multi-hop" : "single",
+      resonanceScore: topScore,
+      resonanceTriggered,
+      lancedbCount: lanceResults.length,
+      graphitiCount: graphitiResults.length,
+      rerankCount,
+      finalCount: merged.length,
+      totalLatencyMs: Math.round(performance.now() - t0),
+      lancedbLatencyMs: tLanceMs,
+      graphitiLatencyMs: tGraphitiMs,
+      rerankLatencyMs: tRerankMs,
+    }) + "\n";
+    appendFile(RETRIEVAL_LOG_PATH, trackEntry).catch(() => {});
+    recordQuery({
+      timestamp: new Date().toISOString(),
+      query: query.substring(0, 200),
+      source: (source === "auto-recall" ? "auto" : source || "manual") as "auto" | "manual" | "cli",
+      hitCount: merged.length,
+      topScore,
+      latency_ms: Math.round(performance.now() - t0),
+      queryType: isMultiHop ? "multi-hop" : "single",
+      resonancePass: true,
+    });
+
+    return merged;
+  }
+
+  private async vectorOnlyRetrieval(
+    query: string,
+    limit: number,
+    scopeFilter?: string[],
+    category?: string,
+  ): Promise<RetrievalResult[]> {
+    const queryVector = await this.embedder.embedQuery(query);
+    const results = await this.store.vectorSearch(
+      queryVector,
+      limit,
+      this.config.minScore,
+      scopeFilter,
+    );
+
+    // Filter by category if specified
+    const filtered = category
+      ? results.filter((r) => r.entry.category === category)
+      : results;
+
+    const mapped = filtered.map(
+      (result, index) =>
+        ({
+          ...result,
+          sources: {
+            vector: { score: result.score, rank: index + 1 },
+          },
+        }) as RetrievalResult,
+    );
+
+    const weighted = this.decayEngine ? mapped : this.applyImportanceWeight(this.applyRecencyBoost(mapped));
+    const lengthNormalized = this.applyLengthNormalization(weighted);
+    const hardFiltered = lengthNormalized.filter(r => r.score >= this.config.hardMinScore);
+    const lifecycleRanked = this.decayEngine
+      ? this.applyDecayBoost(hardFiltered)
+      : this.applyTimeDecay(hardFiltered);
+    const denoised = this.config.filterNoise
+      ? filterNoise(lifecycleRanked, r => r.entry.text)
+      : lifecycleRanked;
+
+    // MMR deduplication: avoid top-k filled with near-identical memories
+    const deduplicated = this.applyMMRDiversity(denoised);
+
+    return deduplicated.slice(0, limit);
+  }
+
+  private async hybridRetrieval(
+    query: string,
+    limit: number,
+    scopeFilter?: string[],
+    category?: string,
+  ): Promise<RetrievalResult[]> {
+    const candidatePoolSize = Math.max(
+      this.config.candidatePoolSize,
+      limit * 2,
+    );
+
+    // Compute query embedding once, reuse for vector search + reranking
+    const queryVector = await this.embedder.embedQuery(query);
+
+    // Run vector, BM25, and Graphiti searches in parallel (3-way)
+    const [vectorResults, bm25Results, graphitiResults] = await Promise.all([
+      this.runVectorSearch(
+        queryVector,
+        candidatePoolSize,
+        scopeFilter,
+        category,
+      ),
+      this.runBM25Search(query, candidatePoolSize, scopeFilter, category),
+      graphitiSpreadSearch(query, "default", 3, 3),
+    ]);
+
+    // Fuse results using RRF (async: validates BM25-only entries exist in store)
+    // Graphiti results merged as 3rd signal
+    const fusedResults = await this.fuseResults(vectorResults, bm25Results, graphitiResults);
+
+    // Apply minimum score threshold
+    const filtered = fusedResults.filter(
+      (r) => r.score >= this.config.minScore,
+    );
+
+    // Rerank if enabled
+    const reranked =
+      this.config.rerank !== "none"
+        ? await this.rerankResults(
+          query,
+          queryVector,
+          filtered.slice(0, limit * 2),
+        )
+        : filtered;
+
+    const temporallyRanked = this.decayEngine
+      ? reranked
+      : this.applyImportanceWeight(this.applyRecencyBoost(reranked));
+
+    // Apply length normalization (penalize long entries dominating via keyword density)
+    const lengthNormalized = this.applyLengthNormalization(temporallyRanked);
+
+    // Hard minimum score cutoff should be based on semantic / lexical relevance.
+    // Lifecycle decay and time-decay are used for re-ranking, not for dropping
+    // otherwise relevant fresh memories.
+    const hardFiltered = lengthNormalized.filter(r => r.score >= this.config.hardMinScore);
+
+    // Apply lifecycle-aware decay or legacy time decay after thresholding
+    const lifecycleRanked = this.decayEngine
+      ? this.applyDecayBoost(hardFiltered)
+      : this.applyTimeDecay(hardFiltered);
+
+    // Filter noise
+    const denoised = this.config.filterNoise
+      ? filterNoise(lifecycleRanked, r => r.entry.text)
+      : lifecycleRanked;
+
+    // MMR deduplication: avoid top-k filled with near-identical memories
+    const deduplicated = this.applyMMRDiversity(denoised);
+
+    return deduplicated.slice(0, limit);
+  }
+
+  private async runVectorSearch(
+    queryVector: number[],
+    limit: number,
+    scopeFilter?: string[],
+    category?: string,
+  ): Promise<Array<MemorySearchResult & { rank: number }>> {
+    const results = await this.store.vectorSearch(
+      queryVector,
+      limit,
+      0.1,
+      scopeFilter,
+    );
+
+    // Filter by category if specified
+    const filtered = category
+      ? results.filter((r) => r.entry.category === category)
+      : results;
+
+    return filtered.map((result, index) => ({
+      ...result,
+      rank: index + 1,
+    }));
+  }
+
+  private async runBM25Search(
+    query: string,
+    limit: number,
+    scopeFilter?: string[],
+    category?: string,
+  ): Promise<Array<MemorySearchResult & { rank: number }>> {
+    // Expand date formats for better BM25 matching
+    const expandedQuery = this.expandDateFormats(query);
+    const results = await this.store.bm25Search(expandedQuery, limit, scopeFilter);
+
+    // Filter by category if specified
+    const filtered = category
+      ? results.filter((r) => r.entry.category === category)
+      : results;
+
+    return filtered.map((result, index) => ({
+      ...result,
+      rank: index + 1,
+    }));
+  }
+
+  private async fuseResults(
+    vectorResults: Array<MemorySearchResult & { rank: number }>,
+    bm25Results: Array<MemorySearchResult & { rank: number }>,
+    graphitiResults: Array<MemorySearchResult & { rank: number }> = [],
+  ): Promise<RetrievalResult[]> {
+    // Create maps for quick lookup
+    const vectorMap = new Map<string, MemorySearchResult & { rank: number }>();
+    const bm25Map = new Map<string, MemorySearchResult & { rank: number }>();
+
+    vectorResults.forEach((result) => {
+      vectorMap.set(result.entry.id, result);
+    });
+
+    bm25Results.forEach((result) => {
+      bm25Map.set(result.entry.id, result);
+    });
+
+    // Get all unique document IDs
+    const allIds = new Set([...vectorMap.keys(), ...bm25Map.keys()]);
+
+    // Calculate RRF scores
+    const fusedResults: RetrievalResult[] = [];
+
+    for (const id of allIds) {
+      const vectorResult = vectorMap.get(id);
+      const bm25Result = bm25Map.get(id);
+
+      // FIX(#15): BM25-only results may be "ghost" entries whose vector data was
+      // deleted but whose FTS index entry lingers until the next index rebuild.
+      // Validate that the entry actually exists in the store before including it.
+      if (!vectorResult && bm25Result) {
+        try {
+          const exists = await this.store.hasId(id);
+          if (!exists) continue; // Skip ghost entry
+        } catch {
+          // If hasId fails, keep the result (fail-open)
+        }
+      }
+
+      // Use the result with more complete data (prefer vector result if both exist)
+      const baseResult = vectorResult || bm25Result!;
+
+      // Use vector similarity as the base score.
+      // BM25 hit acts as a bonus (keyword match confirms relevance).
+      const vectorScore = vectorResult ? vectorResult.score : 0;
+      const bm25Score = bm25Result ? bm25Result.score : 0;
+      // Weighted fusion: vectorWeight/bm25Weight directly control score blending.
+      // BM25 high-score floor (>= 0.75) preserves exact keyword matches
+      // (e.g. API keys, ticket numbers) that may have low vector similarity.
+      const weightedFusion = (vectorScore * this.config.vectorWeight)
+                           + (bm25Score * this.config.bm25Weight);
+      const fusedScore = vectorResult
+        ? clamp01(
+          Math.max(
+            weightedFusion,
+            bm25Score >= 0.75 ? bm25Score * 0.92 : 0,
+          ),
+          0.1,
+        )
+        : clamp01(bm25Result!.score, 0.1);
+
+      fusedResults.push({
+        entry: baseResult.entry,
+        score: fusedScore,
+        sources: {
+          vector: vectorResult
+            ? { score: vectorResult.score, rank: vectorResult.rank }
+            : undefined,
+          bm25: bm25Result
+            ? { score: bm25Result.score, rank: bm25Result.rank }
+            : undefined,
+          fused: { score: fusedScore },
+        },
+      });
+    }
+
+    // Inject Graphiti graph traversal results as 3rd signal.
+    // Synthetic entries (not in LanceDB) — scored slightly lower to avoid dominating,
+    // but provide coverage for relational queries (e.g. "Alice's clients", "who did Bob meet?").
+    for (const gr of graphitiResults) {
+      fusedResults.push({
+        entry: gr.entry,
+        score: gr.score * 0.85,
+        sources: {
+          graphiti: { score: gr.score, rank: gr.rank },
+          fused: { score: gr.score * 0.85 },
+        },
+      });
+    }
+
+    // Sort by fused score descending
+    return fusedResults.sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * Rerank results using cross-encoder API (Jina, Pinecone, or compatible).
+   * Falls back to cosine similarity if API is unavailable or fails.
+   */
+  private async rerankResults(
+    query: string,
+    queryVector: number[],
+    results: RetrievalResult[],
+  ): Promise<RetrievalResult[]> {
+    if (results.length === 0) {
+      return results;
+    }
+
+    // Try cross-encoder rerank via configured provider API
+    console.warn(`[rerank-debug] rerank=${this.config.rerank}, hasKey=${!!this.config.rerankApiKey}, keyPrefix=${String(this.config.rerankApiKey || '').substring(0, 8)}, provider=${this.config.rerankProvider}, model=${this.config.rerankModel}`);
+    const isLocalRerank = this.config.rerankProvider === "ollama";
+    if (this.config.rerank === "cross-encoder" && (this.config.rerankApiKey || isLocalRerank)) {
+      try {
+        const provider = this.config.rerankProvider || "jina";
+        const model = this.config.rerankModel || (isLocalRerank ? "bge-reranker-v2-m3" : "jina-reranker-v3");
+        const endpoint =
+          this.config.rerankEndpoint || (isLocalRerank ? "http://127.0.0.1:11434/api/rerank" : "https://api.jina.ai/v1/rerank");
+        const documents = results.map((r) => r.entry.text);
+
+        // Build provider-specific request
+        const { headers, body } = buildRerankRequest(
+          provider,
+          this.config.rerankApiKey,
+          model,
+          query,
+          documents,
+          results.length,
+        );
+
+        // Timeout: 5 seconds to prevent stalling retrieval pipeline
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeout);
+
+        if (response.ok) {
+          const data = (await response.json()) as Record<string, unknown>;
+
+          // Parse provider-specific response into unified format
+          const parsed = parseRerankResponse(provider, data);
+
+          if (!parsed) {
+            console.warn(
+              "Rerank API: invalid response shape, falling back to cosine",
+            );
+          } else {
+            // Build a Set of returned indices to identify unreturned candidates
+            const returnedIndices = new Set(parsed.map((r) => r.index));
+
+            const reranked = parsed
+              .filter((item) => item.index >= 0 && item.index < results.length)
+              .map((item) => {
+                const original = results[item.index];
+                const floor = this.getRerankPreservationFloor(original, false);
+                // Blend: 60% cross-encoder score + 40% original fused score
+                const blendedScore = clamp01WithFloor(
+                  item.score * 0.6 + original.score * 0.4,
+                  floor,
+                );
+                return {
+                  ...original,
+                  score: blendedScore,
+                  sources: {
+                    ...original.sources,
+                    reranked: { score: item.score },
+                  },
+                };
+              });
+
+            // Keep unreturned candidates with their original scores (slightly penalized)
+            const unreturned = results
+              .filter((_, idx) => !returnedIndices.has(idx))
+              .map(r => ({
+                ...r,
+                score: clamp01WithFloor(
+                  r.score * 0.8,
+                  this.getRerankPreservationFloor(r, true),
+                ),
+              }));
+
+            return [...reranked, ...unreturned].sort(
+              (a, b) => b.score - a.score,
+            );
+          }
+        } else {
+          const errText = await response.text().catch(() => "");
+          console.warn(
+            `Rerank API returned ${response.status}: ${errText.slice(0, 200)}, falling back to cosine`,
+          );
+        }
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          console.warn("Rerank API timed out (5s), falling back to cosine");
+        } else {
+          console.warn("Rerank API failed, falling back to cosine:", error);
+        }
+      }
+    }
+
+    // Fallback: lightweight cosine similarity rerank
+    try {
+      const reranked = results.map((result) => {
+        const cosineScore = cosineSimilarity(queryVector, result.entry.vector);
+        const combinedScore = result.score * 0.7 + cosineScore * 0.3;
+
+        return {
+          ...result,
+          score: clamp01(combinedScore, result.score),
+          sources: {
+            ...result.sources,
+            reranked: { score: cosineScore },
+          },
+        };
+      });
+
+      return reranked.sort((a, b) => b.score - a.score);
+    } catch (error) {
+      console.warn("Reranking failed, returning original results:", error);
+      return results;
+    }
+  }
+
+  private getRerankPreservationFloor(result: RetrievalResult, unreturned: boolean): number {
+    const bm25Score = result.sources.bm25?.score ?? 0;
+
+    // Exact lexical hits (IDs, env vars, ticket numbers) should not disappear
+    // just because a reranker under-scores symbolic or mixed-language queries.
+    if (bm25Score >= 0.75) {
+      return result.score * (unreturned ? 1.0 : 0.95);
+    }
+    if (bm25Score >= 0.6) {
+      return result.score * (unreturned ? 0.95 : 0.9);
+    }
+    return result.score * (unreturned ? 0.8 : 0.5);
+  }
+
+  /**
+   * Apply recency boost: newer memories get a small score bonus.
+   * This ensures corrections/updates naturally outrank older entries
+   * when semantic similarity is close.
+   * Formula: boost = exp(-ageDays / halfLife) * weight
+   */
+  private applyRecencyBoost(results: RetrievalResult[]): RetrievalResult[] {
+    const { recencyHalfLifeDays, recencyWeight } = this.config;
+    if (!recencyHalfLifeDays || recencyHalfLifeDays <= 0 || !recencyWeight) {
+      return results;
+    }
+
+    const now = Date.now();
+    const boosted = results.map((r) => {
+      const ts =
+        r.entry.timestamp && r.entry.timestamp > 0 ? r.entry.timestamp : now;
+      const ageDays = (now - ts) / 86_400_000;
+      const boost = Math.exp(-ageDays / recencyHalfLifeDays) * recencyWeight;
+      return {
+        ...r,
+        score: clamp01(r.score + boost, r.score),
+      };
+    });
+
+    return boosted.sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * Apply importance weighting: memories with higher importance get a score boost.
+   * This ensures critical memories (importance=1.0) outrank casual ones (importance=0.5)
+   * when semantic similarity is close.
+   * Formula: score *= (baseWeight + (1 - baseWeight) * importance)
+   * With baseWeight=0.7: importance=1.0 → ×1.0, importance=0.5 → ×0.85, importance=0.0 → ×0.7
+   */
+  private applyImportanceWeight(results: RetrievalResult[]): RetrievalResult[] {
+    const baseWeight = 0.7;
+    const weighted = results.map((r) => {
+      const importance = r.entry.importance ?? 0.7;
+      const factor = baseWeight + (1 - baseWeight) * importance;
+      return {
+        ...r,
+        score: clamp01(r.score * factor, r.score * baseWeight),
+      };
+    });
+    return weighted.sort((a, b) => b.score - a.score);
+  }
+
+  private applyDecayBoost(results: RetrievalResult[]): RetrievalResult[] {
+    if (!this.decayEngine || results.length === 0) return results;
+
+    const scored = results.map((result) => ({
+      memory: toLifecycleMemory(result.entry.id, result.entry),
+      score: result.score,
+    }));
+
+    this.decayEngine.applySearchBoost(scored);
+
+    const reranked = results.map((result, index) => ({
+      ...result,
+      score: clamp01(scored[index].score, result.score * 0.3),
+    }));
+
+    return reranked.sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * Detect multi-hop queries that involve multiple entities or relationships.
+   * Multi-hop queries benefit from LanceDB secondary retrieval rather than
+   * Graphiti spread (which follows single-entity neighborhoods).
+   */
+  private isMultiHopQuery(query: string): boolean {
+    // Count distinct capitalized words (potential entity names, >= 2 chars)
+    const capitalizedWords = new Set(
+      (query.match(/\b[A-Z\u4e00-\u9fff][a-zA-Z\u4e00-\u9fff]{1,}/g) || [])
+    );
+    if (capitalizedWords.size >= 2) return true;
+
+    // Relationship / comparison patterns
+    const relationPatterns = [
+      /和.{1,20}的关系/,
+      /compared\s+to/i,
+      /difference\s+between/i,
+      /为什么/,
+      /how\s+does\s+.{1,30}\s+relate\s+to/i,
+      /between\s+.{1,30}\s+and\s+/i,
+      /相比/,
+      /区别/,
+      /之间/,
+    ];
+    for (const pat of relationPatterns) {
+      if (pat.test(query)) return true;
+    }
+
+    // Long query with question mark
+    if (query.length > 100 && /[?？]/.test(query)) return true;
+
+    return false;
+  }
+
+  /**
+   * via sheer keyword density and broad semantic coverage.
+   * Short, focused entries (< anchor) get a slight boost.
+   * Long, sprawling entries (> anchor) get penalized.
+   * Formula: score *= 1 / (1 + log2(charLen / anchor))
+   */
+  private applyLengthNormalization(
+    results: RetrievalResult[],
+  ): RetrievalResult[] {
+    const anchor = this.config.lengthNormAnchor;
+    if (!anchor || anchor <= 0) return results;
+
+    const normalized = results.map((r) => {
+      const charLen = r.entry.text.length;
+      const ratio = charLen / anchor;
+      // No penalty for entries at or below anchor length.
+      // Gentle logarithmic decay for longer entries:
+      //   anchor (500) → 1.0, 800 → 0.75, 1000 → 0.67, 1500 → 0.56, 2000 → 0.50
+      // This prevents long, keyword-rich entries from dominating top-k
+      // while keeping their scores reasonable.
+      const logRatio = Math.log2(Math.max(ratio, 1)); // no boost for short entries
+      const factor = 1 / (1 + 0.5 * logRatio);
+      return {
+        ...r,
+        score: clamp01(r.score * factor, r.score * 0.3),
+      };
+    });
+
+    return normalized.sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * Time decay: multiplicative penalty for old entries.
+   * Unlike recencyBoost (additive bonus for new entries), this actively
+   * penalizes stale information so recent knowledge wins ties.
+   * Formula: score *= 0.5 + 0.5 * exp(-ageDays / halfLife)
+   * At 0 days: 1.0x (no penalty)
+   * At halfLife: ~0.68x
+   * At 2*halfLife: ~0.59x
+   * Floor at 0.5x (never penalize more than half)
+   */
+  private applyTimeDecay(results: RetrievalResult[]): RetrievalResult[] {
+    const halfLife = this.config.timeDecayHalfLifeDays;
+    if (!halfLife || halfLife <= 0) return results;
+
+    const now = Date.now();
+    const decayed = results.map((r) => {
+      const ts =
+        r.entry.timestamp && r.entry.timestamp > 0 ? r.entry.timestamp : now;
+      const ageDays = (now - ts) / 86_400_000;
+
+      // Access reinforcement: frequently recalled memories decay slower
+      const { accessCount, lastAccessedAt } = parseAccessMetadata(
+        r.entry.metadata,
+      );
+      const effectiveHL = computeEffectiveHalfLife(
+        halfLife,
+        accessCount,
+        lastAccessedAt,
+        this.config.reinforcementFactor,
+        this.config.maxHalfLifeMultiplier,
+      );
+
+      // floor at 0.5: even very old entries keep at least 50% of their score
+      const factor = 0.5 + 0.5 * Math.exp(-ageDays / effectiveHL);
+      return {
+        ...r,
+        score: clamp01(r.score * factor, r.score * 0.5),
+      };
+    });
+
+    return decayed.sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * Apply lifecycle-aware score adjustment (decay + tier floors).
+   *
+   * This is intentionally lightweight:
+   * - reads tier/access metadata (if any)
+   * - multiplies scores by max(tierFloor, decayComposite)
+   */
+  private applyLifecycleBoost(results: RetrievalResult[]): RetrievalResult[] {
+    if (!this.decayEngine) return results;
+
+    const now = Date.now();
+    const pairs = results.map(r => {
+      const { memory } = getDecayableFromEntry(r.entry);
+      return { r, memory };
+    });
+
+    const scored = pairs.map(p => ({ memory: p.memory, score: p.r.score }));
+    this.decayEngine.applySearchBoost(scored, now);
+
+    const boosted = pairs.map((p, i) => ({ ...p.r, score: scored[i].score }));
+    return boosted.sort((a, b) => b.score - a.score);
+  }
+
+  /**
+   * Record access stats (access_count, last_accessed_at) and apply tier
+   * promotion/demotion for a small number of top results.
+   *
+   * Note: this writes back to LanceDB via delete+readd; keep it bounded.
+   */
+  private async recordAccessAndMaybeTransition(results: RetrievalResult[]): Promise<void> {
+    if (!this.decayEngine && !this.tierManager) return;
+
+    const now = Date.now();
+    const toUpdate = results.slice(0, 3);
+
+    for (const r of toUpdate) {
+      const { memory, meta } = getDecayableFromEntry(r.entry);
+
+      // Update access stats in-memory first
+      const nextAccess = memory.accessCount + 1;
+      meta.access_count = nextAccess;
+      meta.last_accessed_at = now;
+      if (meta.created_at === undefined && meta.createdAt === undefined) {
+        meta.created_at = memory.createdAt;
+      }
+      if (meta.tier === undefined) {
+        meta.tier = memory.tier;
+      }
+      if (meta.confidence === undefined) {
+        meta.confidence = memory.confidence;
+      }
+
+      const updatedMemory: DecayableMemory = {
+        ...memory,
+        accessCount: nextAccess,
+        lastAccessedAt: now,
+      };
+
+      // Tier transition (optional)
+      if (this.decayEngine && this.tierManager) {
+        const ds = this.decayEngine.score(updatedMemory, now);
+        const transition = this.tierManager.evaluate(updatedMemory, ds, now);
+        if (transition) {
+          meta.tier = transition.toTier;
+        }
+      }
+
+      try {
+        await this.store.update(r.entry.id, {
+          metadata: JSON.stringify(meta),
+        });
+      } catch {
+        // best-effort: ignore
+      }
+    }
+  }
+
+  /**
+   * MMR-inspired diversity filter: greedily select results that are both
+   * relevant (high score) and diverse (low similarity to already-selected).
+   *
+   * Uses cosine similarity between memory vectors. If two memories have
+   * cosine similarity > threshold (default 0.92), the lower-scored one
+   * is demoted to the end rather than removed entirely.
+   *
+   * This prevents top-k from being filled with near-identical entries
+   * (e.g. 3 similar "SVG style" memories) while keeping them available
+   * if the pool is small.
+   */
+  private applyMMRDiversity(
+    results: RetrievalResult[],
+    similarityThreshold = 0.85,
+  ): RetrievalResult[] {
+    if (results.length <= 1) return results;
+
+    const selected: RetrievalResult[] = [];
+    const deferred: RetrievalResult[] = [];
+
+    for (const candidate of results) {
+      // Check if this candidate is too similar to any already-selected result
+      const tooSimilar = selected.some((s) => {
+        // Both must have vectors to compare.
+        // LanceDB returns Arrow Vector objects (not plain arrays),
+        // so use .length directly and Array.from() for conversion.
+        const sVec = s.entry.vector;
+        const cVec = candidate.entry.vector;
+        if (!sVec?.length || !cVec?.length) return false;
+        const sArr = Array.from(sVec as Iterable<number>);
+        const cArr = Array.from(cVec as Iterable<number>);
+        const sim = cosineSimilarity(sArr, cArr);
+        return sim > similarityThreshold;
+      });
+
+      if (tooSimilar) {
+        deferred.push(candidate);
+      } else {
+        selected.push(candidate);
+      }
+    }
+    // Append deferred results at the end (available but deprioritized)
+    return [...selected, ...deferred];
+  }
+
+  // Update configuration
+  updateConfig(newConfig: Partial<RetrievalConfig>): void {
+    this.config = { ...this.config, ...newConfig };
+  }
+
+  // Get current configuration
+  getConfig(): RetrievalConfig {
+    return { ...this.config };
+  }
+
+  // Test retrieval system
+  async test(query = "test query"): Promise<{
+    success: boolean;
+    mode: string;
+    hasFtsSupport: boolean;
+    error?: string;
+  }> {
+    try {
+      const results = await this.retrieve({
+        query,
+        limit: 1,
+      });
+
+      return {
+        success: true,
+        mode: this.config.mode,
+        hasFtsSupport: this.store.hasFtsSupport,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        mode: this.config.mode,
+        hasFtsSupport: this.store.hasFtsSupport,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export interface RetrieverLifecycleOptions {
+  decayEngine?: DecayEngine;
+  tierManager?: TierManager;
+}
+
+export function createRetriever(
+  store: MemoryStore,
+  embedder: Embedder,
+  config?: Partial<RetrievalConfig>,
+  options?: { decayEngine?: DecayEngine | null },
+): MemoryRetriever {
+  const fullConfig = { ...DEFAULT_RETRIEVAL_CONFIG, ...config };
+  return new MemoryRetriever(store, embedder, fullConfig, options?.decayEngine ?? null);
+}