@melandlabs/memory-store 1.2.5 → 1.3.0

package/dist/index.js

@@ -260,6 +260,69 @@ var init_raw_message_store = __esm({
 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 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`);
+    }
+  }
+}
+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");
+  }
+  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/utilities.ts
 function deriveLexicalKeywords(query) {
   return query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((token) => token.length >= 2).slice(0, 16);
@@ -418,6 +481,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 +691,6 @@ async function applyReranker(reranker, query, results) {
 
 // src/search/gather-evidence.ts
 var DEFAULT_TIERS2 = ["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 +708,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 +721,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 +740,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 +753,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 +838,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 +877,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 +904,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 +922,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 +1011,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 +1028,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 +1075,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 +1091,7 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
           queryEmbedding,
           limit,
           threshold,
+          includeDeprecated: input.includeDeprecated === true,
           ...peerPeers.length > 0 ? { peers: peerPeers } : {},
           ...factTypes ? { factTypes } : {}
         });
@@ -1051,6 +1121,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 +1141,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 +1150,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 +1158,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 +1172,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 +1188,7 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
           keywords,
           limit: Math.ceil(limit / filters.length),
           botId,
+          includeDeprecated,
           ...factTypes ? { factTypes } : {}
         })
       )
@@ -1128,7 +1219,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,7 +1249,7 @@ function createUnifiedSearch(deps = {}) {
     }
     return normalizeUnifiedMemoryReasoningStrategy(deps.reasoning?.defaultStrategy, "none");
   }
-  async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo, peerPeers = []) {
+  async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo, peerPeers = [], runtimeContext) {
     if ((reasoningStrategy === "iterative" || reasoningStrategy === "union") && !deps.reasoning?.iterativePlanner) {
       warnings.push({
         source: "memory",
@@ -1189,7 +1282,9 @@ function createUnifiedSearch(deps = {}) {
               keywords2,
               limit,
               logger,
-              peerPeers
+              peerPeers,
+              warnings,
+              runtimeContext
             );
             let semanticHits = [];
             if (typeof deps.embedQuery === "function") {
@@ -1203,7 +1298,9 @@ function createUnifiedSearch(deps = {}) {
                   limit,
                   threshold,
                   logger,
-                  peerPeers
+                  peerPeers,
+                  warnings,
+                  runtimeContext
                 );
               } catch (error) {
                 logger.warn?.(
@@ -1244,6 +1341,11 @@ function createUnifiedSearch(deps = {}) {
       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",
@@ -1251,7 +1353,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
       );
@@ -1259,6 +1370,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({
@@ -1277,7 +1408,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);
@@ -1300,7 +1441,9 @@ function createUnifiedSearch(deps = {}) {
         limit,
         threshold,
         logger,
-        peerPeers
+        peerPeers,
+        warnings,
+        runtimeContext
       );
     }
     let lexical = [];
@@ -1319,7 +1462,8 @@ function createUnifiedSearch(deps = {}) {
                 limit,
                 botId,
                 ...peerPeers.length > 0 ? { peers: peerPeers } : {},
-                ...factTypes ? { factTypes } : {}
+                ...factTypes ? { factTypes } : {},
+                ...runtimeContext ?? {}
               })
             )
           )).flat().filter(isRawMemorySemanticResult).map((hit) => ({
@@ -1345,7 +1489,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
       );
@@ -1407,14 +1551,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({
@@ -1434,23 +1580,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({
@@ -1473,12 +1642,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({
@@ -1505,12 +1675,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));
@@ -1528,10 +1699,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,
@@ -1539,28 +1714,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;
@@ -1592,19 +1790,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 = [];
@@ -1615,7 +1818,8 @@ function createUnifiedSearch(deps = {}) {
         limit,
         threshold,
         logger,
-        peerScope.peers
+        peerScope.peers,
+        runtimeContext
       );
       warnings.push(...summaryBucket.warnings);
       summaryHits = summaryBucket.hits;
@@ -1640,7 +1844,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,
@@ -1653,12 +1858,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
@@ -1667,6 +1875,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,
@@ -1682,6 +1894,7 @@ function mergeAcrossSources(input) {
     for (const hit of [
       ...memorySubs.semantic,
       ...memorySubs.lexical,
+      ...memorySubs.hybrid ?? [],
       ...input.insightHits,
       ...input.knowledgeHits
     ]) {
@@ -1697,6 +1910,7 @@ function mergeAcrossSources(input) {
   const all = [
     ...memorySubs.semantic,
     ...memorySubs.lexical,
+    ...memorySubs.hybrid ?? [],
     ...memorySubs.entity ?? [],
     ...input.insightHits,
     ...input.knowledgeHits
@@ -1708,6 +1922,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 });
   }