@melandlabs/memory-store 0.3.0 → 1.0.0

package/dist/http.js

@@ -1,11 +1,14 @@
+import { vsaNormalizeVector, vsaAssertSameDim } from '@melandlabs/contracts';
 import { buildMemoryRecordEmbeddingDocument } from '@melandlabs/ai/memory';
 import { ChromaVectorStore } from '@melandlabs/rag';
 import { mkdirSync } from 'fs';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
-import { SQLiteRawMessageManager } from '@melandlabs/sqlite';
+import { dirname } from 'path';
+import { getOpenContextPath } from '@melandlabs/env-config';
+import { SQLiteRawMessageManager, getSQLiteVsaStore, closeSQLiteVsaStore } from '@melandlabs/sqlite';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
+import { applyReflectedConsolidationPlan } from '@melandlabs/memory-consolidation';
+import { superpose, bind, unbind, cleanup, cosineSimilarity } from '@melandlabs/vsa';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -16,8 +19,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;
@@ -186,7 +187,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;
@@ -220,12 +221,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");
   }
 });
 
@@ -325,6 +325,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 +481,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 +810,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 +840,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 +848,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 +860,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 +903,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 +911,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 +934,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 +955,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 +1000,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 +1026,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 +1045,8 @@ function createUnifiedSearch(deps = {}) {
                   queryEmbedding,
                   limit,
                   threshold,
-                  logger
+                  logger,
+                  peerPeers
                 );
               } catch (error) {
                 logger.warn?.(
@@ -866,7 +1091,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 +1117,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 +1133,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 +1150,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,20 +1187,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: [] };
@@ -996,9 +1484,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/http.ts
 init_chroma_memory_index();
 init_raw_message_store();
+init_sqlite_raw_message_store();
 async function embedMissingMessages(messages, deps) {
   if (typeof deps.embedQuery !== "function") {
     return messages;
@@ -1050,6 +1812,9 @@ async function startHttpServer(options = {}) {
       return [];
     }
   });
+  const vsaDbPath = resolveSQLiteRawMessageDbPath(options.dbPath);
+  const vsaStorage = await getSQLiteVsaStore({ dbPath: vsaDbPath });
+  const vsa = createVsaRecall(vsaStorage);
   const app = new Hono();
   app.get("/health", (c) => c.json({ ok: true, store: "memory", ts: Date.now() }));
   app.post("/v1/search", async (c) => {
@@ -1059,17 +1824,62 @@ async function startHttpServer(options = {}) {
     if (!userId || !query) {
       return c.json({ error: "userId and query are required" }, 400);
     }
-    const result = await search.searchUnifiedMemory({
+    const wantsSynthesis = typeof body.synthesize === "boolean" ? body.synthesize : typeof body.synthesize === "object" && body.synthesize !== null;
+    const responseSchema = typeof body.synthesize === "object" && body.synthesize !== null ? body.synthesize.responseSchema ?? body.responseSchema : body.responseSchema;
+    const input = {
       userId,
       query,
-      sources: body.sources,
-      limit: body.limit,
-      threshold: body.threshold,
-      botIds: body.botIds,
-      documentIds: body.documentIds,
-      includeArchivedInsights: body.includeArchivedInsights,
-      authToken: body.authToken
-    });
+      sources: Array.isArray(body.sources) ? body.sources : void 0,
+      tiers: Array.isArray(body.tiers) ? body.tiers : void 0,
+      limit: typeof body.limit === "number" ? body.limit : void 0,
+      threshold: typeof body.threshold === "number" ? body.threshold : void 0,
+      botIds: Array.isArray(body.botIds) ? body.botIds : void 0,
+      documentIds: Array.isArray(body.documentIds) ? body.documentIds : void 0,
+      includeArchivedInsights: body.includeArchivedInsights === true,
+      authToken: typeof body.authToken === "string" ? body.authToken : void 0,
+      dateFrom: typeof body.dateFrom === "string" ? body.dateFrom : void 0,
+      dateTo: typeof body.dateTo === "string" ? body.dateTo : void 0,
+      ...wantsSynthesis ? {
+        synthesize: {
+          ...responseSchema ? { responseSchema } : {}
+        }
+      } : {}
+    };
+    const result = await search.search(input);
+    return c.json(result);
+  });
+  app.post("/v1/consolidate:apply", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const userId = typeof body.userId === "string" ? body.userId : null;
+    const query = typeof body.query === "string" ? body.query : "";
+    const ownerScope = body.ownerScope ?? {};
+    if (!userId || !query) {
+      return c.json({ error: "userId and query are required" }, 400);
+    }
+    if (typeof ownerScope.userId !== "string") {
+      return c.json({ error: "ownerScope.userId is required" }, 400);
+    }
+    const input = {
+      userId,
+      query,
+      ownerScope: { userId: ownerScope.userId },
+      botIds: Array.isArray(body.botIds) ? body.botIds : void 0,
+      dateFrom: typeof body.dateFrom === "string" ? body.dateFrom : void 0,
+      dateTo: typeof body.dateTo === "string" ? body.dateTo : void 0,
+      tiers: Array.isArray(body.tiers) ? body.tiers : void 0,
+      limit: typeof body.limit === "number" ? body.limit : void 0,
+      threshold: typeof body.threshold === "number" ? body.threshold : void 0,
+      dryRun: body.dryRun === true,
+      expectedVersion: typeof body.expectedVersion === "string" ? body.expectedVersion : void 0,
+      authToken: typeof body.authToken === "string" ? body.authToken : void 0,
+      llmPlanReview: body.llmPlanReview && typeof body.llmPlanReview === "object" ? {
+        maxTokens: typeof body.llmPlanReview.maxTokens === "number" ? body.llmPlanReview.maxTokens : void 0
+      } : void 0
+    };
+    const result = await applyReflectedPlan(
+      { ...options.unified ?? {} },
+      { graphStore: options.graphStore, storage: options.storage },
+      input);
     return c.json(result);
   });
   app.post("/v1/raw-messages", async (c) => {
@@ -1135,12 +1945,98 @@ async function startHttpServer(options = {}) {
     if (!row) return c.json({ error: "not found" }, 404);
     return c.json({ message: row });
   });
+  app.post("/v1/vsa/store", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const userId = typeof body.userId === "string" ? body.userId : null;
+    const roleLabel = typeof body.roleLabel === "string" ? body.roleLabel : null;
+    const fillerLabel = typeof body.fillerLabel === "string" ? body.fillerLabel : null;
+    if (!userId || !roleLabel || !fillerLabel) {
+      return c.json({ error: "userId, roleLabel, and fillerLabel are required" }, 400);
+    }
+    if (!Array.isArray(body.roleVector) || !Array.isArray(body.fillerVector)) {
+      return c.json({ error: "roleVector[] and fillerVector[] are required" }, 400);
+    }
+    try {
+      const result = await vsa.storeFact({
+        userId,
+        roleLabel,
+        fillerLabel,
+        roleVector: body.roleVector,
+        fillerVector: body.fillerVector,
+        scopeTag: typeof body.scopeTag === "string" ? body.scopeTag : void 0,
+        botId: typeof body.botId === "string" ? body.botId : void 0,
+        factId: typeof body.factId === "string" ? body.factId : void 0
+      });
+      return c.json(result);
+    } catch (error) {
+      return c.json({ error: error.message ?? "vsa.store failed" }, 400);
+    }
+  });
+  app.post("/v1/vsa/recall", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const userId = typeof body.userId === "string" ? body.userId : null;
+    const roleLabel = typeof body.roleLabel === "string" ? body.roleLabel : null;
+    const roleVector = Array.isArray(body.roleVector) ? body.roleVector : null;
+    const vocabulary = Array.isArray(body.vocabulary) ? body.vocabulary : null;
+    if (!userId || !roleLabel || !roleVector || !vocabulary) {
+      return c.json({ error: "userId, roleLabel, roleVector[], and vocabulary[] are required" }, 400);
+    }
+    try {
+      const result = await vsa.recall({
+        userId,
+        roleLabel,
+        roleVector,
+        vocabulary,
+        scopeTag: typeof body.scopeTag === "string" ? body.scopeTag : void 0,
+        botId: typeof body.botId === "string" ? body.botId : void 0,
+        maxFacts: typeof body.maxFacts === "number" ? body.maxFacts : void 0
+      });
+      return c.json(result);
+    } catch (error) {
+      return c.json({ error: error.message ?? "vsa.recall failed" }, 400);
+    }
+  });
+  app.post("/v1/vsa/list", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const userId = typeof body.userId === "string" ? body.userId : null;
+    if (!userId) return c.json({ error: "userId is required" }, 400);
+    try {
+      const facts = await vsa.listFacts({
+        userId,
+        scopeTag: typeof body.scopeTag === "string" ? body.scopeTag : void 0,
+        botId: typeof body.botId === "string" ? body.botId : void 0,
+        includeDeprecated: body.includeDeprecated === true
+      });
+      return c.json({ facts });
+    } catch (error) {
+      return c.json({ error: error.message ?? "vsa.list failed" }, 400);
+    }
+  });
+  app.post("/v1/vsa/forget", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const userId = typeof body.userId === "string" ? body.userId : null;
+    const factIds = Array.isArray(body.factIds) ? body.factIds : null;
+    if (!userId || !factIds) {
+      return c.json({ error: "userId and factIds[] are required" }, 400);
+    }
+    try {
+      const result = await vsa.forget({
+        userId,
+        factIds,
+        reason: typeof body.reason === "string" ? body.reason : void 0
+      });
+      return c.json(result);
+    } catch (error) {
+      return c.json({ error: error.message ?? "vsa.forget failed" }, 400);
+    }
+  });
   const server = serve({ fetch: app.fetch, port, hostname: host });
   return {
     url: `http://${host}:${port}`,
     port,
     async stop() {
       await rawStore.close();
+      await closeSQLiteVsaStore();
       server.close();
     }
   };