@melandlabs/memory-store 1.2.4 → 1.3.0

package/dist/mcp.js

@@ -1,5 +1,5 @@
 import { isFactType, vsaNormalizeVector, vsaAssertSameDim } from '@melandlabs/contracts';
-import { buildMemoryRecordEmbeddingDocument } from '@melandlabs/ai/memory';
+import '@melandlabs/ai/memory';
 import { ChromaVectorStore } from '@melandlabs/rag';
 import { mkdirSync } from 'fs';
 import { dirname } from 'path';
@@ -12,6 +12,7 @@ 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';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -22,27 +23,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"() {
   }
@@ -68,61 +48,9 @@ function getChromaStore(collectionName) {
     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 [];
@@ -324,59 +252,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;
+  }
+  if (!isRecord(runtimeContext) || !Array.isArray(runtimeContext.applicabilityContexts)) {
+    invalidRuntimeContext("applicabilityContexts must be an array");
   }
-  return { messages, warnings: [] };
+  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) {
@@ -463,7 +405,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;
@@ -570,6 +512,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;
 }
@@ -627,7 +570,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;
@@ -645,7 +587,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: [] };
   }
@@ -658,7 +600,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: [] };
@@ -676,12 +619,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) {
@@ -695,9 +632,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")}`);
   }
@@ -779,12 +717,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;
@@ -815,21 +756,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({
@@ -853,7 +783,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 [];
   }
@@ -871,7 +801,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();
@@ -959,6 +890,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,
@@ -966,10 +907,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) => {
@@ -994,24 +954,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();
@@ -1022,6 +970,7 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
           queryEmbedding,
           limit,
           threshold,
+          includeDeprecated: input.includeDeprecated === true,
           ...peerPeers.length > 0 ? { peers: peerPeers } : {},
           ...factTypes ? { factTypes } : {}
         });
@@ -1051,6 +1000,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,
@@ -1059,7 +1020,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 [];
   }
@@ -1068,6 +1029,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({
@@ -1075,8 +1037,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) => ({
@@ -1087,10 +1051,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({
@@ -1098,6 +1067,7 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
           keywords,
           limit: Math.ceil(limit / filters.length),
           botId,
+          includeDeprecated,
           ...factTypes ? { factTypes } : {}
         })
       )
@@ -1128,7 +1098,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) {
@@ -1156,8 +1128,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",
@@ -1173,7 +1145,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,
@@ -1188,7 +1161,9 @@ function createUnifiedSearch(deps = {}) {
               keywords2,
               limit,
               logger,
-              peerPeers
+              peerPeers,
+              warnings,
+              runtimeContext
             );
             let semanticHits = [];
             if (typeof deps.embedQuery === "function") {
@@ -1202,7 +1177,9 @@ function createUnifiedSearch(deps = {}) {
                   limit,
                   threshold,
                   logger,
-                  peerPeers
+                  peerPeers,
+                  warnings,
+                  runtimeContext
                 );
               } catch (error) {
                 logger.warn?.(
@@ -1230,16 +1207,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",
@@ -1247,7 +1232,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
       );
@@ -1255,6 +1249,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({
@@ -1273,7 +1287,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);
@@ -1296,7 +1320,9 @@ function createUnifiedSearch(deps = {}) {
         limit,
         threshold,
         logger,
-        peerPeers
+        peerPeers,
+        warnings,
+        runtimeContext
       );
     }
     let lexical = [];
@@ -1315,7 +1341,8 @@ function createUnifiedSearch(deps = {}) {
                 limit,
                 botId,
                 ...peerPeers.length > 0 ? { peers: peerPeers } : {},
-                ...factTypes ? { factTypes } : {}
+                ...factTypes ? { factTypes } : {},
+                ...runtimeContext ?? {}
               })
             )
           )).flat().filter(isRawMemorySemanticResult).map((hit) => ({
@@ -1341,7 +1368,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
       );
@@ -1363,6 +1390,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)
@@ -1372,14 +1430,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({
@@ -1399,23 +1459,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({
@@ -1438,12 +1521,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({
@@ -1470,12 +1554,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));
@@ -1493,10 +1578,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,
@@ -1504,28 +1593,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;
@@ -1557,19 +1669,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 = [];
@@ -1580,7 +1697,8 @@ function createUnifiedSearch(deps = {}) {
         limit,
         threshold,
         logger,
-        peerScope.peers
+        peerScope.peers,
+        runtimeContext
       );
       warnings.push(...summaryBucket.warnings);
       summaryHits = summaryBucket.hits;
@@ -1605,7 +1723,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,
@@ -1618,12 +1737,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
@@ -1632,6 +1754,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,
@@ -1647,6 +1773,7 @@ function mergeAcrossSources(input) {
     for (const hit of [
       ...memorySubs.semantic,
       ...memorySubs.lexical,
+      ...memorySubs.hybrid ?? [],
       ...input.insightHits,
       ...input.knowledgeHits
     ]) {
@@ -1662,6 +1789,7 @@ function mergeAcrossSources(input) {
   const all = [
     ...memorySubs.semantic,
     ...memorySubs.lexical,
+    ...memorySubs.hybrid ?? [],
     ...memorySubs.entity ?? [],
     ...input.insightHits,
     ...input.knowledgeHits
@@ -1673,6 +1801,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 });
   }
@@ -2137,8 +2268,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";
@@ -2151,13 +2524,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),
@@ -2165,8 +2562,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."
@@ -2175,7 +2572,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),
@@ -2239,11 +2640,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: {
@@ -2269,37 +2672,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 } : {}
             })
           }
         ]
@@ -2639,7 +3029,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;