@melandlabs/memory-store 1.3.8 → 1.4.1

package/dist/http.js

@@ -318,6 +318,46 @@ function resolveSearchRuntimeContext(input, runtimeContext, now = Date.now) {
   };
 }
 
+// src/search/execution-budget.ts
+function boundedSearchOperation(operation, budget) {
+  const timeout = budget.sourceTimeoutMs ?? 5e3;
+  if (!Number.isFinite(timeout) || timeout <= 0)
+    throw new TypeError("sourceTimeoutMs must be positive and finite");
+  return (...args) => new Promise((resolve, reject) => {
+    const signal = budget.signal;
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const cleanup2 = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup2();
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      cleanup2();
+      reject(new Error(`Search operation exceeded ${timeout}ms waiting budget`));
+    }, timeout);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve().then(() => {
+      signal?.throwIfAborted();
+      return operation(...args);
+    }).then(
+      (value) => {
+        cleanup2();
+        resolve(value);
+      },
+      (error) => {
+        cleanup2();
+        reject(error);
+      }
+    );
+  });
+}
+
 // src/search/reranker.ts
 async function applyReranker(reranker, query, results) {
   if (!reranker || results.length === 0) {
@@ -464,16 +504,21 @@ function deriveLexicalKeywords(query) {
 }
 var DEFAULT_LIMIT = 10;
 var DEFAULT_THRESHOLD = 0.7;
-var DEFAULT_SOURCES = ["memory", "insights", "knowledge"];
+var DEFAULT_SOURCES = ["memory", "insights", "knowledge", "workspace"];
 var SOURCE_SET = new Set(DEFAULT_SOURCES);
 function normalizeUnifiedMemorySearchSources(sources) {
-  if (!Array.isArray(sources) || sources.length === 0) {
+  if (sources === void 0) {
     return [...DEFAULT_SOURCES];
   }
+  if (!Array.isArray(sources) || sources.length === 0) {
+    throw new TypeError("Search sources must be a non-empty array when specified");
+  }
   const normalized = sources.filter((source) => typeof source === "string").map((source) => source.trim().toLowerCase()).filter(
     (source) => SOURCE_SET.has(source)
   );
-  return normalized.length > 0 ? Array.from(new Set(normalized)) : [...DEFAULT_SOURCES];
+  if (normalized.length !== sources.length)
+    throw new TypeError("Search sources contain an unsupported source");
+  return Array.from(new Set(normalized));
 }
 function clampUnifiedMemorySearchLimit(limit) {
   const parsed = typeof limit === "number" ? limit : Number(limit ?? DEFAULT_LIMIT);
@@ -515,6 +560,20 @@ function normalizeUnifiedMemoryReasoningStrategy(value, defaultStrategy = "none"
   return defaultStrategy;
 }
 var DEFAULT_RRF_K = 60;
+function mergeSearchResultProvenance(preferred, other) {
+  const first = preferred.provenance;
+  const second = other.provenance;
+  const firstVersion = first?.version ?? first?.citation?.version_id;
+  const secondVersion = second?.version ?? second?.citation?.version_id;
+  const firstHash = first?.contentHash ?? first?.citation?.content_hash;
+  const secondHash = second?.contentHash ?? second?.citation?.content_hash;
+  if (firstVersion != null && secondVersion != null && firstVersion !== secondVersion || firstHash != null && secondHash != null && firstHash !== secondHash || first?.citation && second?.citation && first.citation.id !== second.citation.id || preferred.content !== other.content && !(firstHash && firstHash === secondHash))
+    return preferred;
+  const metadata = { ...other.metadata, ...preferred.metadata };
+  if (!second) return { ...preferred, metadata };
+  const knownFirst = Object.fromEntries(Object.entries(first ?? {}).filter(([, value]) => value != null));
+  return { ...preferred, metadata, provenance: { ...second, ...knownFirst } };
+}
 function mergeUnifiedMemorySearchResultsRrf(lists, limit, k = DEFAULT_RRF_K, weights = {}) {
   if (!Array.isArray(lists) || lists.length === 0) {
     return [];
@@ -528,6 +587,7 @@ function mergeUnifiedMemorySearchResultsRrf(lists, limit, k = DEFAULT_RRF_K, wei
   const scores = /* @__PURE__ */ new Map();
   const order = [];
   for (const list of lists) {
+    const seenInList = /* @__PURE__ */ new Set();
     const channel = listNameToChannel(list.name);
     const configuredWeight = channel ? effectiveWeights[channel] : void 0;
     const weight = typeof configuredWeight === "number" && Number.isFinite(configuredWeight) && configuredWeight >= 0 ? configuredWeight : 1;
@@ -535,7 +595,8 @@ function mergeUnifiedMemorySearchResultsRrf(lists, limit, k = DEFAULT_RRF_K, wei
     for (let index = 0; index < list.hits.length; index += 1) {
       const hit = list.hits[index];
       const key = `${hit.type}::${hit.id}`;
-      const contribution = weight / (safeK + index + 1);
+      const contribution = seenInList.has(key) ? 0 : weight / (safeK + seenInList.size + 1);
+      seenInList.add(key);
       const existing = scores.get(key);
       const rankedHit = hit.type === "memory" ? withMatchedEvidence(hit, list.name, index + 1) : hit;
       if (existing) {
@@ -543,6 +604,7 @@ function mergeUnifiedMemorySearchResultsRrf(lists, limit, k = DEFAULT_RRF_K, wei
         if (hit.type === "memory" && existing.hit.type === "memory") {
           existing.hit = mergeMatchedEvidence(existing.hit, rankedHit);
         }
+        existing.hit = mergeSearchResultProvenance(existing.hit, rankedHit);
       } else {
         scores.set(key, { hit: rankedHit, rrf: contribution });
         order.push(key);
@@ -749,14 +811,15 @@ function buildSynthesisPrompt(input) {
     grouped.set(item.source, bucket);
   }
   const sections = [];
-  for (const tier of DEFAULT_TIERS) {
+  for (const tier of [...DEFAULT_TIERS, "workspace"]) {
     const items = grouped.get(tier) ?? [];
     if (items.length === 0) {
       continue;
     }
     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}`;
+      const provenance = item.provenance ? ` provenance=${JSON.stringify(item.provenance)}` : "";
+      return `  [${index + 1}] (${item.id}, source=${factSource}, score=${item.score.toFixed(4)}) ${item.snippet}${provenance}`;
     });
     sections.push(`## ${tier}
 ${lines.join("\n")}`);
@@ -847,7 +910,8 @@ async function synthesizeAnswer(input) {
     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
+    metadata: item.metadata,
+    provenance: item.provenance
   }));
   const warnings = [];
   const complete = deps.reasoning?.complete;
@@ -1068,7 +1132,7 @@ async function embedQueryVariant(embedQuery, input, query) {
     authToken: input.authToken
   });
 }
-async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger, peerPeers, warnings, runtimeContext) {
+async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger, peerPeers, warnings, runtimeContext, execution) {
   const filters = input.botIds && input.botIds.length > 0 ? input.botIds.map((botId) => ({ botId })) : [{}];
   let semantic = [];
   if (typeof deps.searchRawMessagesAnn === "function") {
@@ -1096,7 +1160,10 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
       semantic = (await Promise.all(
         filters.map((filter) => {
           const botId = "botId" in filter ? filter.botId : void 0;
-          return searchRawMessagesWithChroma({
+          return boundedSearchOperation(
+            searchRawMessagesWithChroma,
+            deps
+          )({
             userId: input.userId,
             queryEmbedding,
             limit,
@@ -1105,19 +1172,21 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
           });
         })
       )).flat().map(toMemoryResult);
+      if (execution) execution.completed++;
       logger.log?.("[memory-store] Raw message semantic search completed", {
         backend: "chroma",
         dimensions: queryEmbedding.length,
         count: semantic.length
       });
     } catch (error) {
+      if (execution) execution.failed++;
       logger.warn?.(
         "[memory-store] Chroma raw message search failed; falling back to database search:",
         error
       );
     }
   }
-  if (semantic.length === 0 && runtimeContext !== void 0) {
+  if (semantic.length === 0 && runtimeContext !== void 0 && !deps.searchRawMessagesAnn) {
     warnApplicabilityNotEnforced(warnings);
     return [];
   }
@@ -1127,7 +1196,10 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
       const manager2 = await getRawMessageManager2();
       if (typeof manager2.searchMessagesSemantically === "function") {
         const factTypes = input.factTypes?.length ? input.factTypes : void 0;
-        const results = await manager2.searchMessagesSemantically({
+        const results = await boundedSearchOperation(
+          manager2.searchMessagesSemantically.bind(manager2),
+          deps
+        )({
           userId: input.userId,
           queryEmbedding,
           limit,
@@ -1137,6 +1209,7 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
           ...peerPeers.length > 0 ? { peers: peerPeers } : {},
           ...factTypes ? { factTypes } : {}
         });
+        if (execution) execution.completed++;
         semantic = results.map((r) => ({
           type: "memory",
           id: r.id,
@@ -1146,6 +1219,7 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
         }));
       }
     } catch (error) {
+      if (execution) execution.failed++;
       logger.warn?.("[memory-store] SQLite semantic search failed:", error);
     }
   }
@@ -1196,7 +1270,7 @@ function toIterativeRecallCandidate(hit) {
     metadata: hit.metadata
   };
 }
-async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger, peerPeers, warnings, runtimeContext) {
+async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger, peerPeers, warnings, runtimeContext, execution) {
   if (keywords.length === 0) {
     return [];
   }
@@ -1246,9 +1320,12 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
     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(
+    const results = (await Promise.all(
       filters.map(
-        (botId) => lexicalSearchRawMessages2({
+        (botId) => boundedSearchOperation(
+          lexicalSearchRawMessages2,
+          deps
+        )({
           userId: input.userId,
           keywords,
           limit: Math.ceil(limit / filters.length),
@@ -1263,7 +1340,10 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger,
         r
       )
     );
+    if (execution) execution.completed++;
+    return results;
   } catch (error) {
+    if (execution) execution.failed++;
     logger.warn?.("[memory-store] SQLite lexical search failed:", error);
   }
   return [];
@@ -1310,7 +1390,21 @@ function mapHitToEvidenceSource(hit) {
   }
   return hit.type;
 }
-function createUnifiedSearch(deps = {}) {
+function createUnifiedSearch(inputDeps = {}) {
+  const deps = {
+    ...inputDeps,
+    embedQuery: inputDeps.embedQuery && boundedSearchOperation(inputDeps.embedQuery, inputDeps),
+    searchRawMessagesAnn: inputDeps.searchRawMessagesAnn && boundedSearchOperation(inputDeps.searchRawMessagesAnn, inputDeps),
+    searchRawMessagesHybrid: inputDeps.searchRawMessagesHybrid && boundedSearchOperation(inputDeps.searchRawMessagesHybrid, inputDeps),
+    searchRawMessagesLexical: inputDeps.searchRawMessagesLexical && boundedSearchOperation(inputDeps.searchRawMessagesLexical, inputDeps),
+    searchWorkspace: inputDeps.searchWorkspace && boundedSearchOperation(inputDeps.searchWorkspace, inputDeps),
+    searchInsights: inputDeps.searchInsights && boundedSearchOperation(inputDeps.searchInsights, inputDeps),
+    searchKnowledge: inputDeps.searchKnowledge && boundedSearchOperation(inputDeps.searchKnowledge, inputDeps),
+    searchSummaries: inputDeps.searchSummaries && boundedSearchOperation(inputDeps.searchSummaries, inputDeps),
+    getRawMessageRetrievalStatus: inputDeps.getRawMessageRetrievalStatus && boundedSearchOperation(inputDeps.getRawMessageRetrievalStatus, inputDeps),
+    entitySearch: inputDeps.entitySearch && boundedSearchOperation(inputDeps.entitySearch, inputDeps),
+    searchRawMessageNeighbors: inputDeps.searchRawMessageNeighbors && boundedSearchOperation(inputDeps.searchRawMessageNeighbors, inputDeps)
+  };
   const logger = deps.logger ?? console;
   function resolveReasoningStrategy(input) {
     const requested = normalizeUnifiedMemoryReasoningStrategy(input.reasoningStrategy);
@@ -1320,6 +1414,25 @@ function createUnifiedSearch(deps = {}) {
     return normalizeUnifiedMemoryReasoningStrategy(deps.reasoning?.defaultStrategy, "none");
   }
   async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo, peerPeers = [], runtimeContext) {
+    const execution = { completed: 0, failed: 0 };
+    const observe = (operation, preparation = false) => operation && (async (...args) => {
+      try {
+        const result = await operation(...args);
+        if (!preparation) execution.completed++;
+        return result;
+      } catch (error) {
+        execution.failed++;
+        throw error;
+      }
+    });
+    const sourceDeps = {
+      ...deps,
+      embedQuery: observe(deps.embedQuery, true),
+      searchRawMessagesAnn: observe(deps.searchRawMessagesAnn),
+      searchRawMessagesHybrid: observe(deps.searchRawMessagesHybrid),
+      searchRawMessagesLexical: observe(deps.searchRawMessagesLexical),
+      entitySearch: observe(deps.entitySearch)
+    };
     const sourceStartedAt = monotonicNow();
     const timings = {
       semanticMs: 0,
@@ -1337,9 +1450,10 @@ function createUnifiedSearch(deps = {}) {
     };
     const finish = (results) => ({
       results,
-      timings: { ...timings, memorySourceMs: monotonicNow() - sourceStartedAt }
+      timings: { ...timings, memorySourceMs: monotonicNow() - sourceStartedAt },
+      availability: execution.failed > 0 ? execution.completed > 0 ? "partial" : "failed" : execution.completed > 0 || Object.values(results).some((hits) => hits.length > 0) ? "complete" : "not_ready"
     });
-    if ((reasoningStrategy === "iterative" || reasoningStrategy === "union") && !deps.reasoning?.iterativePlanner) {
+    if ((reasoningStrategy === "iterative" || reasoningStrategy === "union") && !sourceDeps.reasoning?.iterativePlanner) {
       warnings.push({
         source: "memory",
         code: "memory_iterative_planner_not_configured",
@@ -1347,7 +1461,7 @@ function createUnifiedSearch(deps = {}) {
       });
       if (reasoningInfo) reasoningInfo.degraded = true;
     }
-    if (reasoningStrategy === "rewrite" && !deps.reasoning?.queryRewriter) {
+    if (reasoningStrategy === "rewrite" && !sourceDeps.reasoning?.queryRewriter) {
       warnings.push({
         source: "memory",
         code: "memory_query_rewrite_not_configured",
@@ -1356,8 +1470,8 @@ function createUnifiedSearch(deps = {}) {
       if (reasoningInfo) reasoningInfo.degraded = true;
     }
     let unionEvidence = null;
-    if ((reasoningStrategy === "iterative" || reasoningStrategy === "union") && deps.reasoning?.iterativePlanner) {
-      const planner = deps.reasoning.iterativePlanner;
+    if ((reasoningStrategy === "iterative" || reasoningStrategy === "union") && sourceDeps.reasoning?.iterativePlanner) {
+      const planner = sourceDeps.reasoning.iterativePlanner;
       const result = await planner.plan({
         query: input.query,
         ...input.includeRetrievalDiagnostics ? { options: { collectDiagnostics: true } } : {},
@@ -1369,26 +1483,27 @@ function createUnifiedSearch(deps = {}) {
             const lexicalHits = await measure(
               "lexicalMs",
               () => runLexicalSearchForKeywords(
-                deps,
+                sourceDeps,
                 input,
                 keywords2,
                 limit,
                 logger,
                 peerPeers,
                 warnings,
-                runtimeContext
+                runtimeContext,
+                execution
               )
             );
             let semanticHits = [];
-            if (typeof deps.embedQuery === "function") {
+            if (typeof sourceDeps.embedQuery === "function") {
               try {
                 semanticHits = await measure("semanticMs", async () => {
                   const semanticQuery = keywords2.join(" ");
-                  const queryEmbedder = deps.embedQuery;
+                  const queryEmbedder = sourceDeps.embedQuery;
                   if (typeof queryEmbedder !== "function") return [];
                   const queryEmbedding = await embedQueryVariant(queryEmbedder, input, semanticQuery);
                   return runSemanticSearchForEmbedding(
-                    deps,
+                    sourceDeps,
                     input,
                     queryEmbedding,
                     limit,
@@ -1396,7 +1511,8 @@ function createUnifiedSearch(deps = {}) {
                     logger,
                     peerPeers,
                     warnings,
-                    runtimeContext
+                    runtimeContext,
+                    execution
                   );
                 });
               } catch (error) {
@@ -1449,66 +1565,74 @@ function createUnifiedSearch(deps = {}) {
       }
       unionEvidence = evidence;
     }
-    if (typeof deps.embedQuery !== "function") {
+    const lexicalFallback = async () => {
+      const lexical2 = await runLexicalSearchForKeywords(
+        sourceDeps,
+        input,
+        deriveLexicalKeywords(input.query),
+        limit,
+        logger,
+        peerPeers,
+        warnings,
+        runtimeContext,
+        execution
+      );
+      return finish({ semantic: [], lexical: filterByDateRange(lexical2, input.dateFrom, input.dateTo) });
+    };
+    if (typeof sourceDeps.embedQuery !== "function") {
       warnings.push({
         source: "memory",
         code: "memory_lexical_search_fallback",
         message: "No embedding provider is configured; using lexical (BM25) search as fallback. Pass an `embedQuery` function via `unified.embedQuery` to enable semantic retrieval."
       });
-      const keywords2 = deriveLexicalKeywords(input.query);
-      const lexical2 = filterByDateRange(
-        await runLexicalSearchForKeywords(
-          deps,
-          input,
-          keywords2,
-          limit,
-          logger,
-          peerPeers,
-          warnings,
-          runtimeContext
-        ),
-        input.dateFrom,
-        input.dateTo
-      );
-      return finish({ semantic: [], lexical: lexical2 });
+      return lexicalFallback();
     }
     let semantic = [];
     let lexicalQueries = [input.query];
-    const embedQuery = deps.embedQuery;
+    const embedQuery = sourceDeps.embedQuery;
     const activeMergeStrategy = normalizeUnifiedMemoryMergeStrategy(
-      input.mergeStrategy ?? deps.reasoning?.defaultMergeStrategy ?? "rrf"
+      input.mergeStrategy ?? sourceDeps.reasoning?.defaultMergeStrategy ?? "rrf"
     );
-    if (reasoningStrategy === "none" && activeMergeStrategy === "rrf" && input.threshold === void 0 && typeof deps.searchRawMessagesHybrid === "function") {
-      const hybrid = await measure("hybridMs", async () => {
-        const queryEmbedding = await embedQueryVariant(embedQuery, input, input.query);
-        const filters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
-        return (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 finish({
-        semantic: [],
-        lexical: [],
-        hybrid: filterByDateRange(hybrid, input.dateFrom, input.dateTo)
-      });
+    if (reasoningStrategy === "none" && activeMergeStrategy === "rrf" && input.threshold === void 0 && typeof sourceDeps.searchRawMessagesHybrid === "function") {
+      try {
+        const hybrid = await measure("hybridMs", async () => {
+          const queryEmbedding = await embedQueryVariant(embedQuery, input, input.query);
+          const filters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
+          return (await Promise.all(
+            filters.map(
+              (botId) => sourceDeps.searchRawMessagesHybrid?.({
+                userId: input.userId,
+                query: input.query,
+                queryEmbedding,
+                limit: Math.ceil(limit / filters.length),
+                botId,
+                ...runtimeContext ?? {}
+              })
+            )
+          )).flatMap((items) => items ?? []).filter(isRawMemorySemanticResult).map(toMemoryResult);
+        });
+        return finish({
+          semantic: [],
+          lexical: [],
+          hybrid: filterByDateRange(hybrid, input.dateFrom, input.dateTo)
+        });
+      } catch (error) {
+        warnings.push({
+          source: "memory",
+          code: "memory_hybrid_search_failed",
+          message: error instanceof Error ? error.message : String(error)
+        });
+        return lexicalFallback();
+      }
     }
-    if (reasoningStrategy === "rewrite" && deps.reasoning?.queryRewriter) {
+    if (reasoningStrategy === "rewrite" && sourceDeps.reasoning?.queryRewriter) {
       try {
-        const variants = await deps.reasoning.queryRewriter.rewrite({
+        const variants = await sourceDeps.reasoning.queryRewriter.rewrite({
           query: input.query,
           userId: input.userId,
           authToken: input.authToken
         });
-        if (deps.reasoning.rewriteLexical === true) {
+        if (sourceDeps.reasoning.rewriteLexical === true) {
           const seen = /* @__PURE__ */ new Set();
           lexicalQueries = [input.query, ...variants].map((query) => query.trim()).filter((query) => {
             const key = query.toLowerCase();
@@ -1519,7 +1643,7 @@ function createUnifiedSearch(deps = {}) {
         }
         if (reasoningInfo) {
           reasoningInfo.rewrittenQueries = variants;
-          if (deps.reasoning.queryRewriter.lastDegraded?.()) {
+          if (sourceDeps.reasoning.queryRewriter.lastDegraded?.()) {
             reasoningInfo.degraded = true;
           }
         }
@@ -1530,7 +1654,7 @@ function createUnifiedSearch(deps = {}) {
           return Promise.all(
             embeddings.map(
               (embedding) => runSemanticSearchForEmbedding(
-                deps,
+                sourceDeps,
                 input,
                 embedding,
                 limit,
@@ -1538,12 +1662,13 @@ function createUnifiedSearch(deps = {}) {
                 logger,
                 peerPeers,
                 warnings,
-                runtimeContext
+                runtimeContext,
+                execution
               )
             )
           );
         });
-        if (activeMergeStrategy === "rrf" && deps.reasoning.rewriteSemanticMerge === "rrf" && lists.length > 1 && lists.some((hits) => hits.length > 0)) {
+        if (activeMergeStrategy === "rrf" && sourceDeps.reasoning.rewriteSemanticMerge === "rrf" && lists.length > 1 && lists.some((hits) => hits.length > 0)) {
           semantic = mergeUnifiedMemorySearchResultsRrf(
             lists.map((hits, index) => ({
               name: `memory-semantic-query:${index}`,
@@ -1566,24 +1691,33 @@ function createUnifiedSearch(deps = {}) {
       }
     }
     if (semantic.length === 0) {
-      semantic = await measure("semanticMs", async () => {
-        const queryEmbedding = await embedQueryVariant(embedQuery, input, input.query);
-        return runSemanticSearchForEmbedding(
-          deps,
-          input,
-          queryEmbedding,
-          limit,
-          threshold,
-          logger,
-          peerPeers,
-          warnings,
-          runtimeContext
-        );
-      });
+      try {
+        semantic = await measure("semanticMs", async () => {
+          const queryEmbedding = await embedQueryVariant(embedQuery, input, input.query);
+          return runSemanticSearchForEmbedding(
+            sourceDeps,
+            input,
+            queryEmbedding,
+            limit,
+            threshold,
+            logger,
+            peerPeers,
+            warnings,
+            runtimeContext,
+            execution
+          );
+        });
+      } catch (error) {
+        warnings.push({
+          source: "memory",
+          code: "memory_semantic_search_failed",
+          message: error instanceof Error ? error.message : String(error)
+        });
+      }
     }
     let lexical = [];
     const keywords = deriveLexicalKeywords(input.query);
-    if (activeMergeStrategy === "rrf" && lexicalQueries.length > 1 && typeof deps.searchRawMessagesLexical === "function") {
+    if (activeMergeStrategy === "rrf" && lexicalQueries.length > 1 && typeof sourceDeps.searchRawMessagesLexical === "function") {
       const lists = await Promise.all(
         lexicalQueries.map(async (query) => ({
           name: "memory-bm25",
@@ -1591,14 +1725,15 @@ function createUnifiedSearch(deps = {}) {
             await measure(
               "lexicalMs",
               () => runLexicalSearchForKeywords(
-                deps,
+                sourceDeps,
                 input,
                 deriveLexicalKeywords(query),
                 limit,
                 logger,
                 peerPeers,
                 warnings,
-                runtimeContext
+                runtimeContext,
+                execution
               )
             ),
             "memory-bm25"
@@ -1611,11 +1746,11 @@ function createUnifiedSearch(deps = {}) {
       }));
       if (reasoningInfo) reasoningInfo.lexicalRewrittenQueries = lexicalQueries;
     } else if (keywords.length > 0) {
-      if (typeof deps.searchRawMessagesLexical === "function") {
+      if (typeof sourceDeps.searchRawMessagesLexical === "function") {
         const lexicalStartedAt = monotonicNow();
         try {
           const lexFilters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
-          const searchRawMessagesLexical = deps.searchRawMessagesLexical;
+          const searchRawMessagesLexical = sourceDeps.searchRawMessagesLexical;
           const factTypes = input.factTypes?.length ? input.factTypes : void 0;
           const includeDeprecated = input.includeDeprecated === true;
           lexical = (await Promise.all(
@@ -1655,16 +1790,16 @@ function createUnifiedSearch(deps = {}) {
       }
     }
     let entity;
-    if (typeof deps.entitySearch === "function") {
+    if (typeof sourceDeps.entitySearch === "function") {
       entity = filterByDateRange(
-        await runEntitySearchForQuery(deps, input, limit, logger, peerPeers, runtimeContext),
+        await runEntitySearchForQuery(sourceDeps, input, limit, logger, peerPeers, runtimeContext),
         input.dateFrom,
         input.dateTo
       );
       if (entity.length === 0) {
         entity = void 0;
       } else if (normalizeUnifiedMemoryMergeStrategy(
-        input.mergeStrategy ?? deps.reasoning?.defaultMergeStrategy ?? "rrf"
+        input.mergeStrategy ?? sourceDeps.reasoning?.defaultMergeStrategy ?? "rrf"
       ) !== "rrf") {
         warnings.push({
           source: "memory",
@@ -1695,6 +1830,7 @@ function createUnifiedSearch(deps = {}) {
     const searchStartedAt = monotonicNow();
     const query = input.query.trim();
     const sources = normalizeUnifiedMemorySearchSources(input.sources);
+    const sourceStates = [];
     const limit = clampUnifiedMemorySearchLimit(input.limit);
     const mergeStrategy = normalizeUnifiedMemoryMergeStrategy(
       input.mergeStrategy ?? deps.reasoning?.defaultMergeStrategy ?? "rrf"
@@ -1720,7 +1856,8 @@ function createUnifiedSearch(deps = {}) {
         sources,
         results: [],
         count: 0,
-        warnings
+        warnings,
+        sourceStates
       };
     }
     let memorySubs;
@@ -1731,6 +1868,7 @@ function createUnifiedSearch(deps = {}) {
       reasoningInfo.dateRange = { from: input.dateFrom, to: input.dateTo };
     }
     if (sources.includes("memory")) {
+      let availability = "not_ready";
       const hasRawProviders = typeof deps.searchRawMessagesAnn === "function" || typeof deps.searchRawMessagesHybrid === "function" || typeof deps.searchRawMessagesLexical === "function";
       if (isRawMessageStorageAvailable() || hasRawProviders) {
         try {
@@ -1745,6 +1883,7 @@ function createUnifiedSearch(deps = {}) {
             runtimeContext
           );
           memorySubs = memoryRun.results;
+          availability = memoryRun.availability;
           memoryTimings = memoryRun.timings;
           memorySubs = {
             semantic: dedupeChannelByParent(memorySubs.semantic, "memory-semantic"),
@@ -1769,11 +1908,12 @@ function createUnifiedSearch(deps = {}) {
             warnings.push({ source: "memory", code, message });
           }
         } catch (error) {
+          availability = availability === "complete" || availability === "partial" ? "partial" : "failed";
           logger.warn?.("[memory-store] memory source failed:", error);
           warnings.push({
             source: "memory",
             code: "memory_search_failed",
-            message: `Memory search failed: ${error.message ?? "Unknown error"}. Using keyword search fallback.`
+            message: `Memory search failed: ${error.message ?? "Unknown error"}.`
           });
         }
       } else {
@@ -1783,6 +1923,51 @@ function createUnifiedSearch(deps = {}) {
           message: "Raw memory storage is not available in this environment."
         });
       }
+      const count = new Set(
+        [
+          ...memorySubs?.semantic ?? [],
+          ...memorySubs?.lexical ?? [],
+          ...memorySubs?.hybrid ?? [],
+          ...memorySubs?.planner ?? [],
+          ...memorySubs?.entity ?? []
+        ].map((hit) => hit.id)
+      ).size;
+      if (availability === "complete" && count === 0 && retrievalStatus?.lexicalReady === false && (!retrievalStatus.semanticReady || !deps.embedQuery)) {
+        availability = "not_ready";
+      }
+      const memoryWarnings = warnings.filter((warning) => warning.source === "memory");
+      sourceStates.push({
+        source: "memory",
+        status: availability,
+        count,
+        ...memoryWarnings.length ? { message: memoryWarnings.map((warning) => warning.message).join("; ") } : {}
+      });
+    }
+    const workspaceHits = [];
+    if (sources.includes("workspace")) {
+      if (!deps.searchWorkspace) {
+        sourceStates.push({ source: "workspace", status: "not_configured", count: 0 });
+      } else {
+        try {
+          const result = await deps.searchWorkspace({
+            userId: input.userId,
+            query,
+            limit: candidateLimit,
+            ...runtimeContext ?? {}
+          });
+          workspaceHits.push(...result.hits.map((hit) => ({ ...hit, type: "workspace" })));
+          sourceStates.push({
+            source: "workspace",
+            status: result.status,
+            count: result.hits.length,
+            ...result.message ? { message: result.message } : {}
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          sourceStates.push({ source: "workspace", status: "failed", count: 0, message });
+          warnings.push({ source: "workspace", code: "workspace_search_failed", message });
+        }
+      }
     }
     const insightHits = [];
     if (sources.includes("insights") && typeof deps.searchInsights === "function") {
@@ -1804,10 +1989,18 @@ function createUnifiedSearch(deps = {}) {
             id: hit.id,
             content: hit.content,
             similarity: hit.similarity,
-            metadata: hit.metadata
+            metadata: hit.metadata,
+            provenance: hit.provenance
           });
         }
+        sourceStates.push({ source: "insights", status: "complete", count: insightHits.length });
       } catch (error) {
+        sourceStates.push({
+          source: "insights",
+          status: "failed",
+          count: 0,
+          message: error instanceof Error ? error.message : String(error)
+        });
         logger.warn?.("[memory-store] insights source failed:", error);
         warnings.push({
           source: "insights",
@@ -1815,7 +2008,9 @@ function createUnifiedSearch(deps = {}) {
           message: error.message ?? "insights_search_failed"
         });
       }
-    } else if (sources.includes("insights")) ;
+    } else if (sources.includes("insights")) {
+      sourceStates.push({ source: "insights", status: "not_configured", count: 0 });
+    }
     const knowledgeHits = [];
     if (sources.includes("knowledge") && typeof deps.searchKnowledge === "function") {
       try {
@@ -1834,7 +2029,14 @@ function createUnifiedSearch(deps = {}) {
         for (const hit of hits) {
           knowledgeHits.push(toKnowledgeResult(hit));
         }
+        sourceStates.push({ source: "knowledge", status: "complete", count: knowledgeHits.length });
       } catch (error) {
+        sourceStates.push({
+          source: "knowledge",
+          status: "failed",
+          count: 0,
+          message: error instanceof Error ? error.message : String(error)
+        });
         logger.warn?.("[memory-store] knowledge source failed:", error);
         warnings.push({
           source: "knowledge",
@@ -1842,12 +2044,15 @@ function createUnifiedSearch(deps = {}) {
           message: error.message ?? "knowledge_search_failed"
         });
       }
-    } else if (sources.includes("knowledge")) ;
+    } else if (sources.includes("knowledge")) {
+      sourceStates.push({ source: "knowledge", status: "not_configured", count: 0 });
+    }
     const fusionStartedAt = monotonicNow();
     const merged = mergeAcrossSources({
       memorySubs,
       insightHits,
       knowledgeHits,
+      workspaceHits,
       limit: candidateLimit,
       strategy: mergeStrategy,
       rrfK,
@@ -1874,7 +2079,8 @@ function createUnifiedSearch(deps = {}) {
       sources,
       results: ranked,
       count: ranked.length,
-      warnings
+      warnings,
+      sourceStates
     };
     if (input.includeRetrievalDiagnostics) {
       output.retrievalDiagnostics = {
@@ -1984,15 +2190,17 @@ function createUnifiedSearch(deps = {}) {
         evidence: [],
         count: 0,
         warnings: peerScope.warnings,
+        sourceStates: [],
         answer: ""
       };
       return empty;
     }
-    const tiers = input.tiers ? [...input.tiers] : wantsSynthesis ? ["summary", "raw", "insight", "knowledge"] : ["raw", "insight", "knowledge"];
+    const tiers = input.tiers ? [...input.tiers] : wantsSynthesis ? ["summary", "raw", "insight", "knowledge", "workspace"] : ["raw", "insight", "knowledge", "workspace"];
     const wantsSummaryTier = tiers.includes("summary");
     const wantsRawTier = tiers.includes("raw");
     const wantsInsightTier = tiers.includes("insight");
     const wantsKnowledgeTier = tiers.includes("knowledge");
+    const wantsWorkspaceTier = tiers.includes("workspace");
     const warnings = [...peerScope.warnings];
     const limit = clampUnifiedMemorySearchLimit(input.limit);
     const threshold = clampUnifiedMemorySearchThreshold(input.threshold);
@@ -2000,11 +2208,13 @@ function createUnifiedSearch(deps = {}) {
     let sources = input.sources ? [...input.sources] : [];
     let unifiedReasoning;
     let retrievalDiagnostics;
-    if (wantsRawTier || wantsInsightTier || wantsKnowledgeTier) {
+    let sourceStates = [];
+    if (wantsRawTier || wantsInsightTier || wantsKnowledgeTier || wantsWorkspaceTier) {
       const inferredSources = sources.length > 0 ? sources : [
         ...wantsRawTier ? ["memory"] : [],
         ...wantsInsightTier ? ["insights"] : [],
-        ...wantsKnowledgeTier ? ["knowledge"] : []
+        ...wantsKnowledgeTier ? ["knowledge"] : [],
+        ...wantsWorkspaceTier ? ["workspace"] : []
       ];
       const unified = await searchUnifiedMemoryWithRuntime(
         {
@@ -2017,6 +2227,7 @@ function createUnifiedSearch(deps = {}) {
       sources = unified.sources;
       unifiedReasoning = unified.reasoning;
       retrievalDiagnostics = unified.retrievalDiagnostics;
+      sourceStates = unified.sourceStates;
       warnings.push(...unified.warnings);
     }
     let summaryHits = [];
@@ -2055,6 +2266,17 @@ function createUnifiedSearch(deps = {}) {
       source: mapHitToEvidenceSource(hit),
       snippet: hit.content,
       score: hit.similarity,
+      provenance: {
+        citation: hit.provenance?.citation ?? null,
+        origin: hit.provenance?.origin ?? null,
+        businessReference: hit.provenance?.businessReference ?? null,
+        version: hit.provenance?.version ?? hit.provenance?.citation?.version_id ?? null,
+        contentHash: hit.provenance?.contentHash ?? hit.provenance?.citation?.content_hash ?? null,
+        scope: hit.provenance?.scope ?? null,
+        derivedFrom: hit.provenance?.derivedFrom ?? null,
+        confirmation: hit.provenance?.confirmation ?? null,
+        freshness: hit.provenance?.freshness ?? null
+      },
       timestamp: getCandidateTimestamp(hit.metadata),
       metadata: hit.metadata
     }));
@@ -2064,7 +2286,8 @@ function createUnifiedSearch(deps = {}) {
       results: hits,
       evidence,
       count: hits.length,
-      warnings
+      warnings,
+      sourceStates
     };
     if (unifiedReasoning) {
       base.reasoning = unifiedReasoning;
@@ -2087,8 +2310,16 @@ function createUnifiedSearch(deps = {}) {
     return base;
   }
   async function search(input, runtimeContext) {
+    deps.signal?.throwIfAborted();
+    if (input.sources !== void 0) normalizeUnifiedMemorySearchSources(input.sources);
     const resolvedRuntime = resolveSearchRuntimeContext(input, runtimeContext);
-    return searchWithResolvedRuntime(input, resolvedRuntime);
+    const runSearch = boundedSearchOperation(() => searchWithResolvedRuntime(input, resolvedRuntime), {
+      signal: deps.signal,
+      sourceTimeoutMs: deps.searchTimeoutMs ?? 3e4
+    });
+    const result = await runSearch();
+    deps.signal?.throwIfAborted();
+    return result;
   }
   return {
     search,
@@ -2203,6 +2434,7 @@ function selectSessionNeighborResults(results, options, limit) {
 function mergeAcrossSources(input) {
   const memorySubs = input.memorySubs ?? { semantic: [], lexical: [] };
   const lists = buildChannelLists(memorySubs, input.insightHits, input.knowledgeHits);
+  if (input.workspaceHits.length) lists.push({ name: "workspace", hits: input.workspaceHits });
   if (input.strategy !== "rrf") {
     const seen = /* @__PURE__ */ new Map();
     for (const hit of [
@@ -2211,7 +2443,8 @@ function mergeAcrossSources(input) {
       ...memorySubs.planner ?? [],
       ...memorySubs.hybrid ?? [],
       ...input.insightHits,
-      ...input.knowledgeHits
+      ...input.knowledgeHits,
+      ...input.workspaceHits
     ]) {
       const key = `${hit.type}::${hit.id}`;
       const existing = seen.get(key);
@@ -2222,7 +2455,10 @@ function mergeAcrossSources(input) {
         const other = preferred === hit ? existing : hit;
         seen.set(
           key,
-          preferred.type === "memory" && other.type === "memory" ? mergeMatchedEvidence(preferred, other) : preferred
+          mergeSearchResultProvenance(
+            preferred.type === "memory" && other.type === "memory" ? mergeMatchedEvidence(preferred, other) : preferred,
+            other
+          )
         );
       }
     }
@@ -2238,7 +2474,8 @@ function mergeAcrossSources(input) {
     ...memorySubs.hybrid ?? [],
     ...memorySubs.entity ?? [],
     ...input.insightHits,
-    ...input.knowledgeHits
+    ...input.knowledgeHits,
+    ...input.workspaceHits
   ];
   const merged = mergeUnifiedMemorySearchResultsRrf(
     lists.length > 0 ? lists : [{ name: "memory-semantic", hits: all }],
@@ -2333,7 +2570,8 @@ async function applyReflectedPlan(deps, store, input, _logger) {
     source: item.source ?? "raw",
     snippet: item.snippet,
     score: item.score,
-    timestamp: item.timestamp
+    timestamp: item.timestamp,
+    provenance: item.provenance
   }));
   const records = evidence.map((item) => toMemoryEvidenceRecord(item, input.userId));
   const applyInput = {
@@ -3082,10 +3320,16 @@ async function startHttpServer(options = {}) {
     }
     const wantsSynthesis = typeof body.synthesize === "boolean" ? body.synthesize : typeof body.synthesize === "object" && body.synthesize !== null;
     const responseSchema = typeof body.synthesize === "object" && body.synthesize !== null ? body.synthesize.responseSchema ?? body.responseSchema : body.responseSchema;
+    let sources;
+    try {
+      if (body.sources !== void 0) sources = normalizeUnifiedMemorySearchSources(body.sources);
+    } catch (error) {
+      return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
     const input = {
       userId,
       query,
-      sources: Array.isArray(body.sources) ? body.sources : void 0,
+      sources,
       tiers: Array.isArray(body.tiers) ? body.tiers : void 0,
       limit: typeof body.limit === "number" ? body.limit : void 0,
       candidateLimit: typeof body.candidateLimit === "number" ? body.candidateLimit : void 0,