@melandlabs/memory-store 0.3.0 → 1.0.0

package/dist/search/unified-search.js

@@ -1,9 +1,11 @@
+import '@melandlabs/contracts';
 import '@melandlabs/ai/memory';
 import { ChromaVectorStore } from '@melandlabs/rag';
 import { mkdirSync } from 'fs';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
+import { dirname } from 'path';
+import { getOpenContextPath } from '@melandlabs/env-config';
 import { SQLiteRawMessageManager } from '@melandlabs/sqlite';
+import { applyReflectedConsolidationPlan } from '@melandlabs/memory-consolidation';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -14,8 +16,6 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-
-// src/contracts.ts
 var init_contracts = __esm({
   "src/contracts.ts"() {
   }
@@ -111,7 +111,7 @@ __export(sqlite_raw_message_store_exports, {
 function resolveSQLiteRawMessageDbPath(dbPath) {
   if (dbPath && dbPath.length > 0) return dbPath;
   const fromEnv = process.env.MEMORY_STORE_DB_PATH?.trim();
-  return fromEnv && fromEnv.length > 0 ? fromEnv : DEFAULT_SQLITE_PATH;
+  return fromEnv && fromEnv.length > 0 ? fromEnv : getOpenContextPath("memory", "store.db");
 }
 function isSQLiteRawMessageStorageAvailable(_env) {
   return true;
@@ -145,12 +145,11 @@ async function lexicalSearchRawMessages(input) {
   }
   return mgr.lexicalSearchMessages(input);
 }
-var manager, DEFAULT_SQLITE_PATH;
+var manager;
 var init_sqlite_raw_message_store = __esm({
   "src/storage/sqlite-raw-message-store.ts"() {
     init_chroma_memory_index();
     manager = null;
-    DEFAULT_SQLITE_PATH = join(homedir(), ".opencontext", "memory", "store.db");
   }
 });
 
@@ -371,6 +370,416 @@ function isRawMemorySemanticResult(result) {
   const item = result;
   return typeof item.id === "string" && typeof item.content === "string" && typeof item.similarity === "number" && Boolean(item.metadata) && typeof item.metadata === "object";
 }
+async function resolveScopePeer(input) {
+  const peers = input.peerFilter ?? [];
+  if (peers.length === 0) {
+    return { peers: [], warnings: [] };
+  }
+  if (typeof input.scopeCheck !== "function") {
+    return { peers, warnings: [] };
+  }
+  const retained = [];
+  const dropped = [];
+  for (const peer of peers) {
+    const ok = await input.scopeCheck({ userId: input.userId, peers: [peer] });
+    if (ok) {
+      retained.push(peer);
+    } else {
+      dropped.push(peer);
+    }
+  }
+  if (dropped.length === 0) {
+    return { peers, warnings: [] };
+  }
+  if (retained.length === 0) {
+    return {
+      peers: [],
+      warnings: [
+        {
+          source: "memory",
+          code: "peer_filter_outside_user_scope",
+          message: `${dropped.map((peer) => `${peer.kind}:${peer.id}`).join(",")} ignored; falling back to userId scope`
+        }
+      ]
+    };
+  }
+  return {
+    peers: retained,
+    warnings: [
+      {
+        source: "memory",
+        code: "peer_filter_outside_user_scope",
+        message: `${dropped.map((peer) => `${peer.kind}:${peer.id}`).join(",")} ignored because they fall outside userId ${input.userId}`
+      }
+    ]
+  };
+}
+
+// src/search/apply-reflect.ts
+var DEFAULT_TIERS = ["summary", "raw", "insight", "knowledge"];
+function reflectTierToEvidenceTier(source) {
+  switch (source) {
+    case "raw":
+      return "short";
+    case "summary":
+      return "long";
+    default:
+      return "mid";
+  }
+}
+function toMemoryEvidenceRecord(input, fallbackUserId) {
+  const tier = reflectTierToEvidenceTier(input.source);
+  const timestamp = input.timestamp ?? Date.now();
+  return {
+    id: input.id,
+    userId: fallbackUserId,
+    timestamp,
+    tier,
+    text: input.snippet,
+    metadata: {
+      source: input.source,
+      score: input.score,
+      ...input.timestamp !== void 0 ? { originalTimestamp: input.timestamp } : {}
+    }
+  };
+}
+async function applyReflectedPlan(deps, store, input, _logger) {
+  const query = input.query.trim();
+  const warnings = [];
+  const limit = clampUnifiedMemorySearchLimit(input.limit);
+  const threshold = clampUnifiedMemorySearchThreshold(input.threshold);
+  const tiers = input.tiers && input.tiers.length > 0 ? input.tiers : DEFAULT_TIERS;
+  const searchInput = {
+    userId: input.userId,
+    query,
+    botIds: input.botIds,
+    dateFrom: input.dateFrom,
+    dateTo: input.dateTo,
+    tiers,
+    limit,
+    threshold,
+    authToken: input.authToken,
+    peerFilter: input.peerFilter,
+    synthesize: true
+  };
+  const search = createUnifiedSearch(deps);
+  const result = await search.search(searchInput);
+  warnings.push(...result.warnings);
+  const evidence = result.evidence.map((item) => ({
+    id: item.id,
+    source: item.source ?? "raw",
+    snippet: item.snippet,
+    score: item.score,
+    timestamp: item.timestamp
+  }));
+  const records = evidence.map((item) => toMemoryEvidenceRecord(item, input.userId));
+  const applyInput = {
+    userId: input.userId,
+    ownerScope: input.ownerScope,
+    records,
+    plan: input.plan,
+    dryRun: input.dryRun,
+    expectedVersion: input.expectedVersion,
+    getClusterKey: input.getClusterKey ?? defaultClusterKey,
+    llmReview: deps.reasoning?.complete ? {
+      complete: deps.reasoning.complete,
+      maxTokens: input.llmPlanReview?.maxTokens
+    } : void 0,
+    graphStore: input.graphStore ?? store.graphStore,
+    storage: input.storage ?? store.storage
+  };
+  const applyOutput = await applyReflectedConsolidationPlan(applyInput);
+  for (const warning of applyOutput.warnings) {
+    warnings.push({
+      source: "memory",
+      code: warning.code,
+      message: warning.message
+    });
+  }
+  const summaryAnswer = makePlanSummary(applyOutput.plan);
+  return {
+    answer: result.answer ? `${result.answer}
+
+Plan summary:
+${summaryAnswer}` : summaryAnswer,
+    plan: applyOutput.plan,
+    persistenceResult: applyOutput.persistenceResult,
+    deprecationCounts: applyOutput.deprecationCounts,
+    warnings,
+    applied: applyOutput.applied,
+    evidence
+  };
+}
+function defaultClusterKey(record) {
+  return record.text ?? record.id;
+}
+function makePlanSummary(plan) {
+  const lines = [];
+  const counts = {
+    preserve: plan.actions.preserve.length,
+    observe: plan.actions.observe.length,
+    decay: plan.actions.decay.length,
+    deprecate: plan.actions.deprecate.length
+  };
+  lines.push(
+    `- preserve=${counts.preserve} observe=${counts.observe} decay=${counts.decay} deprecate=${counts.deprecate}`
+  );
+  for (const entry of plan.actions.deprecate.slice(0, 5)) {
+    lines.push(
+      `  deprecate ${entry.recordIds.length} record(s) from cluster ${entry.clusterKey} -> ${entry.supersededBySummaryId ?? entry.winningClusterKey}`
+    );
+  }
+  return lines.join("\n");
+}
+
+// src/search/reranker.ts
+async function applyReranker(reranker, query, results) {
+  if (!reranker || results.length === 0) {
+    return results;
+  }
+  const scores = await reranker.rerank({
+    query,
+    candidates: results.map((result) => ({
+      id: result.id,
+      content: result.content,
+      metadata: result.metadata
+    }))
+  });
+  if (scores.length === 0) {
+    return results;
+  }
+  const byId = new Map(results.map((result) => [result.id, result]));
+  const reordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const { id, score } of scores) {
+    const hit = byId.get(id);
+    if (!hit || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    reordered.push({ ...hit, metadata: { ...hit.metadata, rerankerScore: score } });
+  }
+  for (const hit of results) {
+    if (!seen.has(hit.id)) {
+      reordered.push(hit);
+    }
+  }
+  return reordered;
+}
+
+// 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;
+  return {
+    type: "memory",
+    id: row.summaryId,
+    content: row.summaryText,
+    similarity: 1,
+    metadata: {
+      tier: "summary",
+      summaryTier: row.summaryTier,
+      keywords: row.keywords,
+      startTimestamp: start,
+      endTimestamp: end
+    }
+  };
+}
+async function gatherSummaries(deps, input, limit, threshold, logger, peerPeers) {
+  if (typeof deps.searchSummaries !== "function") {
+    return { hits: [], warnings: [] };
+  }
+  const keywords = input.query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((token) => token.length >= 2).slice(0, 16);
+  try {
+    const rows = await deps.searchSummaries({
+      userId: input.userId,
+      query: input.query,
+      keywords,
+      limit,
+      threshold,
+      authToken: input.authToken,
+      ...peerPeers.length > 0 ? { peers: peerPeers } : {}
+    });
+    const hits = rows.map(toSummaryResult);
+    return { hits, warnings: [] };
+  } catch (error) {
+    logger.warn?.("[memory-store] gather-evidence: summary search failed:", error);
+    return {
+      hits: [],
+      warnings: [
+        {
+          source: "memory",
+          code: "reflect_summaries_failed",
+          message: error.message ?? "reflect_summaries_failed"
+        }
+      ]
+    };
+  }
+}
+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) {
+    const bucket = grouped.get(item.source) ?? [];
+    bucket.push(item);
+    grouped.set(item.source, bucket);
+  }
+  const sections = [];
+  for (const tier of DEFAULT_TIERS2) {
+    const items = grouped.get(tier) ?? [];
+    if (items.length === 0) {
+      continue;
+    }
+    const lines = items.map(
+      (item, index) => `  [${index + 1}] (${item.id}, score=${item.score.toFixed(4)}) ${item.snippet}`
+    );
+    sections.push(`## ${tier}
+${lines.join("\n")}`);
+  }
+  const schemaDirective = input.responseSchema ? `
+Respond with a JSON object that conforms to the following schema:
+${JSON.stringify(input.responseSchema, null, 2)}
+Wrap your JSON in a single fenced \`\`\`json code block; do not add any prose outside the code block.` : "\nRespond in plain prose. Be concise; cite evidence by its [n] number.";
+  if (sections.length === 0) {
+    return `You are a reflection assistant.
+
+Question: ${input.query}
+
+No evidence was found across any tier. State that explicitly.${schemaDirective}`;
+  }
+  return `You are a reflection assistant. Synthesise the user's question using only the evidence below. Do not invent facts.
+
+Question: ${input.query}
+
+Evidence (grouped by tier):
+${sections.join("\n\n")}${schemaDirective}`;
+}
+function extractJsonPayload(text) {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+  if (fenced?.[1]) {
+    return fenced[1];
+  }
+  const start = text.indexOf("{");
+  if (start === -1) {
+    return void 0;
+  }
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i += 1) {
+    const ch = text[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inString) {
+      if (ch === "\\") {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === "{") {
+      depth += 1;
+    } else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(start, i + 1);
+      }
+    }
+  }
+  return void 0;
+}
+function coerceAnswer(text, schema) {
+  if (!schema) {
+    return text;
+  }
+  const payload = extractJsonPayload(text);
+  if (!payload) {
+    return text;
+  }
+  try {
+    const parsed = JSON.parse(payload);
+    if (parsed && typeof parsed === "object") {
+      const answer = parsed.answer;
+      if (typeof answer === "string") {
+        return answer;
+      }
+    }
+  } catch {
+  }
+  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 warnings = [];
+  const complete = deps.reasoning?.complete;
+  if (!complete) {
+    warnings.push({
+      source: "memory",
+      code: "reflect_llm_not_configured",
+      message: "No `reasoning.complete` callback is configured; search() returned evidence without an LLM synthesis."
+    });
+    return { answer: "", warnings };
+  }
+  const prompt = buildSynthesisPrompt({ query, evidence, responseSchema });
+  try {
+    const raw = await complete(prompt);
+    const answer = coerceAnswer(raw, responseSchema);
+    logger.log?.("[memory-store] search synthesis completed", {
+      evidenceCount: evidence.length,
+      answerChars: answer.length
+    });
+    return { answer, warnings };
+  } catch (error) {
+    logger.warn?.("[memory-store] search synthesis failed:", error);
+    warnings.push({
+      source: "memory",
+      code: "reflect_llm_failed",
+      message: error.message ?? "reflect_llm_failed"
+    });
+    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;
+}
+async function resolveSearchScopePeers(input) {
+  return resolveScopePeer({
+    userId: input.userId,
+    peerFilter: input.peerFilter,
+    scopeCheck: input.deps.peerScopeCheck
+  });
+}
 
 // src/search/unified-search.ts
 function deriveLexicalKeywords(query) {
@@ -442,7 +851,7 @@ async function embedQueryVariant(embedQuery, input, query) {
     authToken: input.authToken
   });
 }
-async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger) {
+async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger, peerPeers = []) {
   const filters = input.botIds && input.botIds.length > 0 ? input.botIds.map((botId) => ({ botId })) : [{}];
   let semantic = [];
   if (isRawMessageChromaEnabled()) {
@@ -472,6 +881,7 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
     }
   } 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({
@@ -479,7 +889,9 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
           queryEmbedding,
           limit,
           threshold,
-          botId: "botId" in filter ? filter.botId : void 0
+          botId: "botId" in filter ? filter.botId : void 0,
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+          ...factTypes ? { factTypes } : {}
         })
       )
     )).flat().filter(isRawMemorySemanticResult).map(toMemoryResult);
@@ -489,11 +901,14 @@ async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit,
       const { getRawMessageManager: getRawMessageManager2 } = await Promise.resolve().then(() => (init_raw_message_store(), raw_message_store_exports));
       const manager2 = await getRawMessageManager2();
       if (typeof manager2.searchMessagesSemantically === "function") {
+        const factTypes = input.factTypes?.length ? input.factTypes : void 0;
         const results = await manager2.searchMessagesSemantically({
           userId: input.userId,
           queryEmbedding,
           limit,
-          threshold
+          threshold,
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+          ...factTypes ? { factTypes } : {}
         });
         semantic = results.map((r) => ({
           type: "memory",
@@ -529,7 +944,7 @@ function toIterativeRecallCandidate(hit) {
     metadata: hit.metadata
   };
 }
-async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger) {
+async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger, peerPeers = []) {
   if (keywords.length === 0) {
     return [];
   }
@@ -537,13 +952,16 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger)
     try {
       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;
       return (await Promise.all(
         filters.map(
           (botId) => searchRawMessagesLexical({
             userId: input.userId,
             keywords,
             limit: Math.ceil(limit / filters.length),
-            botId
+            botId,
+            ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+            ...factTypes ? { factTypes } : {}
           })
         )
       )).flat().filter(isRawMemorySemanticResult).map((hit) => ({
@@ -557,13 +975,15 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger)
   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;
     return (await Promise.all(
       filters.map(
         (botId) => lexicalSearchRawMessages2({
           userId: input.userId,
           keywords,
           limit: Math.ceil(limit / filters.length),
-          botId
+          botId,
+          ...factTypes ? { factTypes } : {}
         })
       )
     )).flat().filter(Boolean).map(
@@ -576,6 +996,42 @@ async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger)
   }
   return [];
 }
+function searchInputToUnified(input) {
+  return {
+    userId: input.userId,
+    query: input.query,
+    sources: input.sources ? [...input.sources] : void 0,
+    limit: input.limit,
+    threshold: input.threshold,
+    authToken: input.authToken,
+    includeArchivedInsights: input.includeArchivedInsights,
+    botIds: input.botIds,
+    documentIds: input.documentIds,
+    asOf: input.asOf,
+    dateFrom: input.dateFrom,
+    dateTo: input.dateTo,
+    mergeStrategy: input.mergeStrategy,
+    peerFilter: input.peerFilter,
+    reasoningStrategy: input.reasoningStrategy,
+    factTypes: input.factTypes
+  };
+}
+function mapHitToEvidenceSource(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 createUnifiedSearch(deps = {}) {
   const logger = deps.logger ?? console;
   function resolveReasoningStrategy(input) {
@@ -585,130 +1041,7 @@ function createUnifiedSearch(deps = {}) {
     }
     return normalizeUnifiedMemoryReasoningStrategy(deps.reasoning?.defaultStrategy, "none");
   }
-  async function searchUnifiedMemory(input) {
-    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);
-    const reasoningStrategy = resolveReasoningStrategy(input);
-    const warnings = [];
-    if (!query) {
-      return {
-        query,
-        sources,
-        results: [],
-        count: 0,
-        warnings
-      };
-    }
-    let memorySubs;
-    const reasoningInfo = { strategy: reasoningStrategy };
-    if (input.dateFrom || input.dateTo) {
-      reasoningInfo.dateRange = { from: input.dateFrom, to: input.dateTo };
-    }
-    if (sources.includes("memory")) {
-      if (isRawMessageStorageAvailable()) {
-        try {
-          memorySubs = await runMemorySource(
-            input,
-            limit,
-            threshold,
-            warnings,
-            reasoningStrategy,
-            reasoningInfo
-          );
-        } catch (error) {
-          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.`
-          });
-        }
-      } else {
-        warnings.push({
-          source: "memory",
-          code: "raw_message_storage_unavailable",
-          message: "Raw memory storage is not available in this environment."
-        });
-      }
-    }
-    const insightHits = [];
-    if (sources.includes("insights") && typeof deps.searchInsights === "function") {
-      try {
-        const hits = await deps.searchInsights({
-          userId: input.userId,
-          query: input.query,
-          limit,
-          threshold,
-          botIds: input.botIds,
-          includeArchived: input.includeArchivedInsights,
-          authToken: input.authToken
-        });
-        for (const hit of hits) {
-          insightHits.push({
-            type: "insight",
-            id: hit.id,
-            content: hit.content,
-            similarity: hit.similarity,
-            metadata: hit.metadata
-          });
-        }
-      } catch (error) {
-        logger.warn?.("[memory-store] insights source failed:", error);
-        warnings.push({
-          source: "insights",
-          code: "insights_search_failed",
-          message: error.message ?? "insights_search_failed"
-        });
-      }
-    } else if (sources.includes("insights")) ;
-    const knowledgeHits = [];
-    if (sources.includes("knowledge") && typeof deps.searchKnowledge === "function") {
-      try {
-        const hits = await deps.searchKnowledge({
-          userId: input.userId,
-          query: input.query,
-          options: {
-            limit,
-            threshold,
-            documentIds: input.documentIds
-          },
-          authToken: input.authToken
-        });
-        for (const hit of hits) {
-          knowledgeHits.push(toKnowledgeResult(hit));
-        }
-      } catch (error) {
-        logger.warn?.("[memory-store] knowledge source failed:", error);
-        warnings.push({
-          source: "knowledge",
-          code: "knowledge_search_failed",
-          message: error.message ?? "knowledge_search_failed"
-        });
-      }
-    } else if (sources.includes("knowledge")) ;
-    const merged = mergeAcrossSources({
-      memorySubs,
-      insightHits,
-      knowledgeHits,
-      limit,
-      strategy: mergeStrategy
-    });
-    const output = {
-      query: input.query,
-      sources,
-      results: merged,
-      count: merged.length,
-      warnings
-    };
-    if (reasoningInfo && (reasoningInfo.strategy !== "none" || reasoningInfo.dateRange !== void 0)) {
-      output.reasoning = reasoningInfo;
-    }
-    return output;
-  }
-  async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo) {
+  async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo, peerPeers = []) {
     if (reasoningStrategy === "iterative" && !deps.reasoning?.iterativePlanner) {
       warnings.push({
         source: "memory",
@@ -734,7 +1067,14 @@ function createUnifiedSearch(deps = {}) {
         executor: {
           search: async (request) => {
             const keywords2 = request.keywords.length > 0 ? request.keywords : deriveLexicalKeywords(input.query);
-            const lexicalHits = await runLexicalSearchForKeywords(deps, input, keywords2, limit, logger);
+            const lexicalHits = await runLexicalSearchForKeywords(
+              deps,
+              input,
+              keywords2,
+              limit,
+              logger,
+              peerPeers
+            );
             let semanticHits = [];
             if (typeof deps.embedQuery === "function") {
               try {
@@ -746,7 +1086,8 @@ function createUnifiedSearch(deps = {}) {
                   queryEmbedding,
                   limit,
                   threshold,
-                  logger
+                  logger,
+                  peerPeers
                 );
               } catch (error) {
                 logger.warn?.(
@@ -791,7 +1132,7 @@ function createUnifiedSearch(deps = {}) {
       });
       const keywords2 = deriveLexicalKeywords(input.query);
       const lexical2 = filterByDateRange(
-        await runLexicalSearchForKeywords(deps, input, keywords2, limit, logger),
+        await runLexicalSearchForKeywords(deps, input, keywords2, limit, logger, peerPeers),
         input.dateFrom,
         input.dateTo
       );
@@ -817,7 +1158,7 @@ function createUnifiedSearch(deps = {}) {
         );
         const lists = await Promise.all(
           embeddings.map(
-            (embedding) => runSemanticSearchForEmbedding(deps, input, embedding, limit, threshold, logger)
+            (embedding) => runSemanticSearchForEmbedding(deps, input, embedding, limit, threshold, logger, peerPeers)
           )
         );
         semantic = mergeByMaxScore(lists);
@@ -833,7 +1174,15 @@ function createUnifiedSearch(deps = {}) {
     }
     if (semantic.length === 0) {
       const queryEmbedding = await embedQueryVariant(embedQuery, input, input.query);
-      semantic = await runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger);
+      semantic = await runSemanticSearchForEmbedding(
+        deps,
+        input,
+        queryEmbedding,
+        limit,
+        threshold,
+        logger,
+        peerPeers
+      );
     }
     let lexical = [];
     const keywords = deriveLexicalKeywords(input.query);
@@ -842,13 +1191,16 @@ function createUnifiedSearch(deps = {}) {
         try {
           const lexFilters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
           const searchRawMessagesLexical = deps.searchRawMessagesLexical;
+          const factTypes = input.factTypes?.length ? input.factTypes : void 0;
           lexical = (await Promise.all(
             lexFilters.map(
               (botId) => searchRawMessagesLexical({
                 userId: input.userId,
                 keywords,
                 limit,
-                botId
+                botId,
+                ...peerPeers.length > 0 ? { peers: peerPeers } : {},
+                ...factTypes ? { factTypes } : {}
               })
             )
           )).flat().filter(isRawMemorySemanticResult).map((hit) => ({
@@ -876,20 +1228,272 @@ function createUnifiedSearch(deps = {}) {
       lexical: filterByDateRange(lexical, input.dateFrom, input.dateTo)
     };
   }
+  async function searchUnifiedMemory(input) {
+    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 reasoningStrategy = resolveReasoningStrategy(input);
+    const warnings = [];
+    const peerScope = input.peerFilter && input.peerFilter.length > 0 ? await resolveScopePeer({
+      userId: input.userId,
+      peerFilter: input.peerFilter,
+      scopeCheck: deps.peerScopeCheck
+    }) : { peers: [], warnings: [] };
+    warnings.push(...peerScope.warnings);
+    const peerPeers = peerScope.peers;
+    if (!query) {
+      return {
+        query,
+        sources,
+        results: [],
+        count: 0,
+        warnings
+      };
+    }
+    let memorySubs;
+    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";
+      if (isRawMessageStorageAvailable() || hasRawProviders) {
+        try {
+          memorySubs = await runMemorySource(
+            input,
+            limit,
+            threshold,
+            warnings,
+            reasoningStrategy,
+            reasoningInfo,
+            peerPeers
+          );
+        } catch (error) {
+          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.`
+          });
+        }
+      } else {
+        warnings.push({
+          source: "memory",
+          code: "raw_message_storage_unavailable",
+          message: "Raw memory storage is not available in this environment."
+        });
+      }
+    }
+    const insightHits = [];
+    if (sources.includes("insights") && typeof deps.searchInsights === "function") {
+      try {
+        const hits = await deps.searchInsights({
+          userId: input.userId,
+          query: input.query,
+          limit,
+          threshold,
+          botIds: input.botIds,
+          includeArchived: input.includeArchivedInsights,
+          authToken: input.authToken,
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {}
+        });
+        for (const hit of hits) {
+          insightHits.push({
+            type: "insight",
+            id: hit.id,
+            content: hit.content,
+            similarity: hit.similarity,
+            metadata: hit.metadata
+          });
+        }
+      } catch (error) {
+        logger.warn?.("[memory-store] insights source failed:", error);
+        warnings.push({
+          source: "insights",
+          code: "insights_search_failed",
+          message: error.message ?? "insights_search_failed"
+        });
+      }
+    } else if (sources.includes("insights")) ;
+    const knowledgeHits = [];
+    if (sources.includes("knowledge") && typeof deps.searchKnowledge === "function") {
+      try {
+        const hits = await deps.searchKnowledge({
+          userId: input.userId,
+          query: input.query,
+          options: {
+            limit,
+            threshold,
+            documentIds: input.documentIds
+          },
+          authToken: input.authToken,
+          ...peerPeers.length > 0 ? { peers: peerPeers } : {}
+        });
+        for (const hit of hits) {
+          knowledgeHits.push(toKnowledgeResult(hit));
+        }
+      } catch (error) {
+        logger.warn?.("[memory-store] knowledge source failed:", error);
+        warnings.push({
+          source: "knowledge",
+          code: "knowledge_search_failed",
+          message: error.message ?? "knowledge_search_failed"
+        });
+      }
+    } else if (sources.includes("knowledge")) ;
+    const merged = mergeAcrossSources({
+      memorySubs,
+      insightHits,
+      knowledgeHits,
+      limit,
+      strategy: mergeStrategy
+    });
+    const ranked = await applyReranker(deps.reranker, input.query, merged);
+    const output = {
+      query: input.query,
+      sources,
+      results: ranked,
+      count: ranked.length,
+      warnings
+    };
+    if (reasoningInfo && (reasoningInfo.strategy !== "none" || reasoningInfo.dateRange !== void 0)) {
+      output.reasoning = reasoningInfo;
+    }
+    return output;
+  }
   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: normalizeUnifiedMemoryMergeStrategy(input.mergeStrategy)
+      strategy: mergeStrategy
     });
   }
-  return { searchUnifiedMemory, searchRawMemorySemantically };
+  async function search(input) {
+    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;
+    const peerScope = await resolveSearchScopePeers({
+      deps,
+      userId: input.userId,
+      peerFilter: input.peerFilter
+    });
+    if (!query) {
+      const empty = {
+        query,
+        sources: input.sources ? [...input.sources] : [],
+        results: [],
+        evidence: [],
+        count: 0,
+        warnings: peerScope.warnings,
+        answer: ""
+      };
+      return empty;
+    }
+    const tiers = input.tiers ? [...input.tiers] : wantsSynthesis ? ["summary", "raw", "insight", "knowledge"] : ["raw", "insight", "knowledge"];
+    const wantsSummaryTier = tiers.includes("summary");
+    const wantsRawTier = tiers.includes("raw");
+    const wantsInsightTier = tiers.includes("insight");
+    const wantsKnowledgeTier = tiers.includes("knowledge");
+    const warnings = [...peerScope.warnings];
+    const limit = clampUnifiedMemorySearchLimit(input.limit);
+    const threshold = clampUnifiedMemorySearchThreshold(input.threshold);
+    let unifiedHits = [];
+    let sources = input.sources ? [...input.sources] : [];
+    let unifiedReasoning;
+    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
+      });
+      unifiedHits = unified.results;
+      sources = unified.sources;
+      unifiedReasoning = unified.reasoning;
+      warnings.push(...unified.warnings);
+    }
+    let summaryHits = [];
+    if (wantsSummaryTier && typeof deps.searchSummaries === "function") {
+      const summaryBucket = await gatherSummaries(
+        deps,
+        { userId: input.userId, query: input.query, authToken: input.authToken },
+        limit,
+        threshold,
+        logger,
+        peerScope.peers
+      );
+      warnings.push(...summaryBucket.warnings);
+      summaryHits = summaryBucket.hits;
+    }
+    const tierLists = [];
+    if (unifiedHits.length > 0) {
+      tierLists.push({ name: "memory", hits: unifiedHits });
+    }
+    if (summaryHits.length > 0) {
+      tierLists.push({ name: "summary", hits: summaryHits });
+    }
+    let hits;
+    if (tierLists.length === 0) {
+      hits = [];
+    } else if (tierLists.length === 1) {
+      hits = tierLists[0].hits.slice(0, limit);
+    } else {
+      hits = mergeUnifiedMemorySearchResultsRrf(tierLists, limit);
+    }
+    const evidence = hits.map((hit) => ({
+      id: hit.id,
+      source: mapHitToEvidenceSource(hit),
+      snippet: hit.content,
+      score: hit.similarity,
+      timestamp: getCandidateTimestamp(hit.metadata)
+    }));
+    const base = {
+      query,
+      sources,
+      results: hits,
+      evidence,
+      count: hits.length,
+      warnings
+    };
+    if (unifiedReasoning) {
+      base.reasoning = unifiedReasoning;
+    }
+    if (!wantsSynthesis) {
+      return base;
+    }
+    const { answer, warnings: synthWarnings } = await synthesizeAnswer({
+      query,
+      hits,
+      responseSchema: synthesisSchema,
+      deps,
+      logger
+    });
+    base.answer = answer;
+    base.warnings = [...base.warnings, ...synthWarnings];
+    return base;
+  }
+  return {
+    search,
+    searchUnifiedMemory,
+    searchRawMemorySemantically,
+    consolidate: (input) => applyReflectedPlan(deps, {}, input)
+  };
 }
 function mergeAcrossSources(input) {
   const memorySubs = input.memorySubs ?? { semantic: [], lexical: [] };