@melandlabs/memory-store 1.2.4 → 1.3.0

package/dist/server/cli-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { isFactType, vsaNormalizeVector, vsaAssertSameDim } from '@melandlabs/contracts';
-import { buildMemoryRecordEmbeddingDocument } from '@melandlabs/ai/memory';
-import { ChromaVectorStore } from '@melandlabs/rag';
+import '@melandlabs/ai/memory';
+import { ChromaVectorStore as ChromaVectorStore$1 } from '@melandlabs/rag';
 import { mkdirSync } from 'fs';
 import { dirname } from 'path';
 import { getOpenContextPath } from '@melandlabs/env-config';
@@ -13,6 +13,8 @@ import { applyReflectedConsolidationPlan } from '@melandlabs/memory-consolidatio
 import { isDerivedKind } from '@melandlabs/contracts/derived-fact';
 import { isEntityKind } from '@melandlabs/contracts/entity-edge';
 import { superpose, bind, unbind, cleanup, cosineSimilarity } from '@melandlabs/vsa';
+import { createHash } from 'crypto';
+import { ChromaVectorStore } from '@melandlabs/rag/chroma-vector-store';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -23,27 +25,6 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-function normalizeTimestampToMs(value) {
-  if (!Number.isFinite(value)) {
-    return 0;
-  }
-  if (value < 1e11) {
-    return Math.floor(value * 1e3);
-  }
-  return Math.floor(value);
-}
-function rawMessageToMemoryRecord(message) {
-  return {
-    id: message.messageId,
-    userId: message.userId,
-    timestamp: normalizeTimestampToMs(message.timestamp),
-    text: message.archivedAt ? void 0 : message.content,
-    mediaRefs: message.attachments?.map((item) => item.url).filter(Boolean),
-    embedding: message.embedding,
-    embeddingModel: message.embeddingModel,
-    embeddingContentHash: message.embeddingContentHash
-  };
-}
 var init_contracts = __esm({
   "src/contracts.ts"() {
   }
@@ -64,66 +45,14 @@ function getRawMessagesCollectionName() {
   return process.env.CHROMA_RAW_MESSAGES_COLLECTION || process.env.CHROMA_MEMORY_COLLECTION || DEFAULT_RAW_MESSAGES_COLLECTION;
 }
 function getChromaStore(collectionName) {
-  return new ChromaVectorStore({
+  return new ChromaVectorStore$1({
     url: process.env.CHROMA_URL,
     collectionName
   });
 }
-function normalizeTimestampToMs2(value) {
-  if (!Number.isFinite(value)) {
-    return 0;
-  }
-  if (value < 1e11) {
-    return Math.floor(value * 1e3);
-  }
-  return Math.floor(value);
-}
 function toBooleanValue(value) {
   return value === true || value === "true" || value === 1 || value === "1";
 }
-function rawMessageToChunk(message) {
-  if (!message.embedding || message.embedding.length === 0) {
-    return null;
-  }
-  const record = rawMessageToMemoryRecord(message);
-  const document = buildMemoryRecordEmbeddingDocument(record);
-  if (!document.content) {
-    return null;
-  }
-  return {
-    id: message.messageId,
-    documentId: message.messageId,
-    content: document.content,
-    embedding: message.embedding,
-    metadata: {
-      sourceType: "raw_message",
-      userId: message.userId,
-      platform: message.platform,
-      botId: message.botId,
-      channel: message.channel,
-      person: message.person,
-      timestamp: normalizeTimestampToMs2(message.timestamp),
-      memoryStage: message.memoryStage,
-      embeddingModel: message.embeddingModel,
-      embeddingDimensions: message.embeddingDimensions,
-      contentHash: message.embeddingContentHash,
-      archived: Boolean(message.archivedAt),
-      role: typeof message.metadata?.role === "string" ? message.metadata.role : void 0
-    }
-  };
-}
-async function upsertRawMessagesToChroma(messages) {
-  if (!isRawMessageChromaEnabled() || messages.length === 0) {
-    return 0;
-  }
-  const chunks = messages.map(rawMessageToChunk).filter((chunk) => chunk !== null);
-  if (chunks.length === 0) {
-    return 0;
-  }
-  const store = getChromaStore(getRawMessagesCollectionName());
-  await store.addChunks(chunks);
-  return chunks.length;
-}
 async function searchRawMessagesWithChroma(input) {
   if (!isRawMessageChromaEnabled() || input.queryEmbedding.length === 0) {
     return [];
@@ -325,59 +254,73 @@ var init_raw_message_store = __esm({
   }
 });
 
-// src/embed-on-insert.ts
-async function embedMissingMessages(messages, deps) {
-  if (typeof deps.embedQuery !== "function") {
-    return messages;
+// src/search/unified-search.ts
+init_chroma_memory_index();
+init_raw_message_store();
+
+// src/search/applicability.ts
+var APPLICABILITY_SCOPES = /* @__PURE__ */ new Set([
+  "global",
+  "task",
+  "conversation",
+  "channel",
+  "project",
+  "custom"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidRuntimeContext(message) {
+  throw new TypeError(`memory-store search runtime context: ${message}`);
+}
+function validateApplicabilityContext(value, index) {
+  const path = `applicabilityContexts[${index}]`;
+  if (!isRecord(value)) {
+    invalidRuntimeContext(`${path} must be an object`);
   }
-  const out = [];
-  for (const message of messages) {
-    if (Array.isArray(message.embedding) && message.embedding.length > 0) {
-      out.push(message);
-      continue;
-    }
-    if (typeof message.content !== "string" || message.content.length === 0) {
-      out.push(message);
-      continue;
+  const scope = value.scope;
+  if (typeof scope !== "string" || !APPLICABILITY_SCOPES.has(scope)) {
+    invalidRuntimeContext(`${path}.scope is not supported`);
+  }
+  if (value.key !== void 0 && typeof value.key !== "string") {
+    invalidRuntimeContext(`${path}.key must be a string when provided`);
+  }
+  if (scope !== "global" && (typeof value.key !== "string" || value.key.trim().length === 0)) {
+    invalidRuntimeContext(`${path}.key must be non-empty for scope "${scope}"`);
+  }
+  for (const field of ["validFrom", "validUntil"]) {
+    const boundary = value[field];
+    if (boundary !== void 0 && (typeof boundary !== "number" || !Number.isFinite(boundary))) {
+      invalidRuntimeContext(`${path}.${field} must be a finite epoch-millisecond number`);
     }
-    const vector = await deps.embedQuery({
-      userId: message.userId,
-      query: message.content
-    });
-    out.push({
-      ...message,
-      embedding: vector,
-      embeddingModel: message.embeddingModel ?? "server",
-      embeddingDimensions: vector.length,
-      embeddingUpdatedAt: Date.now()
-    });
   }
-  return out;
 }
-var AUTO_APPLIED_WARNING = {
-  code: "embed_on_insert_auto_applied",
-  message: "Caller set `embedOnInsert` falsy but the active vector backend needs an embedding per row. Server filled in the missing embeddings; pass `embedOnInsert: true` to opt in explicitly."
-};
-async function applyEmbedOnInsertPolicy(incoming, embedOnInsert, unified) {
-  const messages = incoming;
-  const anyMissing = incoming.some((m) => !Array.isArray(m.embedding) || m.embedding.length === 0);
-  const embedderWired = typeof unified?.embedQuery === "function";
-  if (embedOnInsert === true && anyMissing) {
-    return { messages: await embedMissingMessages(messages, unified ?? {}), warnings: [] };
-  }
-  if (embedOnInsert !== true && anyMissing && embedderWired) {
-    return {
-      messages: await embedMissingMessages(messages, unified ?? {}),
-      warnings: [AUTO_APPLIED_WARNING]
-    };
+function resolveSearchRuntimeContext(input, runtimeContext, now = Date.now) {
+  if (runtimeContext === void 0) {
+    return void 0;
   }
-  return { messages, warnings: [] };
+  if (!isRecord(runtimeContext) || !Array.isArray(runtimeContext.applicabilityContexts)) {
+    invalidRuntimeContext("applicabilityContexts must be an array");
+  }
+  for (const [index, context] of runtimeContext.applicabilityContexts.entries()) {
+    validateApplicabilityContext(context, index);
+  }
+  let applicabilityAt;
+  if (input.asOf === void 0) {
+    applicabilityAt = now();
+  } else {
+    const parsed = typeof input.asOf === "string" ? Date.parse(input.asOf) : Number.NaN;
+    if (!Number.isFinite(parsed)) {
+      invalidRuntimeContext("asOf must be a parseable timestamp when a runtime context is supplied");
+    }
+    applicabilityAt = parsed;
+  }
+  return {
+    applicabilityContexts: runtimeContext.applicabilityContexts,
+    applicabilityAt
+  };
 }
 
-// src/search/unified-search.ts
-init_chroma_memory_index();
-init_raw_message_store();
-
 // src/search/reranker.ts
 async function applyReranker(reranker, query, results) {
   if (!reranker || results.length === 0) {
@@ -464,7 +407,7 @@ function normalizeUnifiedMemoryMergeStrategy(value) {
   return value === "rrf" ? "rrf" : "similarity";
 }
 function normalizeUnifiedMemoryReasoningStrategy(value, defaultStrategy = "none") {
-  if (value === "rewrite" || value === "iterative") {
+  if (value === "rewrite" || value === "iterative" || value === "union") {
     return value;
   }
   return defaultStrategy;
@@ -571,6 +514,7 @@ function materializeSignals(lists, hit) {
 function listNameToChannel(name) {
   if (name === "memory-semantic") return "semantic";
   if (name === "memory-bm25" || name === "memory-lexical") return "lexical";
+  if (name === "memory-hybrid") return "hybrid";
   if (name === "memory-entity") return "entity";
   return void 0;
 }
@@ -628,7 +572,6 @@ async function resolveScopePeer(input) {
 
 // src/search/gather-evidence.ts
 var DEFAULT_TIERS = ["summary", "raw", "insight", "knowledge"];
-var MAX_EVIDENCE_CHARS = 600;
 function toSummaryResult(row) {
   const start = typeof row.startTimestamp === "number" ? row.startTimestamp : void 0;
   const end = typeof row.endTimestamp === "number" ? row.endTimestamp : void 0;
@@ -646,7 +589,7 @@ function toSummaryResult(row) {
     }
   };
 }
-async function gatherSummaries(deps, input, limit, threshold, logger, peerPeers) {
+async function gatherSummaries(deps, input, limit, threshold, logger, peerPeers, runtimeContext) {
   if (typeof deps.searchSummaries !== "function") {
     return { hits: [], warnings: [] };
   }
@@ -659,7 +602,8 @@ async function gatherSummaries(deps, input, limit, threshold, logger, peerPeers)
       limit,
       threshold,
       authToken: input.authToken,
-      ...peerPeers.length > 0 ? { peers: peerPeers } : {}
+      ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+      ...runtimeContext ?? {}
     });
     const hits = rows.map(toSummaryResult);
     return { hits, warnings: [] };
@@ -677,12 +621,6 @@ async function gatherSummaries(deps, input, limit, threshold, logger, peerPeers)
     };
   }
 }
-function truncate(input, max = MAX_EVIDENCE_CHARS) {
-  if (input.length <= max) {
-    return input;
-  }
-  return `${input.slice(0, max - 1)}\u2026`;
-}
 function buildSynthesisPrompt(input) {
   const grouped = /* @__PURE__ */ new Map();
   for (const item of input.evidence) {
@@ -696,9 +634,10 @@ function buildSynthesisPrompt(input) {
     if (items.length === 0) {
       continue;
     }
-    const lines = items.map(
-      (item, index) => `  [${index + 1}] (${item.id}, score=${item.score.toFixed(4)}) ${item.snippet}`
-    );
+    const lines = items.map((item, index) => {
+      const factSource = typeof item.metadata?.source === "string" && item.metadata.source.length > 0 ? item.metadata.source : item.source ?? "unknown";
+      return `  [${index + 1}] (${item.id}, source=${factSource}, score=${item.score.toFixed(4)}) ${item.snippet}`;
+    });
     sections.push(`## ${tier}
 ${lines.join("\n")}`);
   }
@@ -780,12 +719,15 @@ function coerceAnswer(text, schema) {
   return text;
 }
 async function synthesizeAnswer(input) {
-  const { query, hits, responseSchema, deps, logger } = input;
-  const evidence = hits.map((hit) => ({
-    id: hit.id,
-    source: mapHitToTier(hit),
-    snippet: truncate(hit.content),
-    score: hit.similarity
+  const { query, responseSchema, deps, logger } = input;
+  const evidence = input.evidence.map((item) => ({
+    id: item.id,
+    source: mapEvidenceSourceToTier(item.source),
+    snippet: item.snippet,
+    score: item.score,
+    // Forward per-fact provenance (e.g. `metadata.source` from
+    // `opencontext add --source`) so the synthesis prompt can cite it.
+    metadata: item.metadata
   }));
   const warnings = [];
   const complete = deps.reasoning?.complete;
@@ -816,21 +758,10 @@ async function synthesizeAnswer(input) {
     return { answer: "", warnings };
   }
 }
-function mapHitToTier(hit) {
-  const tierMarker = hit.metadata?.tier;
-  if (tierMarker === "summary") {
-    return "summary";
-  }
-  if (hit.type === "memory") {
-    return "raw";
-  }
-  if (hit.type === "insight") {
-    return "insight";
-  }
-  if (hit.type === "knowledge") {
-    return "knowledge";
-  }
-  return hit.type;
+function mapEvidenceSourceToTier(source) {
+  if (source === "memory") return "raw";
+  if (source === "insights") return "insight";
+  return source;
 }
 async function resolveSearchScopePeers(input) {
   return resolveScopePeer({
@@ -854,7 +785,7 @@ function deriveEntityKeywords(query) {
   }
   return out.slice(0, 16);
 }
-async function runEntitySearchForQuery(deps, input, limit, logger, peerPeers = []) {
+async function runEntitySearchForQuery(deps, input, limit, logger, peerPeers = [], runtimeContext) {
   if (typeof deps.entitySearch !== "function") {
     return [];
   }
@@ -872,7 +803,8 @@ async function runEntitySearchForQuery(deps, input, limit, logger, peerPeers = [
           keywords,
           limit: Math.ceil(limit / filters.length),
           botId,
-          ...peerPeers.length > 0 ? { peers: peerPeers } : {}
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+          ...runtimeContext ?? {}
         })
       )
     )).flat();
@@ -960,6 +892,16 @@ function filterByDateRange(items, dateFrom, dateTo) {
     return true;
   });
 }
+function warnApplicabilityNotEnforced(warnings) {
+  if (warnings.some((warning) => warning.code === "memory_applicability_not_enforced")) {
+    return;
+  }
+  warnings.push({
+    source: "memory",
+    code: "memory_applicability_not_enforced",
+    message: "Built-in raw-message retrieval was skipped because it cannot enforce the supplied applicability context. Configure an applicability-aware raw-message provider."
+  });
+}
 async function embedQueryVariant(embedQuery, input, query) {
   return embedQuery({
     userId: input.userId,
@@ -967,10 +909,29 @@ async function embedQueryVariant(embedQuery, input, query) {
     authToken: input.authToken
   });
 }
-async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger, peerPeers = []) {
+async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger, peerPeers, warnings, runtimeContext) {
   const filters = input.botIds && input.botIds.length > 0 ? input.botIds.map((botId) => ({ botId })) : [{}];
   let semantic = [];
-  if (isRawMessageChromaEnabled()) {
+  if (typeof deps.searchRawMessagesAnn === "function") {
+    const searchRawMessagesAnn = deps.searchRawMessagesAnn;
+    const factTypes = input.factTypes?.length ? input.factTypes : void 0;
+    const includeDeprecated = input.includeDeprecated === true;
+    semantic = (await Promise.all(
+      filters.map(
+        (filter) => searchRawMessagesAnn({
+          userId: input.userId,
+          queryEmbedding,
+          limit,
+          threshold,
+          botId: "botId" in filter ? filter.botId : void 0,
+          includeDeprecated,
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+          ...factTypes ? { factTypes } : {},
+          ...runtimeContext ?? {}
+        })
+      )
+    )).flat().filter(isRawMemorySemanticResult).map(toMemoryResult);
+  } else if (runtimeContext === void 0 && isRawMessageChromaEnabled()) {
     try {
       semantic = (await Promise.all(
         filters.map((filter) => {
@@ -995,24 +956,12 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
         error
       );
     }
-  } else if (typeof deps.searchRawMessagesAnn === "function") {
-    const searchRawMessagesAnn = deps.searchRawMessagesAnn;
-    const factTypes = input.factTypes?.length ? input.factTypes : void 0;
-    semantic = (await Promise.all(
-      filters.map(
-        (filter) => searchRawMessagesAnn({
-          userId: input.userId,
-          queryEmbedding,
-          limit,
-          threshold,
-          botId: "botId" in filter ? filter.botId : void 0,
-          ...peerPeers.length > 0 ? { peers: peerPeers } : {},
-          ...factTypes ? { factTypes } : {}
-        })
-      )
-    )).flat().filter(isRawMemorySemanticResult).map(toMemoryResult);
   }
-  if (semantic.length === 0) {
+  if (semantic.length === 0 && runtimeContext !== void 0) {
+    warnApplicabilityNotEnforced(warnings);
+    return [];
+  }
+  if (semantic.length === 0 && typeof deps.searchRawMessagesAnn !== "function") {
     try {
       const { getRawMessageManager: getRawMessageManager2 } = await Promise.resolve().then(() => (init_raw_message_store(), raw_message_store_exports));
       const manager2 = await getRawMessageManager2();
@@ -1023,6 +972,7 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
           queryEmbedding,
           limit,
           threshold,
+          includeDeprecated: input.includeDeprecated === true,
           ...peerPeers.length > 0 ? { peers: peerPeers } : {},
           ...factTypes ? { factTypes } : {}
         });
@@ -1052,6 +1002,18 @@ function mergeByMaxScore(lists) {
   }
   return Array.from(best.values()).sort((a, b) => b.similarity - a.similarity);
 }
+function dedupeChannelByParent(hits) {
+  const strongest = /* @__PURE__ */ new Map();
+  for (const hit of hits) {
+    const sourceMessageId = hit.metadata?.sourceMessageId;
+    const parentId = typeof sourceMessageId === "string" && sourceMessageId.length > 0 ? sourceMessageId : hit.id;
+    const normalized = hit.type === "memory" && hit.id !== parentId ? { ...hit, id: parentId } : hit;
+    const key = `${normalized.type}:${parentId}`;
+    const current = strongest.get(key);
+    if (!current || normalized.similarity > current.similarity) strongest.set(key, normalized);
+  }
+  return [...strongest.values()].sort((a, b) => b.similarity - a.similarity);
+}
 function toIterativeRecallCandidate(hit) {
   return {
     id: hit.id,
@@ -1060,7 +1022,7 @@ function toIterativeRecallCandidate(hit) {
     metadata: hit.metadata
   };
 }
-async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger, peerPeers = []) {
+async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger, peerPeers, warnings, runtimeContext) {
   if (keywords.length === 0) {
     return [];
   }
@@ -1069,6 +1031,7 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
       const filters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
       const searchRawMessagesLexical = deps.searchRawMessagesLexical;
       const factTypes = input.factTypes?.length ? input.factTypes : void 0;
+      const includeDeprecated = input.includeDeprecated === true;
       return (await Promise.all(
         filters.map(
           (botId) => searchRawMessagesLexical({
@@ -1076,8 +1039,10 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
             keywords,
             limit: Math.ceil(limit / filters.length),
             botId,
+            includeDeprecated,
             ...peerPeers.length > 0 ? { peers: peerPeers } : {},
-            ...factTypes ? { factTypes } : {}
+            ...factTypes ? { factTypes } : {},
+            ...runtimeContext ?? {}
           })
         )
       )).flat().filter(isRawMemorySemanticResult).map((hit) => ({
@@ -1088,10 +1053,15 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
       logger.warn?.("[memory-store] lexical memory search failed:", error);
     }
   }
+  if (runtimeContext !== void 0) {
+    warnApplicabilityNotEnforced(warnings);
+    return [];
+  }
   try {
     const { lexicalSearchRawMessages: lexicalSearchRawMessages2 } = await Promise.resolve().then(() => (init_sqlite_raw_message_store(), sqlite_raw_message_store_exports));
     const filters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
     const factTypes = input.factTypes?.length ? input.factTypes : void 0;
+    const includeDeprecated = input.includeDeprecated === true;
     return (await Promise.all(
       filters.map(
         (botId) => lexicalSearchRawMessages2({
@@ -1099,6 +1069,7 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
           keywords,
           limit: Math.ceil(limit / filters.length),
           botId,
+          includeDeprecated,
           ...factTypes ? { factTypes } : {}
         })
       )
@@ -1129,7 +1100,9 @@ function searchInputToUnified(input) {
     mergeStrategy: input.mergeStrategy,
     peerFilter: input.peerFilter,
     reasoningStrategy: input.reasoningStrategy,
-    factTypes: input.factTypes
+    factTypes: input.factTypes,
+    includeRetrievalDiagnostics: input.includeRetrievalDiagnostics,
+    includeDeprecated: input.includeDeprecated
   };
 }
 function mapHitToEvidenceSource(hit) {
@@ -1157,8 +1130,8 @@ function createUnifiedSearch(deps = {}) {
     }
     return normalizeUnifiedMemoryReasoningStrategy(deps.reasoning?.defaultStrategy, "none");
   }
-  async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo, peerPeers = []) {
-    if (reasoningStrategy === "iterative" && !deps.reasoning?.iterativePlanner) {
+  async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo, peerPeers = [], runtimeContext) {
+    if ((reasoningStrategy === "iterative" || reasoningStrategy === "union") && !deps.reasoning?.iterativePlanner) {
       warnings.push({
         source: "memory",
         code: "memory_iterative_planner_not_configured",
@@ -1174,7 +1147,8 @@ function createUnifiedSearch(deps = {}) {
       });
       if (reasoningInfo) reasoningInfo.degraded = true;
     }
-    if (reasoningStrategy === "iterative" && deps.reasoning?.iterativePlanner) {
+    let unionEvidence = null;
+    if ((reasoningStrategy === "iterative" || reasoningStrategy === "union") && deps.reasoning?.iterativePlanner) {
       const planner = deps.reasoning.iterativePlanner;
       const result = await planner.plan({
         query: input.query,
@@ -1189,7 +1163,9 @@ function createUnifiedSearch(deps = {}) {
               keywords2,
               limit,
               logger,
-              peerPeers
+              peerPeers,
+              warnings,
+              runtimeContext
             );
             let semanticHits = [];
             if (typeof deps.embedQuery === "function") {
@@ -1203,7 +1179,9 @@ function createUnifiedSearch(deps = {}) {
                   limit,
                   threshold,
                   logger,
-                  peerPeers
+                  peerPeers,
+                  warnings,
+                  runtimeContext
                 );
               } catch (error) {
                 logger.warn?.(
@@ -1231,16 +1209,24 @@ function createUnifiedSearch(deps = {}) {
           reasoningInfo.degraded = true;
         }
       }
-      const semantic2 = result.evidence.map((candidate) => ({
+      const evidence = result.evidence.map((candidate) => ({
         type: "memory",
         id: candidate.id,
         content: candidate.content,
         similarity: candidate.similarity,
-        metadata: { ...candidate.metadata, reasoning: "iterative" }
+        metadata: { ...candidate.metadata, reasoning: reasoningStrategy }
       }));
-      return { semantic: semantic2, lexical: [] };
+      if (reasoningStrategy === "iterative") {
+        return { semantic: evidence, lexical: [] };
+      }
+      unionEvidence = evidence;
     }
     if (typeof deps.embedQuery !== "function") {
+      warnings.push({
+        source: "memory",
+        code: "semantic_unavailable",
+        message: "Semantic search is unavailable because no embedding provider is configured."
+      });
       warnings.push({
         source: "memory",
         code: "memory_lexical_search_fallback",
@@ -1248,7 +1234,16 @@ function createUnifiedSearch(deps = {}) {
       });
       const keywords2 = deriveLexicalKeywords(input.query);
       const lexical2 = filterByDateRange(
-        await runLexicalSearchForKeywords(deps, input, keywords2, limit, logger, peerPeers),
+        await runLexicalSearchForKeywords(
+          deps,
+          input,
+          keywords2,
+          limit,
+          logger,
+          peerPeers,
+          warnings,
+          runtimeContext
+        ),
         input.dateFrom,
         input.dateTo
       );
@@ -1256,6 +1251,26 @@ function createUnifiedSearch(deps = {}) {
     }
     let semantic = [];
     const embedQuery = deps.embedQuery;
+    const activeMergeStrategy = normalizeUnifiedMemoryMergeStrategy(
+      input.mergeStrategy ?? deps.reasoning?.defaultMergeStrategy ?? "rrf"
+    );
+    if (reasoningStrategy === "none" && activeMergeStrategy === "rrf" && input.threshold === void 0 && typeof deps.searchRawMessagesHybrid === "function") {
+      const queryEmbedding = await embedQueryVariant(embedQuery, input, input.query);
+      const filters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
+      const hybrid = (await Promise.all(
+        filters.map(
+          (botId) => deps.searchRawMessagesHybrid?.({
+            userId: input.userId,
+            query: input.query,
+            queryEmbedding,
+            limit: Math.ceil(limit / filters.length),
+            botId,
+            ...runtimeContext ?? {}
+          })
+        )
+      )).flatMap((items) => items ?? []).filter(isRawMemorySemanticResult).map(toMemoryResult);
+      return { semantic: [], lexical: [], hybrid: filterByDateRange(hybrid, input.dateFrom, input.dateTo) };
+    }
     if (reasoningStrategy === "rewrite" && deps.reasoning?.queryRewriter) {
       try {
         const variants = await deps.reasoning.queryRewriter.rewrite({
@@ -1274,7 +1289,17 @@ function createUnifiedSearch(deps = {}) {
         );
         const lists = await Promise.all(
           embeddings.map(
-            (embedding) => runSemanticSearchForEmbedding(deps, input, embedding, limit, threshold, logger, peerPeers)
+            (embedding) => runSemanticSearchForEmbedding(
+              deps,
+              input,
+              embedding,
+              limit,
+              threshold,
+              logger,
+              peerPeers,
+              warnings,
+              runtimeContext
+            )
           )
         );
         semantic = mergeByMaxScore(lists);
@@ -1297,7 +1322,9 @@ function createUnifiedSearch(deps = {}) {
         limit,
         threshold,
         logger,
-        peerPeers
+        peerPeers,
+        warnings,
+        runtimeContext
       );
     }
     let lexical = [];
@@ -1316,7 +1343,8 @@ function createUnifiedSearch(deps = {}) {
                 limit,
                 botId,
                 ...peerPeers.length > 0 ? { peers: peerPeers } : {},
-                ...factTypes ? { factTypes } : {}
+                ...factTypes ? { factTypes } : {},
+                ...runtimeContext ?? {}
               })
             )
           )).flat().filter(isRawMemorySemanticResult).map((hit) => ({
@@ -1342,7 +1370,7 @@ function createUnifiedSearch(deps = {}) {
     let entity;
     if (typeof deps.entitySearch === "function") {
       entity = filterByDateRange(
-        await runEntitySearchForQuery(deps, input, limit, logger, peerPeers),
+        await runEntitySearchForQuery(deps, input, limit, logger, peerPeers, runtimeContext),
         input.dateFrom,
         input.dateTo
       );
@@ -1364,6 +1392,37 @@ function createUnifiedSearch(deps = {}) {
         message: "RRF merge requested but entity search is not configured; falling back to semantic+lexical RRF."
       });
     }
+    if (unionEvidence) {
+      const plannerHits = unionEvidence;
+      const base = mergeByMaxScore([
+        filterByDateRange(semantic, input.dateFrom, input.dateTo),
+        filterByDateRange(lexical, input.dateFrom, input.dateTo)
+      ]);
+      const maxBase = base.length > 0 ? Math.max(...base.map((h) => h.similarity)) : 0;
+      const seen = /* @__PURE__ */ new Set();
+      const merged = [];
+      plannerHits.forEach((hit, i) => {
+        if (seen.has(hit.id)) {
+          return;
+        }
+        seen.add(hit.id);
+        merged.push({
+          ...hit,
+          similarity: maxBase + (plannerHits.length - i) * 1e-6
+        });
+      });
+      for (const hit of base) {
+        if (merged.length >= limit) {
+          break;
+        }
+        if (seen.has(hit.id)) {
+          continue;
+        }
+        seen.add(hit.id);
+        merged.push(hit);
+      }
+      return { semantic: merged.slice(0, limit), lexical: [] };
+    }
     const out = {
       semantic: filterByDateRange(semantic, input.dateFrom, input.dateTo),
       lexical: filterByDateRange(lexical, input.dateFrom, input.dateTo)
@@ -1373,14 +1432,16 @@ function createUnifiedSearch(deps = {}) {
     }
     return out;
   }
-  async function searchUnifiedMemory(input) {
+  async function searchUnifiedMemoryWithRuntime(input, runtimeContext) {
     const query = input.query.trim();
     const sources = normalizeUnifiedMemorySearchSources(input.sources);
     const limit = clampUnifiedMemorySearchLimit(input.limit);
-    const threshold = clampUnifiedMemorySearchThreshold(input.threshold);
     const mergeStrategy = normalizeUnifiedMemoryMergeStrategy(
       input.mergeStrategy ?? deps.reasoning?.defaultMergeStrategy ?? "rrf"
     );
+    const candidateLimit = Math.min(50, Math.max(limit, limit * 4));
+    const threshold = clampUnifiedMemorySearchThreshold(input.threshold);
+    const memoryThreshold = input.threshold === void 0 && mergeStrategy === "rrf" ? Number.NEGATIVE_INFINITY : threshold;
     const reasoningStrategy = resolveReasoningStrategy(input);
     const warnings = [];
     const peerScope = input.peerFilter && input.peerFilter.length > 0 ? await resolveScopePeer({
@@ -1400,23 +1461,46 @@ function createUnifiedSearch(deps = {}) {
       };
     }
     let memorySubs;
+    let retrievalStatus;
     const reasoningInfo = { strategy: reasoningStrategy };
     if (input.dateFrom || input.dateTo) {
       reasoningInfo.dateRange = { from: input.dateFrom, to: input.dateTo };
     }
     if (sources.includes("memory")) {
-      const hasRawProviders = typeof deps.searchRawMessagesAnn === "function" || typeof deps.searchRawMessagesLexical === "function";
+      const hasRawProviders = typeof deps.searchRawMessagesAnn === "function" || typeof deps.searchRawMessagesHybrid === "function" || typeof deps.searchRawMessagesLexical === "function";
       if (isRawMessageStorageAvailable() || hasRawProviders) {
         try {
           memorySubs = await runMemorySource(
             input,
-            limit,
-            threshold,
+            candidateLimit,
+            memoryThreshold,
             warnings,
             reasoningStrategy,
             reasoningInfo,
-            peerPeers
+            peerPeers,
+            runtimeContext
           );
+          memorySubs = {
+            semantic: dedupeChannelByParent(memorySubs.semantic),
+            lexical: dedupeChannelByParent(memorySubs.lexical),
+            ...memorySubs.hybrid ? { hybrid: dedupeChannelByParent(memorySubs.hybrid) } : {},
+            ...memorySubs.entity ? { entity: dedupeChannelByParent(memorySubs.entity) } : {}
+          };
+          if (deps.getRawMessageRetrievalStatus) {
+            retrievalStatus = await deps.getRawMessageRetrievalStatus();
+          }
+          if (memorySubs.semantic.length === 0 && (memorySubs.hybrid?.length ?? 0) === 0 && typeof deps.embedQuery === "function") {
+            let code = "semantic_candidates_empty";
+            let message = "Semantic search was available but returned no candidates.";
+            if (retrievalStatus?.embeddedChildCount === 0) {
+              code = "semantic_unavailable";
+              message = "No embedded RawMessage children are available for semantic search.";
+            } else if (retrievalStatus?.embeddingDimensions && retrievalStatus.indexedDimensions.length > 0 && !retrievalStatus.indexedDimensions.includes(retrievalStatus.embeddingDimensions)) {
+              code = "semantic_dimension_mismatch";
+              message = `Query embedding dimension ${retrievalStatus.embeddingDimensions} does not match indexed child dimensions ${retrievalStatus.indexedDimensions.join(", ")}.`;
+            }
+            warnings.push({ source: "memory", code, message });
+          }
         } catch (error) {
           logger.warn?.("[memory-store] memory source failed:", error);
           warnings.push({
@@ -1439,12 +1523,13 @@ function createUnifiedSearch(deps = {}) {
         const hits = await deps.searchInsights({
           userId: input.userId,
           query: input.query,
-          limit,
+          limit: candidateLimit,
           threshold,
           botIds: input.botIds,
           includeArchived: input.includeArchivedInsights,
           authToken: input.authToken,
-          ...peerPeers.length > 0 ? { peers: peerPeers } : {}
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+          ...runtimeContext ?? {}
         });
         for (const hit of hits) {
           insightHits.push({
@@ -1471,12 +1556,13 @@ function createUnifiedSearch(deps = {}) {
           userId: input.userId,
           query: input.query,
           options: {
-            limit,
+            limit: candidateLimit,
             threshold,
             documentIds: input.documentIds
           },
           authToken: input.authToken,
-          ...peerPeers.length > 0 ? { peers: peerPeers } : {}
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+          ...runtimeContext ?? {}
         });
         for (const hit of hits) {
           knowledgeHits.push(toKnowledgeResult(hit));
@@ -1494,10 +1580,14 @@ function createUnifiedSearch(deps = {}) {
       memorySubs,
       insightHits,
       knowledgeHits,
-      limit,
+      limit: candidateLimit,
       strategy: mergeStrategy
     });
-    const ranked = await applyReranker(deps.reranker, input.query, merged);
+    const rerankerStartedAt = deps.reranker ? Date.now() : void 0;
+    const reranked = await applyReranker(deps.reranker, input.query, merged);
+    const rerankerLatencyMs = rerankerStartedAt === void 0 ? 0 : Date.now() - rerankerStartedAt;
+    const rerankerOrderChanged = Boolean(deps.reranker) && merged.some((hit, index) => hit.id !== reranked[index]?.id);
+    const ranked = reranked.slice(0, limit);
     const output = {
       query: input.query,
       sources,
@@ -1505,28 +1595,51 @@ function createUnifiedSearch(deps = {}) {
       count: ranked.length,
       warnings
     };
+    if (input.includeRetrievalDiagnostics) {
+      output.retrievalDiagnostics = {
+        mergeStrategy,
+        candidateLimit,
+        backend: retrievalStatus?.backend,
+        semanticDegradedReason: retrievalStatus?.semanticDegradedReason ?? warnings.find((warning) => warning.code.startsWith("semantic_"))?.code,
+        candidateCounts: {
+          semantic: memorySubs?.semantic.length ?? 0,
+          lexical: memorySubs?.lexical.length ?? 0,
+          hybrid: memorySubs?.hybrid?.length ?? 0,
+          entity: memorySubs?.entity?.length ?? 0,
+          fused: merged.length,
+          final: ranked.length
+        },
+        channels: {
+          semantic: memorySubs?.semantic ?? [],
+          lexical: memorySubs?.lexical ?? [],
+          ...memorySubs?.hybrid ? { hybrid: memorySubs.hybrid } : {},
+          ...memorySubs?.entity ? { entity: memorySubs.entity } : {}
+        },
+        fusedBeforeRerank: merged,
+        reranker: {
+          enabled: Boolean(deps.reranker),
+          provider: deps.rerankerInfo?.provider,
+          model: deps.rerankerInfo?.model,
+          inputCount: merged.length,
+          outputCount: reranked.length,
+          latencyMs: rerankerLatencyMs,
+          orderChanged: rerankerOrderChanged
+        },
+        final: ranked
+      };
+    }
     if (reasoningInfo && (reasoningInfo.strategy !== "none" || reasoningInfo.dateRange !== void 0)) {
       output.reasoning = reasoningInfo;
     }
     return output;
   }
+  async function searchUnifiedMemory(input) {
+    return searchUnifiedMemoryWithRuntime(input);
+  }
   async function searchRawMemorySemantically(input) {
-    const limit = clampUnifiedMemorySearchLimit(input.limit);
-    const threshold = clampUnifiedMemorySearchThreshold(input.threshold);
-    const reasoningStrategy = resolveReasoningStrategy(input);
-    const mergeStrategy = normalizeUnifiedMemoryMergeStrategy(
-      input.mergeStrategy ?? deps.reasoning?.defaultMergeStrategy ?? "rrf"
-    );
-    const sub = await runMemorySource(input, limit, threshold, [], reasoningStrategy);
-    return mergeAcrossSources({
-      memorySubs: sub,
-      insightHits: [],
-      knowledgeHits: [],
-      limit,
-      strategy: mergeStrategy
-    });
+    return (await searchUnifiedMemory({ ...input, sources: ["memory"] })).results;
   }
-  async function search(input) {
+  async function searchWithResolvedRuntime(input, runtimeContext) {
     const query = input.query.trim();
     const wantsSynthesis = typeof input.synthesize === "boolean" ? input.synthesize : typeof input.synthesize === "object" && input.synthesize !== null;
     const synthesisSchema = typeof input.synthesize === "object" && input.synthesize !== null ? input.synthesize.responseSchema ?? input.responseSchema : input.responseSchema;
@@ -1558,19 +1671,24 @@ function createUnifiedSearch(deps = {}) {
     let unifiedHits = [];
     let sources = input.sources ? [...input.sources] : [];
     let unifiedReasoning;
+    let retrievalDiagnostics;
     if (wantsRawTier || wantsInsightTier || wantsKnowledgeTier) {
       const inferredSources = sources.length > 0 ? sources : [
         ...wantsRawTier ? ["memory"] : [],
         ...wantsInsightTier ? ["insights"] : [],
         ...wantsKnowledgeTier ? ["knowledge"] : []
       ];
-      const unified = await searchUnifiedMemory({
-        ...searchInputToUnified(input),
-        sources: inferredSources.length > 0 ? inferredSources : void 0
-      });
+      const unified = await searchUnifiedMemoryWithRuntime(
+        {
+          ...searchInputToUnified(input),
+          sources: inferredSources.length > 0 ? inferredSources : void 0
+        },
+        runtimeContext
+      );
       unifiedHits = unified.results;
       sources = unified.sources;
       unifiedReasoning = unified.reasoning;
+      retrievalDiagnostics = unified.retrievalDiagnostics;
       warnings.push(...unified.warnings);
     }
     let summaryHits = [];
@@ -1581,7 +1699,8 @@ function createUnifiedSearch(deps = {}) {
         limit,
         threshold,
         logger,
-        peerScope.peers
+        peerScope.peers,
+        runtimeContext
       );
       warnings.push(...summaryBucket.warnings);
       summaryHits = summaryBucket.hits;
@@ -1606,7 +1725,8 @@ function createUnifiedSearch(deps = {}) {
       source: mapHitToEvidenceSource(hit),
       snippet: hit.content,
       score: hit.similarity,
-      timestamp: getCandidateTimestamp(hit.metadata)
+      timestamp: getCandidateTimestamp(hit.metadata),
+      metadata: hit.metadata
     }));
     const base = {
       query,
@@ -1619,12 +1739,15 @@ function createUnifiedSearch(deps = {}) {
     if (unifiedReasoning) {
       base.reasoning = unifiedReasoning;
     }
+    if (retrievalDiagnostics) {
+      base.retrievalDiagnostics = retrievalDiagnostics;
+    }
     if (!wantsSynthesis) {
       return base;
     }
     const { answer, warnings: synthWarnings } = await synthesizeAnswer({
       query,
-      hits,
+      evidence,
       responseSchema: synthesisSchema,
       deps,
       logger
@@ -1633,6 +1756,10 @@ function createUnifiedSearch(deps = {}) {
     base.warnings = [...base.warnings, ...synthWarnings];
     return base;
   }
+  async function search(input, runtimeContext) {
+    const resolvedRuntime = resolveSearchRuntimeContext(input, runtimeContext);
+    return searchWithResolvedRuntime(input, resolvedRuntime);
+  }
   return {
     search,
     searchUnifiedMemory,
@@ -1648,6 +1775,7 @@ function mergeAcrossSources(input) {
     for (const hit of [
       ...memorySubs.semantic,
       ...memorySubs.lexical,
+      ...memorySubs.hybrid ?? [],
       ...input.insightHits,
       ...input.knowledgeHits
     ]) {
@@ -1663,6 +1791,7 @@ function mergeAcrossSources(input) {
   const all = [
     ...memorySubs.semantic,
     ...memorySubs.lexical,
+    ...memorySubs.hybrid ?? [],
     ...memorySubs.entity ?? [],
     ...input.insightHits,
     ...input.knowledgeHits
@@ -1674,6 +1803,9 @@ function buildChannelLists(memorySubs, insightHits, knowledgeHits) {
   const lists = [];
   if (memorySubs.semantic.length > 0) lists.push({ name: "memory-semantic", hits: memorySubs.semantic });
   if (memorySubs.lexical.length > 0) lists.push({ name: "memory-bm25", hits: memorySubs.lexical });
+  if (memorySubs.hybrid && memorySubs.hybrid.length > 0) {
+    lists.push({ name: "memory-hybrid", hits: memorySubs.hybrid });
+  }
   if (memorySubs.entity && memorySubs.entity.length > 0) {
     lists.push({ name: "memory-entity", hits: memorySubs.entity });
   }
@@ -2138,8 +2270,250 @@ function createVsaRecall(storage) {
   };
 }
 
+// ../shared/src/tokens.ts
+var estimateTokens = (text) => {
+  const chineseChars = (text.match(/[\u4e00-\u9fa5]/g) || []).length;
+  const otherChars = text.length - chineseChars;
+  const wordCount = Math.ceil(otherChars / 5);
+  return chineseChars + wordCount;
+};
+
+// ../shared/src/text-chunking.ts
+var RAW_MESSAGE_CHUNK_MAX_TOKENS = 400;
+var RAW_MESSAGE_CHUNK_OVERLAP_TOKENS = 80;
+var PARAGRAPH_BOUNDARIES = ["\n\n", "\r\n\r\n"];
+var SENTENCE_BOUNDARY = /[.!?。！？；;]\s*$/u;
+function largestEndWithinTokenBudget(text, start, maxTokens) {
+  let low = start + 1;
+  let high = text.length;
+  let best = low;
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    if (estimateTokens(text.slice(start, middle)) <= maxTokens) {
+      best = middle;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return best;
+}
+function preferNaturalEnd(text, start, hardEnd) {
+  if (hardEnd >= text.length) return text.length;
+  const searchStart = start + Math.floor((hardEnd - start) * 0.6);
+  const candidate = text.slice(searchStart, hardEnd);
+  for (const boundary of PARAGRAPH_BOUNDARIES) {
+    const index = candidate.lastIndexOf(boundary);
+    if (index >= 0) return searchStart + index + boundary.length;
+  }
+  for (let offset = candidate.length; offset > 0; offset -= 1) {
+    const prefix = candidate.slice(0, offset);
+    if (SENTENCE_BOUNDARY.test(prefix)) return searchStart + offset;
+  }
+  for (let offset = candidate.length - 1; offset >= 0; offset -= 1) {
+    if (/\s/u.test(candidate[offset] ?? "")) return searchStart + offset + 1;
+  }
+  return hardEnd;
+}
+function overlapStart(text, chunkStart, chunkEnd, overlapTokens) {
+  if (overlapTokens <= 0) return chunkEnd;
+  let low = chunkStart + 1;
+  let high = chunkEnd;
+  let best = chunkEnd;
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    if (estimateTokens(text.slice(middle, chunkEnd)) <= overlapTokens) {
+      best = middle;
+      high = middle - 1;
+    } else {
+      low = middle + 1;
+    }
+  }
+  return Math.min(chunkEnd, Math.max(chunkStart + 1, best));
+}
+function chunkTextByEstimatedTokens(text, options = {}) {
+  if (text.length === 0) return [];
+  const maxTokens = Math.max(1, Math.floor(options.maxTokens ?? RAW_MESSAGE_CHUNK_MAX_TOKENS));
+  const overlapTokens = Math.max(0, Math.floor(options.overlapTokens ?? RAW_MESSAGE_CHUNK_OVERLAP_TOKENS));
+  if (overlapTokens >= maxTokens) {
+    throw new Error("overlapTokens must be smaller than maxTokens");
+  }
+  const chunks = [];
+  let start = 0;
+  while (start < text.length) {
+    const hardEnd = largestEndWithinTokenBudget(text, start, maxTokens);
+    const end = preferNaturalEnd(text, start, hardEnd);
+    chunks.push({
+      chunkIndex: chunks.length,
+      startPosition: start,
+      endPosition: end,
+      content: text.slice(start, end)
+    });
+    if (end >= text.length) break;
+    start = overlapStart(text, start, end, overlapTokens);
+  }
+  return chunks;
+}
+
+// src/embed-on-insert.ts
+var AUTO_APPLIED_WARNING = {
+  code: "embed_on_insert_auto_applied",
+  message: "Caller did not explicitly enable embedOnInsert, but an embedding provider is configured. OpenContext generated the missing search embeddings."
+};
+var SEMANTIC_UNAVAILABLE_WARNING = {
+  code: "semantic_index_unavailable",
+  message: "No embedding provider is configured. RawMessage children were indexed for lexical search only; semantic search is unavailable until they are explicitly reindexed."
+};
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function isUsableEmbedding(embedding) {
+  return Boolean(
+    embedding?.length && embedding.every(Number.isFinite) && embedding.some((value) => value !== 0)
+  );
+}
+async function embedText(text, userId, deps) {
+  if (typeof deps.embedQuery !== "function" || text.length === 0) return void 0;
+  const embedding = await deps.embedQuery({ userId, query: text });
+  return isUsableEmbedding(embedding) ? embedding : void 0;
+}
+async function embedMissingMessages(messages, deps) {
+  if (typeof deps.embedQuery !== "function") return messages;
+  const out = [];
+  for (const message of messages) {
+    if (isUsableEmbedding(message.embedding) || !message.content) {
+      out.push(message);
+      continue;
+    }
+    const embedding = await embedText(message.content, message.userId, deps);
+    out.push(
+      embedding ? {
+        ...message,
+        embedding,
+        embeddingModel: message.embeddingModel ?? deps.embeddingInfo?.model ?? "server",
+        embeddingContentHash: sha256(message.content),
+        embeddingDimensions: embedding.length,
+        embeddingUpdatedAt: Date.now()
+      } : message
+    );
+  }
+  return out;
+}
+async function prepareRawMessageIngest(incoming, embedOnInsert, unified) {
+  const deps = unified ?? {};
+  const embedderAvailable = typeof deps.embedQuery === "function" || typeof deps.embedDocuments === "function";
+  const shouldEmbed = embedOnInsert === true || embedderAvailable;
+  const messages = [];
+  const chunks = [];
+  let missingSemanticEmbedding = false;
+  let generatedEmbedding = false;
+  const plans = incoming.map((message) => ({
+    message,
+    pieces: chunkTextByEstimatedTokens(message.content)
+  }));
+  const generatedEmbeddings = /* @__PURE__ */ new Map();
+  const pendingByUser = /* @__PURE__ */ new Map();
+  for (const [messageIndex, plan] of plans.entries()) {
+    for (const piece of plan.pieces) {
+      const canReuseParentEmbedding = plan.pieces.length === 1 && isUsableEmbedding(plan.message.embedding);
+      if (canReuseParentEmbedding || !shouldEmbed || piece.content.length === 0) continue;
+      const pending = pendingByUser.get(plan.message.userId) ?? [];
+      pending.push({ key: `${messageIndex}:${piece.chunkIndex}`, text: piece.content });
+      pendingByUser.set(plan.message.userId, pending);
+    }
+  }
+  for (const [userId, pending] of pendingByUser) {
+    let embeddings;
+    if (typeof deps.embedDocuments === "function") {
+      const batch = await deps.embedDocuments({
+        userId,
+        texts: pending.map((item) => item.text)
+      });
+      if (batch.length !== pending.length) {
+        throw new Error(
+          `Document embedding count mismatch: expected ${pending.length}, received ${batch.length}`
+        );
+      }
+      embeddings = batch.map((embedding) => isUsableEmbedding(embedding) ? embedding : void 0);
+    } else {
+      embeddings = [];
+      for (const item of pending) {
+        embeddings.push(await embedText(item.text, userId, deps));
+      }
+    }
+    for (const [index, item] of pending.entries()) {
+      const embedding = embeddings[index];
+      if (embedding) generatedEmbeddings.set(item.key, embedding);
+    }
+  }
+  for (const [messageIndex, plan] of plans.entries()) {
+    const incomingMessage = plan.message;
+    const pieces = plan.pieces;
+    let message = incomingMessage;
+    for (const piece of pieces) {
+      const contentHash = sha256(piece.content);
+      const canReuseParentEmbedding = pieces.length === 1 && isUsableEmbedding(incomingMessage.embedding);
+      const embedding = canReuseParentEmbedding ? incomingMessage.embedding : generatedEmbeddings.get(`${messageIndex}:${piece.chunkIndex}`);
+      generatedEmbedding = generatedEmbedding || Boolean(embedding && !canReuseParentEmbedding);
+      if (!embedding) missingSemanticEmbedding = true;
+      const embeddingModel = embedding ? canReuseParentEmbedding ? incomingMessage.embeddingModel : deps.embeddingInfo?.model ?? incomingMessage.embeddingModel ?? "server" : void 0;
+      chunks.push({
+        chunkId: `${incomingMessage.messageId}:chunk:${piece.chunkIndex}:${contentHash.slice(0, 16)}`,
+        messageId: incomingMessage.messageId,
+        userId: incomingMessage.userId,
+        chunkIndex: piece.chunkIndex,
+        chunkCount: pieces.length,
+        startPosition: piece.startPosition,
+        endPosition: piece.endPosition,
+        content: piece.content,
+        contentHash,
+        embedding,
+        embeddingModel,
+        embeddingDimensions: embedding?.length,
+        embeddingUpdatedAt: embedding ? Date.now() : void 0
+      });
+      if (pieces.length === 1 && embedding && !incomingMessage.embedding?.length) {
+        message = {
+          ...incomingMessage,
+          embedding,
+          embeddingModel,
+          embeddingContentHash: contentHash,
+          embeddingDimensions: embedding.length,
+          embeddingUpdatedAt: Date.now()
+        };
+      }
+    }
+    messages.push(message);
+  }
+  const warnings = [];
+  if (generatedEmbedding && embedOnInsert !== true) warnings.push(AUTO_APPLIED_WARNING);
+  if (missingSemanticEmbedding) warnings.push(SEMANTIC_UNAVAILABLE_WARNING);
+  return { messages, chunks, warnings };
+}
+
+// src/storage/raw-message-ingest.ts
+async function persistRawMessages(input) {
+  const prepared = await prepareRawMessageIngest(input.messages, input.embedOnInsert, input.unified);
+  let ids;
+  if (typeof input.manager.storeMessagesWithSearchChunks === "function") {
+    ids = await input.manager.storeMessagesWithSearchChunks(prepared.messages, prepared.chunks);
+  } else {
+    const legacyMessages = (input.embedOnInsert === true || typeof input.unified?.embedQuery === "function") && typeof input.unified?.embedQuery === "function" ? await embedMissingMessages(prepared.messages, input.unified) : prepared.messages;
+    if (typeof input.manager.upsertRawMessages === "function") {
+      await input.manager.upsertRawMessages({ userId: input.userId, messages: legacyMessages });
+    } else if (typeof input.manager.storeMessages === "function") {
+      ids = await input.manager.storeMessages(legacyMessages);
+    } else {
+      throw new Error("active raw-message manager exposes no supported write method");
+    }
+  }
+  if (input.externalIndex) {
+    await input.externalIndex.replaceMessages(prepared.messages, prepared.chunks);
+  }
+  return { count: prepared.messages.length, ids, warnings: prepared.warnings };
+}
+
 // src/mcp.ts
-init_chroma_memory_index();
 init_raw_message_store();
 init_sqlite_raw_message_store();
 var DEFAULT_NAME = "@melandlabs/memory-store";
@@ -2152,13 +2526,37 @@ async function startMcpServer(options = {}) {
   const rawStore = createRawMessageStore({
     env: options.env
   });
-  const search = createUnifiedSearch(options.unified);
+  const rawMessageManager = await rawStore.getManager();
+  const search = createUnifiedSearch({
+    ...options.unified,
+    searchRawMessagesLexical: async (input) => {
+      if (typeof rawMessageManager.lexicalSearchMessages !== "function") return [];
+      const results = await rawMessageManager.lexicalSearchMessages(input);
+      return results.filter(Boolean).map((result) => ({
+        id: result.id,
+        content: result.content,
+        similarity: result.similarity,
+        metadata: result.metadata ?? {}
+      }));
+    }
+  });
   const vsaDbPath = resolveSQLiteRawMessageDbPath(options.dbPath);
   const vsaStorage = await getSQLiteVsaStore({ dbPath: vsaDbPath });
   const vsa = createVsaRecall(vsaStorage);
-  server.tool("memory.health", "Returns the health status of the memory store.", async () => ({
-    content: [{ type: "text", text: JSON.stringify({ ok: true }) }]
-  }));
+  server.tool("memory.health", "Returns the health status of the memory store.", async () => {
+    const retrieval = options.unified?.getRawMessageRetrievalStatus ? await options.unified.getRawMessageRetrievalStatus().catch(() => ({
+      backend: "unknown",
+      childCount: 0,
+      embeddedChildCount: 0,
+      indexedDimensions: [],
+      semanticReady: false,
+      lexicalReady: false,
+      semanticDegradedReason: "health_check_failed"
+    })) : void 0;
+    return {
+      content: [{ type: "text", text: JSON.stringify({ ok: true, retrieval }) }]
+    };
+  });
   const searchSchema = {
     userId: z.string(),
     query: z.string().min(1),
@@ -2166,8 +2564,8 @@ async function startMcpServer(options = {}) {
     tiers: z.array(z.enum(["summary", "raw", "insight", "knowledge"])).optional().describe(
       "Per-tier evidence scope for synthesis. Default: ['summary','raw','insight','knowledge']. Ignored when `synthesize` is falsy."
     ),
-    reasoningStrategy: z.enum(["none", "rewrite", "iterative"]).optional().describe(
-      "LLM reasoning strategy. `rewrite` rephrases the query before embedding; `iterative` runs a planner that searches, notes evidence, and searches again. Requires `unified.reasoning.{queryRewriter,iterativePlanner}` to be wired into the server."
+    reasoningStrategy: z.enum(["none", "rewrite", "iterative", "union"]).optional().describe(
+      "LLM reasoning strategy. `rewrite` rephrases the query before embedding; `iterative` runs a planner that searches, notes evidence, and searches again; `union` merges the planner's evidence with the baseline top-k hits (evidence first, deduped, capped at limit). Requires `unified.reasoning.{queryRewriter,iterativePlanner}` to be wired into the server."
     ),
     synthesize: z.union([z.boolean(), z.object({ responseSchema: z.record(z.string(), z.unknown()).optional() })]).optional().describe(
       "Opt-in LLM synthesis. `true` returns `{ answer, evidence, results, warnings }`. `synthesize.responseSchema` extracts `answer` from a JSON payload."
@@ -2176,7 +2574,11 @@ async function startMcpServer(options = {}) {
     // coerces it into `synthesize.responseSchema` when present.
     responseSchema: z.record(z.string(), z.unknown()).optional(),
     limit: z.number().int().min(1).max(50).default(10),
-    threshold: z.number().min(-1).max(1).default(0.7),
+    threshold: z.number().min(-1).max(1).optional().describe(
+      "Optional similarity floor. Omit it to let the default RRF pipeline fuse the full candidate window."
+    ),
+    mergeStrategy: z.enum(["rrf", "similarity"]).optional(),
+    includeRetrievalDiagnostics: z.boolean().optional(),
     botIds: z.array(z.string()).optional(),
     documentIds: z.array(z.string()).optional(),
     includeArchivedInsights: z.boolean().default(false),
@@ -2240,11 +2642,13 @@ async function startMcpServer(options = {}) {
         sources: a.sources,
         limit: a.limit,
         threshold: a.threshold,
+        mergeStrategy: a.mergeStrategy,
+        includeRetrievalDiagnostics: a.includeRetrievalDiagnostics,
         botIds: a.botIds,
         documentIds: a.documentIds,
         authToken: a.authToken,
         includeArchivedInsights: a.includeArchivedInsights,
-        reasoningStrategy: a.reasoningStrategy === "rewrite" || a.reasoningStrategy === "iterative" ? a.reasoningStrategy : void 0,
+        reasoningStrategy: a.reasoningStrategy === "rewrite" || a.reasoningStrategy === "iterative" || a.reasoningStrategy === "union" ? a.reasoningStrategy : void 0,
         ...a.tiers ? { tiers: a.tiers } : {},
         ...wantsSynthesis ? {
           synthesize: {
@@ -2270,37 +2674,24 @@ async function startMcpServer(options = {}) {
       const a = args;
       const manager2 = await rawStore.getManager();
       const incoming = [a.message].map((m) => ({ ...m, userId: m.userId ?? a.userId }));
-      const { messages, warnings } = await applyEmbedOnInsertPolicy(
-        incoming,
-        a.embedOnInsert,
-        options.unified
-      );
-      let result;
-      if (typeof manager2.upsertRawMessages === "function") {
-        result = await manager2.upsertRawMessages({
-          userId: a.userId,
-          messages
-        });
-      } else if (typeof manager2.storeMessages === "function") {
-        const ids = await manager2.storeMessages(messages);
-        result = { inserted: ids.length, ids };
-      } else {
-        throw new Error("active raw-message manager exposes neither upsertRawMessages nor storeMessages");
-      }
-      try {
-        await upsertRawMessagesToChroma(messages);
-      } catch (error) {
-        console.warn("[memory-store/mcp] chroma upsert failed:", error);
-      }
+      const persisted = await persistRawMessages({
+        manager: manager2,
+        userId: a.userId,
+        messages: incoming,
+        embedOnInsert: a.embedOnInsert,
+        unified: options.unified,
+        externalIndex: options.unified?.rawMessageChildIndex
+      });
+      const result = persisted.ids ? { inserted: persisted.ids.length, ids: persisted.ids } : { inserted: persisted.count };
       return {
         content: [
           {
             type: "text",
             text: JSON.stringify({
               ok: true,
-              count: messages.length,
+              count: persisted.count,
               result,
-              ...warnings.length > 0 ? { warnings } : {}
+              ...persisted.warnings.length > 0 ? { warnings: persisted.warnings } : {}
             })
           }
         ]
@@ -2640,7 +3031,17 @@ async function startMcpServer(options = {}) {
   );
   const okfMcpSpecifier = "@melandlabs/okf/mcp";
   const { registerOkfTools } = await import(okfMcpSpecifier);
-  registerOkfTools(server, rawStore);
+  registerOkfTools(server, rawStore, {
+    writeMessages: async (userId, messages) => {
+      await persistRawMessages({
+        manager: rawMessageManager,
+        userId,
+        messages,
+        unified: options.unified,
+        externalIndex: options.unified?.rawMessageChildIndex
+      });
+    }
+  });
   const transport = new StdioServerTransport();
   await server.connect(transport);
   return server;
@@ -2985,6 +3386,121 @@ function createUserVoiceRewriter(options) {
   };
 }
 
+// src/storage/raw-message-child-vector-index.ts
+var RawMessageChildVectorIndex = class {
+  backend;
+  store;
+  catalog;
+  constructor(options) {
+    this.backend = options.backend;
+    this.store = options.store;
+    this.catalog = options.catalog;
+  }
+  async replaceMessages(messages, chunks) {
+    const chunksByMessage = /* @__PURE__ */ new Map();
+    for (const chunk of chunks) {
+      const group = chunksByMessage.get(chunk.messageId) ?? [];
+      group.push(chunk);
+      chunksByMessage.set(chunk.messageId, group);
+    }
+    for (const message of messages) {
+      await this.store.deleteDocument(message.messageId);
+      const vectorChunks = (chunksByMessage.get(message.messageId) ?? []).filter(
+        (chunk) => Boolean(chunk.embedding?.length) && !chunk.embedding?.every((value) => value === 0)
+      ).map((chunk) => ({
+        id: chunk.chunkId,
+        documentId: message.messageId,
+        content: chunk.content,
+        embedding: chunk.embedding,
+        metadata: {
+          userId: message.userId,
+          botId: message.botId,
+          platform: message.platform,
+          timestamp: message.timestamp,
+          chunkIndex: chunk.chunkIndex,
+          chunkCount: chunk.chunkCount,
+          startPosition: chunk.startPosition,
+          endPosition: chunk.endPosition,
+          contentHash: chunk.contentHash,
+          embeddingModel: chunk.embeddingModel
+        }
+      }));
+      if (vectorChunks.length > 0) await this.store.addChunks(vectorChunks);
+    }
+  }
+  async search(input) {
+    const results = input.hybrid && this.store.hybridSearch ? await this.store.hybridSearch({
+      text: input.query ?? "",
+      vector: input.queryEmbedding,
+      limit: input.limit,
+      candidateLimit: input.limit,
+      fusion: "rrf",
+      filter: { userId: input.userId }
+    }) : await this.store.similaritySearch(input.queryEmbedding, input.limit, input.userId);
+    return this.hydrate(results, input);
+  }
+  async getChunkCount() {
+    return this.store.getChunkCount();
+  }
+  async hydrate(results, input) {
+    const matchedChunks = await this.catalog.getRawMessageSearchChunks({
+      chunkIds: results.map((result) => result.id),
+      userId: input.userId
+    });
+    const matchedById = new Map(matchedChunks.map((chunk) => [chunk.chunkId, chunk]));
+    const messageIds = [...new Set(matchedChunks.map((chunk) => chunk.messageId))];
+    const [allChunks, parents] = await Promise.all([
+      this.catalog.getRawMessageSearchChunks({ messageIds, userId: input.userId }),
+      Promise.all(messageIds.map((messageId) => this.catalog.getMessageById(messageId)))
+    ]);
+    const parentById = new Map(
+      parents.filter((parent) => Boolean(parent)).map((parent) => [parent.messageId, parent])
+    );
+    const chunksByMessage = /* @__PURE__ */ new Map();
+    for (const chunk of allChunks) {
+      const group = chunksByMessage.get(chunk.messageId) ?? [];
+      group.push(chunk);
+      chunksByMessage.set(chunk.messageId, group);
+    }
+    const strongest = /* @__PURE__ */ new Map();
+    for (const result of results) {
+      const chunk = matchedById.get(result.id);
+      if (!chunk) continue;
+      const parent = parentById.get(chunk.messageId);
+      if (!parent || input.botId && parent.botId !== input.botId) continue;
+      if (input.threshold !== void 0 && result.score < input.threshold) continue;
+      const siblings = (chunksByMessage.get(parent.messageId) ?? []).sort(
+        (a, b) => a.chunkIndex - b.chunkIndex
+      );
+      const content = chunk.chunkCount <= 1 ? parent.content : parent.content.slice(
+        siblings[Math.max(0, chunk.chunkIndex - 1)]?.startPosition ?? chunk.startPosition,
+        siblings[Math.min(siblings.length - 1, chunk.chunkIndex + 1)]?.endPosition ?? chunk.endPosition
+      );
+      const hit = {
+        id: parent.messageId,
+        content,
+        similarity: result.score,
+        metadata: {
+          ...parent.metadata ?? {},
+          userId: parent.userId,
+          botId: parent.botId,
+          platform: parent.platform,
+          timestamp: parent.timestamp,
+          sourceMessageId: parent.messageId,
+          sourceChunkId: chunk.chunkId,
+          sourceChunkIndex: chunk.chunkIndex,
+          sourceChunkCount: chunk.chunkCount,
+          backend: this.backend,
+          scoring: input.hybrid ? "native-hybrid" : "dense"
+        }
+      };
+      const existing = strongest.get(parent.messageId);
+      if (!existing || hit.similarity > existing.similarity) strongest.set(parent.messageId, hit);
+    }
+    return [...strongest.values()].sort((a, b) => b.similarity - a.similarity).slice(0, input.limit);
+  }
+};
+
 // src/server/cli-shared.ts
 init_raw_message_store();
 
@@ -2999,7 +3515,7 @@ function isInsightSQLiteVecEnabled(_env) {
 }
 async function getInsightSQLiteVecStore(_env) {
   const dbPath = resolveSQLiteRawMessageDbPath();
-  const { getSQLiteVecStore } = await import('@melandlabs/rag/sqlite-vec-store');
+  const { getSQLiteVecStore } = await import('@melandlabs/ai-rag/sqlite-vec-store');
   return await getSQLiteVecStore(dbPath, void 0, {
     collectionName: process.env.SQLITE_VEC_INSIGHTS_COLLECTION || "opencontext_insights"
   });
@@ -3023,17 +3539,19 @@ async function searchInsightsWithSQLiteVec(input, env) {
 // src/server/cli-shared.ts
 async function loadAiRag() {
   try {
-    const [local, chroma] = await Promise.all([
+    const [local, reranker, chroma] = await Promise.all([
       import('@melandlabs/ai-rag/local-transformers-embedding-provider'),
+      import('@melandlabs/ai-rag/local-transformers-reranker'),
       import('@melandlabs/ai-rag/chroma-store')
     ]);
     return {
       LocalTransformersEmbeddingProvider: local.LocalTransformersEmbeddingProvider,
+      LocalTransformersReranker: reranker.LocalTransformersReranker,
       ChromaVectorStore: chroma.ChromaVectorStore
     };
   } catch (error) {
     throw new Error(
-      `--embedding-provider local / --*-backend=chroma require @melandlabs/ai-rag to be installed. Run \`pnpm add @melandlabs/ai-rag\` and try again. (${error.message})`
+      `Local embedding/reranking and insight/knowledge Chroma require @melandlabs/ai-rag to be installed. Run \`pnpm add @melandlabs/ai-rag\` and try again. (${error.message})`
     );
   }
 }
@@ -3042,8 +3560,21 @@ function parseUnifiedArgs(argv) {
   const args = {
     embeddingProvider: env.EMBEDDING_PROVIDER ?? "none",
     embeddingModel: env.EMBEDDING_MODEL,
+    embeddingCacheDir: env.LOCAL_EMBEDDING_CACHE_DIR,
+    rerankerProvider: env.RERANKER_PROVIDER ?? "none",
+    rerankerModel: env.LOCAL_RERANKER_MODEL,
+    rerankerCacheDir: env.LOCAL_RERANKER_CACHE_DIR,
+    rerankerBatchSize: env.LOCAL_RERANKER_BATCH_SIZE ? Number.parseInt(env.LOCAL_RERANKER_BATCH_SIZE, 10) : void 0,
+    rerankerMaxTokens: env.LOCAL_RERANKER_MAX_TOKENS ? Number.parseInt(env.LOCAL_RERANKER_MAX_TOKENS, 10) : void 0,
     chromaUrl: env.CHROMA_URL,
     memoryBackend: env.MEMORY_BACKEND ?? "none",
+    lancedbUri: env.LANCEDB_URI,
+    lancedbTable: env.LANCEDB_TABLE,
+    milvusAddress: env.MILVUS_ADDRESS,
+    milvusToken: env.MILVUS_TOKEN,
+    milvusDatabase: env.MILVUS_DATABASE,
+    milvusCollection: env.MILVUS_COLLECTION,
+    milvusDimension: env.MILVUS_DIMENSION ? Number.parseInt(env.MILVUS_DIMENSION, 10) : void 0,
     insightsBackend: env.INSIGHTS_BACKEND ?? "none",
     insightsCollection: env.INSIGHTS_COLLECTION ?? "opencontext_insights",
     knowledgeBackend: env.KNOWLEDGE_BACKEND ?? "none",
@@ -3068,12 +3599,51 @@ function parseUnifiedArgs(argv) {
       case "--embedding-model":
         args.embeddingModel = takeValue();
         break;
+      case "--embedding-cache-dir":
+        args.embeddingCacheDir = takeValue();
+        break;
+      case "--reranker-provider":
+        args.rerankerProvider = takeValue();
+        break;
+      case "--reranker-model":
+        args.rerankerModel = takeValue();
+        break;
+      case "--reranker-cache-dir":
+        args.rerankerCacheDir = takeValue();
+        break;
+      case "--reranker-batch-size":
+        args.rerankerBatchSize = Number.parseInt(takeValue(), 10);
+        break;
+      case "--reranker-max-tokens":
+        args.rerankerMaxTokens = Number.parseInt(takeValue(), 10);
+        break;
       case "--chroma-url":
         args.chromaUrl = takeValue();
         break;
       case "--memory-backend":
         args.memoryBackend = takeValue();
         break;
+      case "--lancedb-uri":
+        args.lancedbUri = takeValue();
+        break;
+      case "--lancedb-table":
+        args.lancedbTable = takeValue();
+        break;
+      case "--milvus-address":
+        args.milvusAddress = takeValue();
+        break;
+      case "--milvus-token":
+        args.milvusToken = takeValue();
+        break;
+      case "--milvus-database":
+        args.milvusDatabase = takeValue();
+        break;
+      case "--milvus-collection":
+        args.milvusCollection = takeValue();
+        break;
+      case "--milvus-dimension":
+        args.milvusDimension = Number.parseInt(takeValue(), 10);
+        break;
       case "--insights-backend":
         args.insightsBackend = takeValue();
         break;
@@ -3103,31 +3673,60 @@ function parseUnifiedArgs(argv) {
         break;
     }
   }
-  for (const [name, value] of [
-    ["--embedding-provider", args.embeddingProvider],
-    ["--memory-backend", args.memoryBackend],
-    ["--insights-backend", args.insightsBackend],
-    ["--knowledge-backend", args.knowledgeBackend]
-  ]) {
-    const allowed = ["local", "openrouter", "none", "chroma", "sqlite-vec"];
+  const validate = (name, value, allowed) => {
     if (!allowed.includes(value)) {
       throw new Error(`[memory-store/cli] ${name} must be one of: ${allowed.join(", ")} (got "${value}")`);
     }
+  };
+  validate("--embedding-provider", args.embeddingProvider, ["local", "openrouter", "none"]);
+  validate("--reranker-provider", args.rerankerProvider, ["local", "none"]);
+  validate("--memory-backend", args.memoryBackend, ["sqlite-vec", "chroma", "lancedb", "milvus", "none"]);
+  validate("--insights-backend", args.insightsBackend, ["sqlite-vec", "chroma", "none"]);
+  validate("--knowledge-backend", args.knowledgeBackend, ["chroma", "none"]);
+  if (args.milvusDimension !== void 0 && (!Number.isInteger(args.milvusDimension) || args.milvusDimension <= 0)) {
+    throw new Error("[memory-store/cli] --milvus-dimension must be a positive integer");
+  }
+  for (const [name, value] of [
+    ["--reranker-batch-size", args.rerankerBatchSize],
+    ["--reranker-max-tokens", args.rerankerMaxTokens]
+  ]) {
+    if (value !== void 0 && (!Number.isInteger(value) || value <= 0)) {
+      throw new Error(`[memory-store/cli] ${name} must be a positive integer`);
+    }
   }
   return args;
 }
 async function buildUnified(args) {
   const unified = {};
   const log = (msg) => console.warn(`[memory-store/cli] ${msg}`);
-  const wantsAiRag = args.embeddingProvider === "local" || args.memoryBackend === "chroma" || args.insightsBackend === "chroma" || args.knowledgeBackend === "chroma";
+  const wantsAiRag = args.embeddingProvider === "local" || args.rerankerProvider === "local" || args.insightsBackend === "chroma" || args.knowledgeBackend === "chroma";
   const aiRag = wantsAiRag ? await loadAiRag() : null;
   if (args.embeddingProvider === "local") {
     try {
       if (!aiRag) {
         throw new Error("ai-rag modules not loaded");
       }
-      const provider = new aiRag.LocalTransformersEmbeddingProvider({ modelName: args.embeddingModel });
-      unified.embedQuery = async ({ query }) => provider.embedQuery(query);
+      const provider = new aiRag.LocalTransformersEmbeddingProvider({
+        modelName: args.embeddingModel,
+        cacheDir: args.embeddingCacheDir
+      });
+      unified.embeddingInfo = {
+        provider: "local",
+        model: args.embeddingModel ?? "Xenova/all-MiniLM-L6-v2",
+        maxTokens: 512
+      };
+      unified.embedQuery = async ({ query }) => {
+        const embedding = await provider.embedQuery(query);
+        if (unified.embeddingInfo) unified.embeddingInfo.dimensions = embedding.length;
+        return embedding;
+      };
+      unified.embedDocuments = async ({ texts }) => {
+        const embeddings = await provider.embedDocuments(texts);
+        if (unified.embeddingInfo && embeddings[0]) {
+          unified.embeddingInfo.dimensions = embeddings[0].length;
+        }
+        return embeddings;
+      };
       log(
         `embedQuery wired via LocalTransformersEmbeddingProvider (model=${args.embeddingModel ?? "Xenova/all-MiniLM-L6-v2"})`
       );
@@ -3143,6 +3742,7 @@ async function buildUnified(args) {
     }
     const model = args.embeddingModel ?? "text-embedding-3-small";
     const baseURL = "https://openrouter.ai/api/v1";
+    unified.embeddingInfo = { provider: "openrouter", model };
     unified.embedQuery = async ({ query }) => {
       const res = await fetch(`${baseURL}/embeddings`, {
         method: "POST",
@@ -3160,49 +3760,150 @@ async function buildUnified(args) {
       const body = await res.json();
       const embedding = body.data?.[0]?.embedding;
       if (!embedding) throw new Error("openrouter embeddings response missing data[0].embedding");
+      if (unified.embeddingInfo) unified.embeddingInfo.dimensions = embedding.length;
       return embedding;
     };
     log(`embedQuery wired via openrouter (model=${model})`);
   }
-  if (args.memoryBackend === "sqlite-vec") {
-    const store = createRawMessageStore({ env: void 0 });
-    const manager2 = await store.getManager();
-    if (typeof manager2.searchMessagesSemantically !== "function") {
+  if (args.rerankerProvider === "local") {
+    if (!aiRag) throw new Error("Local reranker modules were not loaded");
+    const reranker = new aiRag.LocalTransformersReranker({
+      modelName: args.rerankerModel,
+      cacheDir: args.rerankerCacheDir,
+      batchSize: args.rerankerBatchSize,
+      maxTokens: args.rerankerMaxTokens
+    });
+    await reranker.warmup();
+    unified.reranker = reranker;
+    unified.rerankerInfo = {
+      provider: "local",
+      model: reranker.getModelName(),
+      maxTokens: reranker.getMaxTokens(),
+      ready: true
+    };
+    log(`reranker wired via local Transformers.js (model=${reranker.getModelName()})`);
+  } else {
+    unified.rerankerInfo = { provider: "none", ready: false };
+  }
+  if (args.memoryBackend !== "none") {
+    if (args.memoryBackend === "chroma" && !args.chromaUrl) {
+      throw new Error("--memory-backend=chroma requires --chroma-url <url> (or CHROMA_URL env)");
+    }
+    if (args.memoryBackend === "lancedb" && !args.lancedbUri) {
+      throw new Error("--memory-backend=lancedb requires --lancedb-uri <uri> (or LANCEDB_URI env)");
+    }
+    if (args.memoryBackend === "milvus" && !args.milvusAddress) {
+      throw new Error("--memory-backend=milvus requires --milvus-address <address> (or MILVUS_ADDRESS env)");
+    }
+    if (args.memoryBackend === "lancedb") {
+      try {
+        await import('@lancedb/lancedb');
+      } catch (error) {
+        throw new Error(
+          `LanceDB requires the optional dependency @lancedb/lancedb (${error.message})`
+        );
+      }
+    }
+    if (args.memoryBackend === "milvus") {
+      try {
+        await import('@zilliz/milvus2-sdk-node');
+      } catch (error) {
+        throw new Error(
+          `Milvus requires the optional dependency @zilliz/milvus2-sdk-node (${error.message})`
+        );
+      }
+    }
+    const rawStore = createRawMessageStore({ env: void 0 });
+    const manager2 = await rawStore.getManager();
+    if (typeof manager2.getRawMessageSearchChunks !== "function" || typeof manager2.getRawMessageSearchIndexStats !== "function") {
       throw new Error(
-        "the active raw-message manager does not implement searchMessagesSemantically; sqlite-vec ANN for the memory source is unavailable in this build"
+        `${args.memoryBackend} child retrieval requires the SQLite raw-message catalog; the Postgres manager remains on the legacy parent fallback in this release`
       );
     }
-    unified.searchRawMessagesAnn = async ({ userId, queryEmbedding, limit, threshold, botId }) => {
-      const rows = await manager2.searchMessagesSemantically({
-        userId,
-        queryEmbedding,
-        limit,
-        threshold,
-        botId
+    if (typeof manager2.lexicalSearchMessages === "function") {
+      unified.searchRawMessagesLexical = async (input) => {
+        const rows = await manager2.lexicalSearchMessages(input);
+        return rows.map((row) => ({ ...row, metadata: row.metadata ?? {} }));
+      };
+    }
+    let externalStore;
+    if (args.memoryBackend === "chroma") {
+      externalStore = new ChromaVectorStore({
+        url: args.chromaUrl,
+        collectionName: "opencontext_raw_message_chunks"
+      });
+    } else if (args.memoryBackend === "lancedb") {
+      const { LanceDBStore } = await import('@melandlabs/rag/lancedb-store');
+      externalStore = new LanceDBStore({
+        uri: args.lancedbUri,
+        tableName: args.lancedbTable ?? "opencontext_raw_message_chunks",
+        defaultFusion: "rrf",
+        candidateMultiplier: 4
+      });
+    } else if (args.memoryBackend === "milvus") {
+      const { MilvusStore } = await import('@melandlabs/rag/milvus-store');
+      externalStore = new MilvusStore({
+        address: args.milvusAddress,
+        token: args.milvusToken,
+        database: args.milvusDatabase,
+        collectionName: args.milvusCollection ?? "opencontext_raw_message_chunks",
+        dimension: args.milvusDimension,
+        defaultFusion: "rrf",
+        candidateMultiplier: 4
       });
-      return rows.map((r) => ({
-        id: r.id,
-        content: r.content,
-        similarity: r.similarity,
-        metadata: r.metadata ?? {}
-      }));
-    };
-    log("memory backend wired via sqlite-vec (uses the manager's searchMessagesSemantically)");
-  } else if (args.memoryBackend === "chroma") {
-    if (!args.chromaUrl)
-      throw new Error("--memory-backend=chroma requires --chroma-url <url> (or CHROMA_URL env)");
-    if (!aiRag) {
-      throw new Error("ai-rag modules not loaded");
     }
-    const store = new aiRag.ChromaVectorStore({
-      url: args.chromaUrl,
-      collectionName: "opencontext_raw_messages"
-    });
-    unified.searchRawMessagesAnn = async ({ queryEmbedding, limit, threshold }) => {
-      const results = await store.similaritySearchWithOptions(queryEmbedding, { limit: limit + 1 });
-      return results.filter((r) => r.score >= threshold).map((r) => ({ id: r.id, content: r.content, similarity: r.score, metadata: r.metadata ?? {} }));
+    if (args.memoryBackend === "sqlite-vec") {
+      if (typeof manager2.searchMessagesSemantically !== "function") {
+        throw new Error("sqlite-vec child search is unavailable in the active raw-message manager");
+      }
+      unified.searchRawMessagesAnn = async ({ userId, queryEmbedding, limit, threshold, botId }) => {
+        const rows = await manager2.searchMessagesSemantically({
+          userId,
+          queryEmbedding,
+          limit,
+          threshold,
+          botId
+        });
+        return rows.map((row) => ({ ...row, metadata: row.metadata ?? {} }));
+      };
+    } else if (externalStore) {
+      const childIndex = new RawMessageChildVectorIndex({
+        backend: args.memoryBackend,
+        store: externalStore,
+        catalog: {
+          getMessageById: (messageId) => manager2.getMessageById(messageId),
+          // biome-ignore lint/style/noNonNullAssertion: guarded above
+          getRawMessageSearchChunks: (input) => manager2.getRawMessageSearchChunks(input)
+        }
+      });
+      unified.rawMessageChildIndex = childIndex;
+      unified.searchRawMessagesAnn = (input) => childIndex.search(input);
+      if (args.memoryBackend !== "chroma") {
+        unified.searchRawMessagesHybrid = (input) => childIndex.search({ ...input, hybrid: true });
+      }
+    }
+    unified.getRawMessageRetrievalStatus = async () => {
+      const stats = await manager2.getRawMessageSearchIndexStats();
+      const embeddingDimensions = unified.embeddingInfo?.dimensions;
+      const dimensionMismatch = embeddingDimensions !== void 0 && stats.embeddingDimensions.length > 0 && !stats.embeddingDimensions.includes(embeddingDimensions);
+      const semanticReady = Boolean(unified.embedQuery) && (args.memoryBackend === "sqlite-vec" ? stats.semanticReady : stats.embeddedChunkCount > 0) && !dimensionMismatch;
+      return {
+        backend: args.memoryBackend,
+        embeddingProvider: unified.embeddingInfo?.provider,
+        embeddingModel: unified.embeddingInfo?.model,
+        embeddingDimensions,
+        childCount: stats.chunkCount,
+        embeddedChildCount: stats.embeddedChunkCount,
+        indexedDimensions: stats.embeddingDimensions,
+        semanticReady,
+        lexicalReady: stats.lexicalReady,
+        semanticDegradedReason: dimensionMismatch ? "semantic_dimension_mismatch" : !unified.embedQuery ? "semantic_unavailable" : stats.embeddedChunkCount === 0 ? "semantic_child_vectors_empty" : void 0,
+        rerankerProvider: unified.rerankerInfo?.provider,
+        rerankerModel: unified.rerankerInfo?.model,
+        rerankerReady: unified.rerankerInfo?.ready ?? false
+      };
     };
-    log("memory backend wired via chroma (collection=opencontext_raw_messages)");
+    log(`memory backend wired via ${args.memoryBackend} with SQLite child catalog and lexical search`);
   }
   if (args.insightsBackend === "sqlite-vec" && isInsightSQLiteVecEnabled()) {
     if (!unified.embedQuery) {
@@ -3329,20 +4030,41 @@ function printUnifiedHelp() {
   --embedding-model <name>        Model name
                                   (env: EMBEDDING_MODEL; local \u2192 Xenova/all-MiniLM-L6-v2,
                                   openrouter \u2192 text-embedding-3-small)
+	--embedding-cache-dir <path>    Local embedding cache (env: LOCAL_EMBEDDING_CACHE_DIR)
   Note: "local" dynamically imports @melandlabs/ai-rag (a peer install).
 
+Reranking (after RRF/source fusion, before final Top-K):
+  --reranker-provider <name>      local | none
+                                  (env: RERANKER_PROVIDER, default: none)
+  --reranker-model <name>         Local sequence-classification model
+                                  (env: LOCAL_RERANKER_MODEL,
+                                  default: Xenova/ms-marco-MiniLM-L-6-v2)
+  --reranker-cache-dir <path>     Persistent model cache (env: LOCAL_RERANKER_CACHE_DIR)
+  --reranker-batch-size <int>     Pair scoring batch size (env: LOCAL_RERANKER_BATCH_SIZE,
+                                  default: 8)
+  --reranker-max-tokens <int>     Query/document pair token limit
+                                  (env: LOCAL_RERANKER_MAX_TOKENS, default: 512)
+
 Cross-source search (wires unified.searchKnowledge / searchInsights / searchRawMessagesAnn):
   --chroma-url <url>              Chroma server URL
                                   (env: CHROMA_URL; required when any *-backend=chroma)
-  --memory-backend <name>         sqlite-vec | chroma | none
+  --memory-backend <name>         sqlite-vec | chroma | lancedb | milvus | none
                                   (env: MEMORY_BACKEND, default: none)
+  --lancedb-uri <uri>             LanceDB directory or URI (env: LANCEDB_URI)
+  --lancedb-table <name>          Optional table name (env: LANCEDB_TABLE)
+  --milvus-address <address>      Milvus endpoint (env: MILVUS_ADDRESS)
+  --milvus-token <token>          Optional Milvus token (env: MILVUS_TOKEN)
+  --milvus-database <name>        Optional database (env: MILVUS_DATABASE)
+  --milvus-collection <name>      Optional collection (env: MILVUS_COLLECTION)
+  --milvus-dimension <int>        Optional vector dimension (env: MILVUS_DIMENSION)
   --insights-backend <name>       sqlite-vec | chroma | none
                                   (env: INSIGHTS_BACKEND, default: none)
   --insights-collection <name>    Chroma collection (default: opencontext_insights)
   --knowledge-backend <name>      chroma | none
                                   (env: KNOWLEDGE_BACKEND, default: none)
   --knowledge-collection <name>   Chroma collection (default: opencontext_knowledge)
-  Note: the chroma backends dynamically import @melandlabs/ai-rag.
+  Notes: memory Chroma uses @melandlabs/rag; insight/knowledge Chroma use
+  @melandlabs/ai-rag. LanceDB and Milvus require their optional peer dependencies.
 
 Reasoning (wires unified.reasoning.{queryRewriter, iterativePlanner}):
   --reasoning                     Enable the LLM reasoning layer so /v1/search and