@mnemoai/core 1.1.0 → 1.1.1

package/dist/src/retriever.js

@@ -0,0 +1,1006 @@
+import { filterNoise } from "./noise-filter.js";
+import { toLifecycleMemory, getDecayableFromEntry } from "./smart-metadata.js";
+import { getAdaptiveThreshold, recordResonanceScore } from "./resonance-state.js";
+import { requirePro } from "./license.js";
+import { log } from "./logger.js";
+let _parseAccessMetadata = null;
+let _computeEffectiveHalfLife = null;
+let _recordQuery = 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(() => {
+  });
+}
+function parseAccessMetadata(m) {
+  if (_parseAccessMetadata) return _parseAccessMetadata(m);
+  return { accessCount: 0, lastAccessedAt: 0 };
+}
+function computeEffectiveHalfLife(hl, _ac, _la, _rf, _mx) {
+  if (_computeEffectiveHalfLife) return _computeEffectiveHalfLife(hl, _ac, _la, _rf, _mx);
+  return hl;
+}
+function recordQuery(data) {
+  _recordQuery?.(data);
+}
+import { appendFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function getGraphitiConfig() {
+  return {
+    enabled: process.env.GRAPHITI_ENABLED === "true",
+    baseUrl: process.env.GRAPHITI_BASE_URL || "http://127.0.0.1:18799",
+    timeoutMs: 3e3
+  };
+}
+async function graphitiSpreadSearch(query, groupId = "default", searchLimit = 3, spreadLimit = 3) {
+  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 = await resp.json();
+    if (!Array.isArray(facts) || facts.length === 0) return [];
+    const seen = /* @__PURE__ */ new Set();
+    const results = [];
+    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(" \u2192 ");
+      const text = nodes ? `[\u56FE\u8C31] ${factText} (${nodes})` : `[\u56FE\u8C31] ${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",
+          importance: 0.8,
+          timestamp: f.created_at ? new Date(f.created_at).getTime() : Date.now(),
+          scope: "global"
+        },
+        score: Math.min(1, baseScore + degreeBoost),
+        rank: i + 1
+      });
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+const DEFAULT_RETRIEVAL_CONFIG = {
+  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
+};
+function clampInt(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+function clamp01(value, fallback) {
+  if (!Number.isFinite(value)) return Number.isFinite(fallback) ? fallback : 0;
+  return Math.min(1, Math.max(0, value));
+}
+function clamp01WithFloor(value, floor) {
+  const safeFloor = clamp01(floor, 0);
+  return Math.max(safeFloor, clamp01(value, safeFloor));
+}
+function buildRerankRequest(provider, apiKey, model, query, documents, topN) {
+  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":
+      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
+        }
+      };
+  }
+}
+function parseRerankResponse(provider, data) {
+  const parseItems = (items, scoreKeys) => {
+    if (!Array.isArray(items)) return null;
+    const parsed = [];
+    for (const raw of items) {
+      const index = typeof raw?.index === "number" ? raw.index : Number(raw?.index);
+      if (!Number.isFinite(index)) continue;
+      let score = 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": {
+      return parseItems(data.results, ["relevance_score", "score"]) ?? parseItems(data.data, ["relevance_score", "score"]);
+    }
+    case "pinecone": {
+      return parseItems(data.data, ["score", "relevance_score"]) ?? parseItems(data.results, ["score", "relevance_score"]);
+    }
+    case "voyage": {
+      return parseItems(data.data, ["relevance_score", "score"]) ?? parseItems(data.results, ["relevance_score", "score"]);
+    }
+    case "siliconflow":
+    case "jina":
+    default: {
+      return parseItems(data.results, ["relevance_score", "score"]) ?? parseItems(data.data, ["relevance_score", "score"]);
+    }
+  }
+}
+function cosineSimilarity(a, b) {
+  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;
+}
+const RETRIEVAL_LOG_PATH = join(homedir(), ".openclaw", "memory", "retrieval-log.jsonl");
+class MemoryRetriever {
+  constructor(store, embedder, config = DEFAULT_RETRIEVAL_CONFIG, decayEngine = null) {
+    this.store = store;
+    this.embedder = embedder;
+    this.config = config;
+    this.decayEngine = decayEngine;
+  }
+  accessTracker = null;
+  tierManager = null;
+  setAccessTracker(tracker) {
+    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.
+   */
+  async resonanceCheck(query, scopeFilter) {
+    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));
+      recordResonanceScore(topScore);
+      for (const r of probeResults) {
+        const importance = r.entry.importance ?? 0.5;
+        const similarity = r.score;
+        if (similarity >= 0.55 || similarity >= threshold && importance >= 0.7) {
+          return { resonates: true, topScore };
+        }
+      }
+      return { resonates: false, topScore };
+    } catch {
+      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.
+   */
+  cleanAutoRecallQuery(raw) {
+    let cleaned = raw.replace(/```json[\s\S]*?```/g, "");
+    cleaned = cleaned.replace(/Conversation info \(untrusted metadata\):/g, "");
+    cleaned = cleaned.replace(/Sender \(untrusted metadata\):/g, "");
+    cleaned = cleaned.replace(/Replied message \(untrusted, for context\):/g, "");
+    cleaned = cleaned.replace(/\[Queued messages[^\]]*\]/g, "");
+    cleaned = cleaned.replace(/---\s*\nQueued #\d+/g, "");
+    cleaned = cleaned.replace(/\n{3,}/g, "\n").trim();
+    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
+   */
+  expandDateFormats(query) {
+    const now = /* @__PURE__ */ new Date();
+    const year = now.getFullYear();
+    let expanded = query;
+    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}`;
+    });
+    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}`;
+    });
+    const relMap = {
+      "\u4ECA\u5929": 0,
+      "\u6628\u5929": -1,
+      "\u524D\u5929": -2,
+      "\u5927\u524D\u5929": -3
+    };
+    for (const [word, offset] of Object.entries(relMap)) {
+      if (expanded.includes(word)) {
+        const d = new Date(now.getTime() + offset * 864e5);
+        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}\u6708${day}\u65E5`);
+      }
+    }
+    return expanded;
+  }
+  async retrieve(context) {
+    let { query, limit, scopeFilter, category, source } = context;
+    if (source === "auto-recall") {
+      query = this.cleanAutoRecallQuery(query);
+    }
+    const safeLimit = clampInt(limit, 1, 20);
+    const t0 = performance.now();
+    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) {
+        const trackEntry2 = JSON.stringify({
+          ts: (/* @__PURE__ */ 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, trackEntry2).catch(() => {
+        });
+        recordQuery({
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          query: query.substring(0, 200),
+          source: source === "auto-recall" ? "auto" : source || "manual",
+          hitCount: 0,
+          topScore: resonanceTopScore,
+          latency_ms: Math.round(performance.now() - t0),
+          queryType: "gated-out",
+          resonancePass: false
+        });
+        return [];
+      }
+    }
+    const isMultiHop = this.config.multiHopRouting && this.isMultiHopQuery(query);
+    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 () => {
+      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";
+        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(5e3)
+        });
+        if (!resp.ok) return [];
+        const facts = await resp.json();
+        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",
+              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 } }
+          };
+        });
+      } catch {
+        return [];
+      }
+    })();
+    const [lanceResults, graphitiResults] = await Promise.all([lanceDbPromise, graphitiPromise]);
+    const tLanceMs = Math.round(performance.now() - tLance0);
+    const tGraphitiMs = Math.round(performance.now() - tGraphiti0);
+    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))
+    );
+    let merged;
+    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);
+    if (this.accessTracker && source === "manual" && merged.length > 0) {
+      this.accessTracker.recordAccess(
+        merged.filter((r) => !r.entry.id.startsWith("graphiti-")).map((r) => r.entry.id)
+      );
+    }
+    const topScore = merged.length > 0 ? Math.max(...merged.map((r) => r.score)) : 0;
+    const trackEntry = JSON.stringify({
+      ts: (/* @__PURE__ */ 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: (/* @__PURE__ */ new Date()).toISOString(),
+      query: query.substring(0, 200),
+      source: source === "auto-recall" ? "auto" : source || "manual",
+      hitCount: merged.length,
+      topScore,
+      latency_ms: Math.round(performance.now() - t0),
+      queryType: isMultiHop ? "multi-hop" : "single",
+      resonancePass: true
+    });
+    return merged;
+  }
+  async vectorOnlyRetrieval(query, limit, scopeFilter, category) {
+    const queryVector = await this.embedder.embedQuery(query);
+    const results = await this.store.vectorSearch(
+      queryVector,
+      limit,
+      this.config.minScore,
+      scopeFilter
+    );
+    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 }
+        }
+      })
+    );
+    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;
+    const deduplicated = this.applyMMRDiversity(denoised);
+    return deduplicated.slice(0, limit);
+  }
+  async hybridRetrieval(query, limit, scopeFilter, category) {
+    const candidatePoolSize = Math.max(
+      this.config.candidatePoolSize,
+      limit * 2
+    );
+    const queryVector = await this.embedder.embedQuery(query);
+    const [vectorResults, bm25Results, graphitiResults] = await Promise.all([
+      this.runVectorSearch(
+        queryVector,
+        candidatePoolSize,
+        scopeFilter,
+        category
+      ),
+      this.runBM25Search(query, candidatePoolSize, scopeFilter, category),
+      graphitiSpreadSearch(query, "default", 3, 3)
+    ]);
+    const fusedResults = await this.fuseResults(vectorResults, bm25Results, graphitiResults);
+    const filtered = fusedResults.filter(
+      (r) => r.score >= this.config.minScore
+    );
+    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));
+    const lengthNormalized = this.applyLengthNormalization(temporallyRanked);
+    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;
+    const deduplicated = this.applyMMRDiversity(denoised);
+    return deduplicated.slice(0, limit);
+  }
+  async runVectorSearch(queryVector, limit, scopeFilter, category) {
+    const results = await this.store.vectorSearch(
+      queryVector,
+      limit,
+      0.1,
+      scopeFilter
+    );
+    const filtered = category ? results.filter((r) => r.entry.category === category) : results;
+    return filtered.map((result, index) => ({
+      ...result,
+      rank: index + 1
+    }));
+  }
+  async runBM25Search(query, limit, scopeFilter, category) {
+    const expandedQuery = this.expandDateFormats(query);
+    const results = await this.store.bm25Search(expandedQuery, limit, scopeFilter);
+    const filtered = category ? results.filter((r) => r.entry.category === category) : results;
+    return filtered.map((result, index) => ({
+      ...result,
+      rank: index + 1
+    }));
+  }
+  async fuseResults(vectorResults, bm25Results, graphitiResults = []) {
+    const vectorMap = /* @__PURE__ */ new Map();
+    const bm25Map = /* @__PURE__ */ new Map();
+    vectorResults.forEach((result) => {
+      vectorMap.set(result.entry.id, result);
+    });
+    bm25Results.forEach((result) => {
+      bm25Map.set(result.entry.id, result);
+    });
+    const allIds = /* @__PURE__ */ new Set([...vectorMap.keys(), ...bm25Map.keys()]);
+    const fusedResults = [];
+    for (const id of allIds) {
+      const vectorResult = vectorMap.get(id);
+      const bm25Result = bm25Map.get(id);
+      if (!vectorResult && bm25Result) {
+        try {
+          const exists = await this.store.hasId(id);
+          if (!exists) continue;
+        } catch {
+        }
+      }
+      const baseResult = vectorResult || bm25Result;
+      const vectorScore = vectorResult ? vectorResult.score : 0;
+      const bm25Score = bm25Result ? bm25Result.score : 0;
+      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 } : void 0,
+          bm25: bm25Result ? { score: bm25Result.score, rank: bm25Result.rank } : void 0,
+          fused: { score: fusedScore }
+        }
+      });
+    }
+    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 }
+        }
+      });
+    }
+    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.
+   */
+  async rerankResults(query, queryVector, results) {
+    if (results.length === 0) {
+      return results;
+    }
+    log.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);
+        const { headers, body } = buildRerankRequest(
+          provider,
+          this.config.rerankApiKey,
+          model,
+          query,
+          documents,
+          results.length
+        );
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5e3);
+        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();
+          const parsed = parseRerankResponse(provider, data);
+          if (!parsed) {
+            log.warn(
+              "Rerank API: invalid response shape, falling back to cosine"
+            );
+          } else {
+            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);
+              const blendedScore = clamp01WithFloor(
+                item.score * 0.6 + original.score * 0.4,
+                floor
+              );
+              return {
+                ...original,
+                score: blendedScore,
+                sources: {
+                  ...original.sources,
+                  reranked: { score: item.score }
+                }
+              };
+            });
+            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(() => "");
+          log.warn(
+            `Rerank API returned ${response.status}: ${errText.slice(0, 200)}, falling back to cosine`
+          );
+        }
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          log.warn("Rerank API timed out (5s), falling back to cosine");
+        } else {
+          log.warn("Rerank API failed, falling back to cosine:", error);
+        }
+      }
+    }
+    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) {
+      log.warn("Reranking failed, returning original results:", error);
+      return results;
+    }
+  }
+  getRerankPreservationFloor(result, unreturned) {
+    const bm25Score = result.sources.bm25?.score ?? 0;
+    if (bm25Score >= 0.75) {
+      return result.score * (unreturned ? 1 : 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
+   */
+  applyRecencyBoost(results) {
+    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) / 864e5;
+      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
+   */
+  applyImportanceWeight(results) {
+    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);
+  }
+  applyDecayBoost(results) {
+    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).
+   */
+  isMultiHopQuery(query) {
+    const capitalizedWords = new Set(
+      query.match(/\b[A-Z\u4e00-\u9fff][a-zA-Z\u4e00-\u9fff]{1,}/g) || []
+    );
+    if (capitalizedWords.size >= 2) return true;
+    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;
+    }
+    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))
+   */
+  applyLengthNormalization(results) {
+    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;
+      const logRatio = Math.log2(Math.max(ratio, 1));
+      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)
+   */
+  applyTimeDecay(results) {
+    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) / 864e5;
+      const { accessCount, lastAccessedAt } = parseAccessMetadata(
+        r.entry.metadata
+      );
+      const effectiveHL = computeEffectiveHalfLife(
+        halfLife,
+        accessCount,
+        lastAccessedAt,
+        this.config.reinforcementFactor,
+        this.config.maxHalfLifeMultiplier
+      );
+      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)
+   */
+  applyLifecycleBoost(results) {
+    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.
+   */
+  async recordAccessAndMaybeTransition(results) {
+    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);
+      const nextAccess = memory.accessCount + 1;
+      meta.access_count = nextAccess;
+      meta.last_accessed_at = now;
+      if (meta.created_at === void 0 && meta.createdAt === void 0) {
+        meta.created_at = memory.createdAt;
+      }
+      if (meta.tier === void 0) {
+        meta.tier = memory.tier;
+      }
+      if (meta.confidence === void 0) {
+        meta.confidence = memory.confidence;
+      }
+      const updatedMemory = {
+        ...memory,
+        accessCount: nextAccess,
+        lastAccessedAt: now
+      };
+      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 {
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  applyMMRDiversity(results, similarityThreshold = 0.85) {
+    if (results.length <= 1) return results;
+    const selected = [];
+    const deferred = [];
+    for (const candidate of results) {
+      const tooSimilar = selected.some((s) => {
+        const sVec = s.entry.vector;
+        const cVec = candidate.entry.vector;
+        if (!sVec?.length || !cVec?.length) return false;
+        const sArr = Array.from(sVec);
+        const cArr = Array.from(cVec);
+        const sim = cosineSimilarity(sArr, cArr);
+        return sim > similarityThreshold;
+      });
+      if (tooSimilar) {
+        deferred.push(candidate);
+      } else {
+        selected.push(candidate);
+      }
+    }
+    return [...selected, ...deferred];
+  }
+  // Update configuration
+  updateConfig(newConfig) {
+    this.config = { ...this.config, ...newConfig };
+  }
+  // Get current configuration
+  getConfig() {
+    return { ...this.config };
+  }
+  // Test retrieval system
+  async test(query = "test query") {
+    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)
+      };
+    }
+  }
+}
+function createRetriever(store, embedder, config, options) {
+  const fullConfig = { ...DEFAULT_RETRIEVAL_CONFIG, ...config };
+  return new MemoryRetriever(store, embedder, fullConfig, options?.decayEngine ?? null);
+}
+export {
+  DEFAULT_RETRIEVAL_CONFIG,
+  MemoryRetriever,
+  createRetriever
+};
+//# sourceMappingURL=retriever.js.map