@melandlabs/memory-store 0.3.1 → 1.0.0

package/dist/mcp.js

@@ -1,12 +1,15 @@
+import { vsaNormalizeVector, vsaAssertSameDim } from '@melandlabs/contracts';
 import { buildMemoryRecordEmbeddingDocument } from '@melandlabs/ai/memory';
 import { ChromaVectorStore } from '@melandlabs/rag';
 import { mkdirSync } from 'fs';
 import { dirname } from 'path';
 import { getOpenContextPath } from '@melandlabs/env-config';
-import { SQLiteRawMessageManager } from '@melandlabs/sqlite';
+import { SQLiteRawMessageManager, getSQLiteVsaStore } from '@melandlabs/sqlite';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { applyReflectedConsolidationPlan } from '@melandlabs/memory-consolidation';
+import { superpose, bind, unbind, cleanup, cosineSimilarity } from '@melandlabs/vsa';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -17,8 +20,6 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-
-// src/contracts.ts
 function normalizeTimestampToMs(value) {
   if (!Number.isFinite(value)) {
     return 0;
@@ -325,6 +326,41 @@ var init_raw_message_store = __esm({
 init_chroma_memory_index();
 init_raw_message_store();
 
+// 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/utilities.ts
 var DEFAULT_LIMIT = 10;
 var DEFAULT_THRESHOLD = 0.7;
@@ -446,6 +482,264 @@ 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/gather-evidence.ts
+var DEFAULT_TIERS = ["summary", "raw", "insight", "knowledge"];
+var MAX_EVIDENCE_CHARS = 600;
+function toSummaryResult(row) {
+  const start = typeof row.startTimestamp === "number" ? row.startTimestamp : void 0;
+  const end = typeof row.endTimestamp === "number" ? row.endTimestamp : void 0;
+  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_TIERS) {
+    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) {
@@ -517,7 +811,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()) {
@@ -547,6 +841,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({
@@ -554,7 +849,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);
@@ -564,11 +861,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",
@@ -604,7 +904,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 [];
   }
@@ -612,13 +912,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) => ({
@@ -632,13 +935,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(
@@ -651,6 +956,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) {
@@ -660,130 +1001,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",
@@ -809,7 +1027,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 {
@@ -821,7 +1046,8 @@ function createUnifiedSearch(deps = {}) {
                   queryEmbedding,
                   limit,
                   threshold,
-                  logger
+                  logger,
+                  peerPeers
                 );
               } catch (error) {
                 logger.warn?.(
@@ -866,7 +1092,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
       );
@@ -892,7 +1118,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);
@@ -908,7 +1134,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);
@@ -917,13 +1151,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) => ({
@@ -951,35 +1188,287 @@ function createUnifiedSearch(deps = {}) {
       lexical: filterByDateRange(lexical, input.dateFrom, input.dateTo)
     };
   }
-  async function searchRawMemorySemantically(input) {
+  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 sub = await runMemorySource(input, limit, threshold, [], reasoningStrategy);
-    return mergeAcrossSources({
-      memorySubs: sub,
-      insightHits: [],
-      knowledgeHits: [],
-      limit,
-      strategy: normalizeUnifiedMemoryMergeStrategy(input.mergeStrategy)
-    });
-  }
-  return { searchUnifiedMemory, searchRawMemorySemantically };
-}
-function mergeAcrossSources(input) {
-  const memorySubs = input.memorySubs ?? { semantic: [], lexical: [] };
-  const all = [
-    ...memorySubs.semantic,
-    ...memorySubs.lexical,
-    ...input.insightHits,
-    ...input.knowledgeHits
-  ];
-  if (input.strategy !== "rrf") {
-    return mergeUnifiedMemorySearchResults(all, input.limit);
-  }
-  const lists = [];
-  if (memorySubs.semantic.length > 0) {
-    lists.push({ name: "memory-semantic", hits: memorySubs.semantic });
+    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: mergeStrategy
+    });
+  }
+  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: [] };
+  const all = [
+    ...memorySubs.semantic,
+    ...memorySubs.lexical,
+    ...input.insightHits,
+    ...input.knowledgeHits
+  ];
+  if (input.strategy !== "rrf") {
+    return mergeUnifiedMemorySearchResults(all, input.limit);
+  }
+  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 });
@@ -996,9 +1485,283 @@ function mergeAcrossSources(input) {
   return mergeUnifiedMemorySearchResultsRrf(lists, input.limit);
 }
 
+// src/search/apply-reflect.ts
+var DEFAULT_TIERS2 = ["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_TIERS2;
+  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");
+}
+var DEFAULT_MAX_FACTS = 1e3;
+var LOW_CONFIDENCE_THRESHOLD = 0.1;
+function toHRR(data) {
+  const arr = data instanceof Float32Array ? data : new Float32Array(data);
+  return { dim: arr.length, data: arr };
+}
+function generateFactId() {
+  const stamp = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `vsa-${stamp}-${rand}`;
+}
+function createVsaRecall(storage) {
+  return {
+    async storeFact(input) {
+      const roleVector = vsaNormalizeVector(input.roleVector, "roleVector");
+      const fillerVector = vsaNormalizeVector(input.fillerVector, "fillerVector");
+      vsaAssertSameDim(roleVector, fillerVector, "storeFact");
+      const dim = input.dim ?? roleVector.length;
+      if (roleVector.length !== dim) {
+        throw new Error(`storeFact: roleVector.length (${roleVector.length}) must equal dim (${dim})`);
+      }
+      const now = Date.now();
+      const fact = {
+        factId: input.factId ?? generateFactId(),
+        userId: input.userId,
+        roleLabel: input.roleLabel,
+        fillerLabel: input.fillerLabel,
+        roleVector,
+        fillerVector,
+        dim,
+        scopeTag: input.scopeTag ?? "default",
+        botId: input.botId,
+        createdAt: now
+      };
+      await storage.storeFact(fact);
+      return { factId: fact.factId, createdAt: now };
+    },
+    async recall(input) {
+      const roleVector = vsaNormalizeVector(input.roleVector, "roleVector");
+      const scopeTag = input.scopeTag ?? "default";
+      const maxFacts = input.maxFacts ?? DEFAULT_MAX_FACTS;
+      if (input.vocabulary.length === 0) {
+        throw new Error("vsaRecall: vocabulary must contain at least one entry");
+      }
+      const facts = await storage.queryFacts({
+        userId: input.userId,
+        scopeTag,
+        botId: input.botId,
+        includeDeprecated: false,
+        limit: maxFacts
+      });
+      const warnings = [];
+      if (facts.length === 0) {
+        warnings.push({
+          code: "vsa_no_facts",
+          message: `No VSA facts for userId=${input.userId} scopeTag=${scopeTag}`
+        });
+        return {
+          fillerLabel: "",
+          score: 0,
+          allScores: [],
+          factCount: 0,
+          warnings
+        };
+      }
+      const refDim = facts[0].dim;
+      const dimMatchedFacts = facts.filter((fact) => {
+        if (fact.dim === refDim) return true;
+        warnings.push({
+          code: "vsa_dim_mismatch",
+          message: `Fact ${fact.factId} has dim=${fact.dim}, expected ${refDim}; skipping`
+        });
+        return false;
+      });
+      if (roleVector.length !== refDim) {
+        throw new Error(
+          `vsaRecall: roleVector dim (${roleVector.length}) must match stored fact dim (${refDim})`
+        );
+      }
+      if (dimMatchedFacts.length === 0) {
+        warnings.push({
+          code: "vsa_no_facts",
+          message: `All stored facts for userId=${input.userId} scopeTag=${scopeTag} had a non-matching dim`
+        });
+        return {
+          fillerLabel: "",
+          score: 0,
+          allScores: [],
+          factCount: 0,
+          warnings
+        };
+      }
+      const memoryVec = superpose(
+        dimMatchedFacts.map((fact) => bind(toHRR(fact.roleVector), toHRR(fact.fillerVector)))
+      );
+      const candidate = unbind(memoryVec, toHRR(roleVector));
+      const vocabVecs = input.vocabulary.map(
+        (entry) => toHRR(vsaNormalizeVector(entry.vector, `vocabulary[${entry.label}].vector`))
+      );
+      const bestVec = cleanup(candidate, vocabVecs);
+      const bestIdx = vocabVecs.indexOf(bestVec);
+      const allScores = input.vocabulary.map((entry, idx) => ({
+        label: entry.label,
+        score: cosineSimilarity(candidate, vocabVecs[idx])
+      }));
+      allScores.sort((a, b) => b.score - a.score);
+      const fillerLabel = bestIdx >= 0 ? input.vocabulary[bestIdx].label : "";
+      const score = allScores[0]?.score ?? 0;
+      if (score < LOW_CONFIDENCE_THRESHOLD) {
+        warnings.push({
+          code: "vsa_low_confidence",
+          message: `Best match "${fillerLabel}" score ${score.toFixed(3)} below ${LOW_CONFIDENCE_THRESHOLD}`
+        });
+      }
+      if (facts.length >= maxFacts) {
+        warnings.push({
+          code: "vsa_fact_limit_reached",
+          message: `Loaded ${facts.length} facts (cap=${maxFacts}); recall may degrade with more`
+        });
+      }
+      return {
+        fillerLabel,
+        score,
+        allScores,
+        factCount: facts.length,
+        warnings
+      };
+    },
+    async listFacts(input) {
+      const facts = await storage.queryFacts({
+        userId: input.userId,
+        scopeTag: input.scopeTag,
+        botId: input.botId,
+        includeDeprecated: input.includeDeprecated
+      });
+      return facts.map((fact) => ({
+        factId: fact.factId,
+        userId: fact.userId,
+        roleLabel: fact.roleLabel,
+        fillerLabel: fact.fillerLabel,
+        scopeTag: fact.scopeTag,
+        botId: fact.botId,
+        createdAt: fact.createdAt,
+        deprecatedAt: fact.deprecatedAt
+      }));
+    },
+    async forget(input) {
+      const result = await storage.deprecateFacts({
+        userId: input.userId,
+        factIds: input.factIds,
+        reason: input.reason
+      });
+      return { deprecatedCount: result.deprecatedCount };
+    }
+  };
+}
+
 // src/mcp.ts
 init_chroma_memory_index();
 init_raw_message_store();
+init_sqlite_raw_message_store();
 var DEFAULT_NAME = "@melandlabs/memory-store";
 var DEFAULT_VERSION = "0.1.0";
 async function embedMissingMessages(messages, deps) {
@@ -1038,6 +1801,9 @@ async function startMcpServer(options = {}) {
     env: options.env
   });
   const search = createUnifiedSearch(options.unified);
+  const vsaDbPath = resolveSQLiteRawMessageDbPath(options.dbPath);
+  const vsaStorage = await getSQLiteVsaStore({ dbPath: vsaDbPath });
+  const vsa = createVsaRecall(vsaStorage);
   server.tool("memory.health", "Returns the health status of the memory store.", async () => ({
     content: [{ type: "text", text: JSON.stringify({ ok: true }) }]
   }));
@@ -1045,6 +1811,15 @@ async function startMcpServer(options = {}) {
     userId: z.string(),
     query: z.string().min(1),
     sources: z.array(z.enum(["memory", "insights", "knowledge"])).optional().describe("Default: ['memory','insights','knowledge']"),
+    tiers: z.array(z.enum(["summary", "raw", "insight", "knowledge"])).optional().describe(
+      "Per-tier evidence scope for synthesis. Default: ['summary','raw','insight','knowledge']. Ignored when `synthesize` is falsy."
+    ),
+    synthesize: z.union([z.boolean(), z.object({ responseSchema: z.record(z.string(), z.unknown()).optional() })]).optional().describe(
+      "Opt-in LLM synthesis. `true` returns `{ answer, evidence, results, warnings }`. `synthesize.responseSchema` extracts `answer` from a JSON payload."
+    ),
+    // Top-level pass-through kept for backward-shaped callers; the SDK
+    // coerces it into `synthesize.responseSchema` when present.
+    responseSchema: z.record(z.string(), z.unknown()).optional(),
     limit: z.number().int().min(1).max(50).default(10),
     threshold: z.number().min(-1).max(1).default(0.7),
     botIds: z.array(z.string()).optional(),
@@ -1077,17 +1852,51 @@ async function startMcpServer(options = {}) {
     userId: z.string(),
     messageId: z.string()
   };
+  const reflectApplySchema = {
+    userId: z.string(),
+    query: z.string().min(1),
+    ownerScopeUserId: z.string().describe("Required: who owns the writes."),
+    botIds: z.array(z.string()).optional(),
+    dateFrom: z.string().optional(),
+    dateTo: z.string().optional(),
+    tiers: z.array(z.enum(["summary", "raw", "insight", "knowledge"])).optional().describe("Default: ['summary','raw','insight','knowledge']"),
+    limit: z.number().int().min(1).max(200).default(20),
+    threshold: z.number().min(-1).max(1).default(0.7),
+    dryRun: z.boolean().default(false),
+    expectedVersion: z.string().optional(),
+    llmPlanReviewMaxTokens: z.number().int().min(64).max(8192).optional(),
+    authToken: z.string().optional()
+  };
   server.registerTool(
-    "memory.searchUnified",
+    "memory.search",
     {
-      title: "Search Unified Memory",
-      description: "Semantic search across raw messages (always), and optionally insights and uploaded knowledge.",
+      title: "Search Memory",
+      description: "Cross-source semantic search across raw messages, insights, and uploaded knowledge. Set `synthesize: true` to opt into LLM synthesis over the gathered evidence. With synthesis enabled, the response carries `answer`, `evidence`, `results`, and `warnings`; otherwise just `results`, `evidence`, and `count`.",
       // biome-ignore lint/suspicious/noExplicitAny: MCP SDK expects Zod schema type
       inputSchema: searchSchema
     },
     async (args) => {
       const a = args;
-      const result = await search.searchUnifiedMemory(a);
+      const wantsSynthesis = typeof a.synthesize === "boolean" ? a.synthesize : typeof a.synthesize === "object" && a.synthesize !== null;
+      const responseSchema = typeof a.synthesize === "object" && a.synthesize !== null ? a.synthesize.responseSchema ?? a.responseSchema : a.responseSchema;
+      const input = {
+        userId: a.userId,
+        query: a.query,
+        sources: a.sources,
+        limit: a.limit,
+        threshold: a.threshold,
+        botIds: a.botIds,
+        documentIds: a.documentIds,
+        authToken: a.authToken,
+        includeArchivedInsights: a.includeArchivedInsights,
+        ...a.tiers ? { tiers: a.tiers } : {},
+        ...wantsSynthesis ? {
+          synthesize: {
+            ...responseSchema ? { responseSchema } : {}
+          }
+        } : {}
+      };
+      const result = await search.search(input);
       return {
         content: [{ type: "text", text: JSON.stringify(result) }]
       };
@@ -1155,6 +1964,212 @@ async function startMcpServer(options = {}) {
       };
     }
   );
+  server.registerTool(
+    "memory.consolidate",
+    {
+      title: "Consolidate",
+      description: "Agentic write-back: gathers evidence like `memory.search({ synthesize: true })`, builds a memory-consolidation plan, optionally asks the LLM to veto unsafe entries, then persists via the attached graph store + soft-deprecates via the storage adapter. Set `dryRun: true` to inspect the plan without writing.",
+      // biome-ignore lint/suspicious/noExplicitAny: MCP SDK expects Zod schema type
+      inputSchema: reflectApplySchema
+    },
+    async (args) => {
+      const a = args;
+      const input = {
+        userId: a.userId,
+        query: a.query,
+        ownerScope: { userId: a.ownerScopeUserId },
+        botIds: a.botIds,
+        dateFrom: a.dateFrom,
+        dateTo: a.dateTo,
+        tiers: a.tiers,
+        limit: a.limit,
+        threshold: a.threshold,
+        dryRun: a.dryRun ?? false,
+        expectedVersion: a.expectedVersion,
+        authToken: a.authToken,
+        llmPlanReview: a.llmPlanReviewMaxTokens !== void 0 ? { maxTokens: a.llmPlanReviewMaxTokens } : void 0
+      };
+      const result = await applyReflectedPlan(
+        { ...options.unified ?? {} },
+        { graphStore: options.graphStore, storage: options.storage },
+        input);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }]
+      };
+    }
+  );
+  const vsaVocabularyEntry = {
+    label: z.string().min(1),
+    vector: z.array(z.number()).describe("Float32 vector for the vocabulary entry.")
+  };
+  const vsaStoreSchema = {
+    userId: z.string(),
+    roleLabel: z.string().min(1),
+    fillerLabel: z.string().min(1),
+    roleVector: z.array(z.number()),
+    fillerVector: z.array(z.number()),
+    scopeTag: z.string().optional(),
+    botId: z.string().optional(),
+    factId: z.string().optional()
+  };
+  const vsaRecallSchema = {
+    userId: z.string(),
+    roleLabel: z.string().min(1),
+    roleVector: z.array(z.number()),
+    vocabulary: z.array(z.object(vsaVocabularyEntry).passthrough()),
+    scopeTag: z.string().optional(),
+    botId: z.string().optional(),
+    maxFacts: z.number().int().min(1).max(1e4).optional()
+  };
+  const vsaListSchema = {
+    userId: z.string(),
+    scopeTag: z.string().optional(),
+    botId: z.string().optional(),
+    includeDeprecated: z.boolean().default(false)
+  };
+  const vsaForgetSchema = {
+    userId: z.string(),
+    factIds: z.array(z.string()).min(1),
+    reason: z.string().optional()
+  };
+  server.registerTool(
+    "memory.vsaStore",
+    {
+      title: "VSA Store Fact",
+      description: "Persist a (role, filler) binding into the user's VSA memory. The vectors are stored as Float32 BLOBs alongside the labels; later `memory.vsaRecall` rebuilds the memory vector and picks the best vocabulary match.",
+      // biome-ignore lint/suspicious/noExplicitAny: MCP SDK expects Zod schema type
+      inputSchema: vsaStoreSchema
+    },
+    async (args) => {
+      const a = args;
+      try {
+        const result = await vsa.storeFact({
+          userId: a.userId,
+          roleLabel: a.roleLabel,
+          fillerLabel: a.fillerLabel,
+          roleVector: a.roleVector,
+          fillerVector: a.fillerVector,
+          scopeTag: a.scopeTag,
+          botId: a.botId,
+          factId: a.factId
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result) }]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: error.message ?? "vsa.store failed" })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "memory.vsaRecall",
+    {
+      title: "VSA Recall",
+      description: "Rebuild the user's VSA memory vector from stored (role, filler) facts, unbind by the requested role, and cleanup against the supplied vocabulary. Returns the best-match label plus a sorted score list and warnings (e.g. low confidence, dim mismatch).",
+      // biome-ignore lint/suspicious/noExplicitAny: MCP SDK expects Zod schema type
+      inputSchema: vsaRecallSchema
+    },
+    async (args) => {
+      const a = args;
+      try {
+        const result = await vsa.recall({
+          userId: a.userId,
+          roleLabel: a.roleLabel,
+          roleVector: a.roleVector,
+          vocabulary: a.vocabulary,
+          scopeTag: a.scopeTag,
+          botId: a.botId,
+          maxFacts: a.maxFacts
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result) }]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: error.message ?? "vsa.recall failed" })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "memory.vsaList",
+    {
+      title: "VSA List Facts",
+      description: "List the (role, filler) facts stored for a user. Vectors are stripped from the response \u2014 for the underlying storage layer, query SQLite directly.",
+      // biome-ignore lint/suspicious/noExplicitAny: MCP SDK expects Zod schema type
+      inputSchema: vsaListSchema
+    },
+    async (args) => {
+      const a = args;
+      try {
+        const facts = await vsa.listFacts({
+          userId: a.userId,
+          scopeTag: a.scopeTag,
+          botId: a.botId,
+          includeDeprecated: a.includeDeprecated
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify({ facts }) }]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: error.message ?? "vsa.list failed" })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "memory.vsaForget",
+    {
+      title: "VSA Forget Facts",
+      description: "Soft-delete one or more VSA facts by id. Idempotent \u2014 facts already deprecated return `deprecatedCount: 0`.",
+      // biome-ignore lint/suspicious/noExplicitAny: MCP SDK expects Zod schema type
+      inputSchema: vsaForgetSchema
+    },
+    async (args) => {
+      const a = args;
+      try {
+        const result = await vsa.forget({
+          userId: a.userId,
+          factIds: a.factIds,
+          reason: a.reason
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result) }]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: error.message ?? "vsa.forget failed" })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
   return server;