@melandlabs/memory-store 0.2.7 → 0.3.1

package/dist/index.js

@@ -1,8 +1,8 @@
 import '@melandlabs/ai/memory';
 import { ChromaVectorStore } from '@melandlabs/rag';
 import { mkdirSync } from 'fs';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
+import { dirname } from 'path';
+import { getOpenContextPath } from '@melandlabs/env-config';
 import { SQLiteRawMessageManager } from '@melandlabs/sqlite';
 
 var __defProp = Object.defineProperty;
@@ -117,7 +117,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;
@@ -151,12 +151,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");
   }
 });
 
@@ -170,7 +169,7 @@ __export(raw_message_store_exports, {
   getRawMessageStorageBackend: () => getRawMessageStorageBackend,
   isRawMessageStorageAvailable: () => isRawMessageStorageAvailable
 });
-function resolveBackend(env) {
+function resolveBackend(_env) {
   const explicit = process.env.OPENCONTEXT_MEMORY_STORE_BACKEND?.trim().toLowerCase();
   if (explicit === "postgres") return "postgres";
   return "sqlite";
@@ -303,6 +302,12 @@ function mergeUnifiedMemorySearchResults(results, limit, options = {}) {
 function normalizeUnifiedMemoryMergeStrategy(value) {
   return value === "rrf" ? "rrf" : "similarity";
 }
+function normalizeUnifiedMemoryReasoningStrategy(value, defaultStrategy = "none") {
+  if (value === "rewrite" || value === "iterative") {
+    return value;
+  }
+  return defaultStrategy;
+}
 var DEFAULT_RRF_K = 60;
 function mergeUnifiedMemorySearchResultsRrf(lists, limit, k = DEFAULT_RRF_K) {
   if (!Array.isArray(lists) || lists.length === 0) {
@@ -325,7 +330,13 @@ function mergeUnifiedMemorySearchResultsRrf(lists, limit, k = DEFAULT_RRF_K) {
       }
     }
   }
-  const ranked = order.map((key) => scores.get(key)).sort((a, b) => {
+  const ranked = order.map((key) => {
+    const entry = scores.get(key);
+    if (!entry) {
+      throw new Error(`Invariant violation: missing RRF score for key "${key}"`);
+    }
+    return entry;
+  }).sort((a, b) => {
     if (b.rrf !== a.rrf) {
       return b.rrf - a.rrf;
     }
@@ -370,14 +381,222 @@ function isRawMemorySemanticResult(result) {
 function deriveLexicalKeywords(query) {
   return query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((token) => token.length >= 2).slice(0, 16);
 }
+function parseDateBoundary(value, role) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  const dateOnlyMatch = trimmed.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (dateOnlyMatch) {
+    const year = Number.parseInt(dateOnlyMatch[1], 10);
+    const month = Number.parseInt(dateOnlyMatch[2], 10) - 1;
+    const day = Number.parseInt(dateOnlyMatch[3], 10);
+    if (role === "from") {
+      return Date.UTC(year, month, day);
+    }
+    return Date.UTC(year, month, day + 1) - 1;
+  }
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) {
+    return void 0;
+  }
+  return parsed;
+}
+function getCandidateTimestamp(metadata) {
+  for (const key of ["timestamp", "createdAt", "time"]) {
+    const value = metadata[key];
+    if (typeof value === "number") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const parsed = Date.parse(value);
+      if (!Number.isNaN(parsed)) {
+        return parsed;
+      }
+    }
+  }
+  return void 0;
+}
+function filterByDateRange(items, dateFrom, dateTo) {
+  if (!dateFrom && !dateTo) {
+    return items;
+  }
+  const fromMs = dateFrom ? parseDateBoundary(dateFrom, "from") : void 0;
+  const toMs = dateTo ? parseDateBoundary(dateTo, "to") : void 0;
+  if (fromMs === void 0 && toMs === void 0) {
+    return items;
+  }
+  return items.filter((item) => {
+    const ts = getCandidateTimestamp(item.metadata);
+    if (ts === void 0) {
+      return true;
+    }
+    if (fromMs !== void 0 && ts < fromMs) {
+      return false;
+    }
+    if (toMs !== void 0 && ts > toMs) {
+      return false;
+    }
+    return true;
+  });
+}
+async function embedQueryVariant(embedQuery, input, query) {
+  return embedQuery({
+    userId: input.userId,
+    query,
+    authToken: input.authToken
+  });
+}
+async function runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger) {
+  const filters = input.botIds && input.botIds.length > 0 ? input.botIds.map((botId) => ({ botId })) : [{}];
+  let semantic = [];
+  if (isRawMessageChromaEnabled()) {
+    try {
+      semantic = (await Promise.all(
+        filters.map((filter) => {
+          const botId = "botId" in filter ? filter.botId : void 0;
+          return searchRawMessagesWithChroma({
+            userId: input.userId,
+            queryEmbedding,
+            limit,
+            threshold,
+            botId
+          });
+        })
+      )).flat().map(toMemoryResult);
+      logger.log?.("[memory-store] Raw message semantic search completed", {
+        backend: "chroma",
+        dimensions: queryEmbedding.length,
+        count: semantic.length
+      });
+    } catch (error) {
+      logger.warn?.(
+        "[memory-store] Chroma raw message search failed; falling back to database search:",
+        error
+      );
+    }
+  } else if (typeof deps.searchRawMessagesAnn === "function") {
+    const searchRawMessagesAnn = deps.searchRawMessagesAnn;
+    semantic = (await Promise.all(
+      filters.map(
+        (filter) => searchRawMessagesAnn({
+          userId: input.userId,
+          queryEmbedding,
+          limit,
+          threshold,
+          botId: "botId" in filter ? filter.botId : void 0
+        })
+      )
+    )).flat().filter(isRawMemorySemanticResult).map(toMemoryResult);
+  }
+  if (semantic.length === 0) {
+    try {
+      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 results = await manager2.searchMessagesSemantically({
+          userId: input.userId,
+          queryEmbedding,
+          limit,
+          threshold
+        });
+        semantic = results.map((r) => ({
+          type: "memory",
+          id: r.id,
+          content: r.content,
+          similarity: r.similarity,
+          metadata: r.metadata ?? {}
+        }));
+      }
+    } catch (error) {
+      logger.warn?.("[memory-store] SQLite semantic search failed:", error);
+    }
+  }
+  return semantic;
+}
+function mergeByMaxScore(lists) {
+  const best = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (const hit of list) {
+      const existing = best.get(hit.id);
+      if (!existing || hit.similarity > existing.similarity) {
+        best.set(hit.id, hit);
+      }
+    }
+  }
+  return Array.from(best.values()).sort((a, b) => b.similarity - a.similarity);
+}
+function toIterativeRecallCandidate(hit) {
+  return {
+    id: hit.id,
+    content: hit.content,
+    similarity: hit.similarity,
+    metadata: hit.metadata
+  };
+}
+async function runLexicalSearchForKeywords(deps, input, keywords, limit, logger) {
+  if (keywords.length === 0) {
+    return [];
+  }
+  if (typeof deps.searchRawMessagesLexical === "function") {
+    try {
+      const filters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
+      const searchRawMessagesLexical = deps.searchRawMessagesLexical;
+      return (await Promise.all(
+        filters.map(
+          (botId) => searchRawMessagesLexical({
+            userId: input.userId,
+            keywords,
+            limit: Math.ceil(limit / filters.length),
+            botId
+          })
+        )
+      )).flat().filter(isRawMemorySemanticResult).map((hit) => ({
+        ...toMemoryResult(hit),
+        metadata: { ...hit.metadata, scoring: "bm25" }
+      }));
+    } catch (error) {
+      logger.warn?.("[memory-store] lexical memory search failed:", error);
+    }
+  }
+  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];
+    return (await Promise.all(
+      filters.map(
+        (botId) => lexicalSearchRawMessages2({
+          userId: input.userId,
+          keywords,
+          limit: Math.ceil(limit / filters.length),
+          botId
+        })
+      )
+    )).flat().filter(Boolean).map(
+      (r) => toMemoryResult(
+        r
+      )
+    );
+  } catch (error) {
+    logger.warn?.("[memory-store] SQLite lexical search failed:", error);
+  }
+  return [];
+}
 function createUnifiedSearch(deps = {}) {
   const logger = deps.logger ?? console;
+  function resolveReasoningStrategy(input) {
+    const requested = normalizeUnifiedMemoryReasoningStrategy(input.reasoningStrategy);
+    if (requested !== "none") {
+      return requested;
+    }
+    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 {
@@ -389,10 +608,21 @@ function createUnifiedSearch(deps = {}) {
       };
     }
     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);
+          memorySubs = await runMemorySource(
+            input,
+            limit,
+            threshold,
+            warnings,
+            reasoningStrategy,
+            reasoningInfo
+          );
         } catch (error) {
           logger.warn?.("[memory-store] memory source failed:", error);
           warnings.push({
@@ -471,121 +701,155 @@ function createUnifiedSearch(deps = {}) {
       limit,
       strategy: mergeStrategy
     });
-    return {
+    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) {
+  async function runMemorySource(input, limit, threshold, warnings, reasoningStrategy = "none", reasoningInfo) {
+    if (reasoningStrategy === "iterative" && !deps.reasoning?.iterativePlanner) {
+      warnings.push({
+        source: "memory",
+        code: "memory_iterative_planner_not_configured",
+        message: "Iterative reasoning requested but no iterativePlanner is configured; falling back to default search."
+      });
+      if (reasoningInfo) reasoningInfo.degraded = true;
+    }
+    if (reasoningStrategy === "rewrite" && !deps.reasoning?.queryRewriter) {
+      warnings.push({
+        source: "memory",
+        code: "memory_query_rewrite_not_configured",
+        message: "Rewrite reasoning requested but no queryRewriter is configured; falling back to default search."
+      });
+      if (reasoningInfo) reasoningInfo.degraded = true;
+    }
+    if (reasoningStrategy === "iterative" && deps.reasoning?.iterativePlanner) {
+      const planner = deps.reasoning.iterativePlanner;
+      const result = await planner.plan({
+        query: input.query,
+        dateFrom: input.dateFrom,
+        dateTo: input.dateTo,
+        executor: {
+          search: async (request) => {
+            const keywords2 = request.keywords.length > 0 ? request.keywords : deriveLexicalKeywords(input.query);
+            const lexicalHits = await runLexicalSearchForKeywords(deps, input, keywords2, limit, logger);
+            let semanticHits = [];
+            if (typeof deps.embedQuery === "function") {
+              try {
+                const semanticQuery = keywords2.join(" ");
+                const queryEmbedding = await embedQueryVariant(deps.embedQuery, input, semanticQuery);
+                semanticHits = await runSemanticSearchForEmbedding(
+                  deps,
+                  input,
+                  queryEmbedding,
+                  limit,
+                  threshold,
+                  logger
+                );
+              } catch (error) {
+                logger.warn?.(
+                  "[memory-store] Iterative semantic search failed; using lexical results only:",
+                  error
+                );
+              }
+            }
+            const candidates = filterByDateRange(
+              mergeByMaxScore([
+                lexicalHits.map(toIterativeRecallCandidate),
+                semanticHits.map(toIterativeRecallCandidate)
+              ]),
+              request.dateFrom,
+              request.dateTo
+            );
+            return { candidates };
+          }
+        }
+      });
+      if (reasoningInfo) {
+        reasoningInfo.iterations = result.stats.iterations;
+        reasoningInfo.evidenceCount = result.evidence.length;
+        if (planner.lastDegraded?.()) {
+          reasoningInfo.degraded = true;
+        }
+      }
+      const semantic2 = result.evidence.map((candidate) => ({
+        type: "memory",
+        id: candidate.id,
+        content: candidate.content,
+        similarity: candidate.similarity,
+        metadata: { ...candidate.metadata, reasoning: "iterative" }
+      }));
+      return { semantic: semantic2, lexical: [] };
+    }
     if (typeof deps.embedQuery !== "function") {
       warnings.push({
         source: "memory",
         code: "memory_lexical_search_fallback",
         message: "Semantic search not configured, using keyword search as fallback"
       });
-      const { lexicalSearchRawMessages: lexicalSearchRawMessages2 } = await Promise.resolve().then(() => (init_sqlite_raw_message_store(), sqlite_raw_message_store_exports));
-      const keywords = deriveLexicalKeywords(input.query);
-      let lexical2 = [];
-      if (keywords.length > 0) {
-        try {
-          const filters2 = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
-          const results = await Promise.all(
-            filters2.map(
-              (botId) => lexicalSearchRawMessages2({
-                userId: input.userId,
-                keywords,
-                limit: Math.ceil(limit / filters2.length),
-                botId
-              })
-            )
-          );
-          lexical2 = results.flat().filter(Boolean).map(toMemoryResult);
-        } catch (error) {
-          logger.warn?.("[memory-store] Default lexical search failed:", error);
-        }
-      }
+      const keywords2 = deriveLexicalKeywords(input.query);
+      const lexical2 = filterByDateRange(
+        await runLexicalSearchForKeywords(deps, input, keywords2, limit, logger),
+        input.dateFrom,
+        input.dateTo
+      );
       return { semantic: [], lexical: lexical2 };
     }
-    const queryEmbedding = await deps.embedQuery({
-      userId: input.userId,
-      query: input.query,
-      authToken: input.authToken
-    });
-    const filters = input.botIds && input.botIds.length > 0 ? input.botIds.map((botId) => ({ botId })) : [{}];
     let semantic = [];
-    if (isRawMessageChromaEnabled()) {
+    const embedQuery = deps.embedQuery;
+    if (reasoningStrategy === "rewrite" && deps.reasoning?.queryRewriter) {
       try {
-        semantic = (await Promise.all(
-          filters.map((filter) => {
-            const botId = "botId" in filter ? filter.botId : void 0;
-            return searchRawMessagesWithChroma({
-              userId: input.userId,
-              queryEmbedding,
-              limit,
-              threshold,
-              botId
-            });
-          })
-        )).flat().map(toMemoryResult);
-        logger.log?.("[memory-store] Raw message semantic search completed", {
-          backend: "chroma",
-          dimensions: queryEmbedding.length,
-          count: semantic.length
+        const variants = await deps.reasoning.queryRewriter.rewrite({
+          query: input.query,
+          userId: input.userId,
+          authToken: input.authToken
         });
-      } catch (error) {
-        logger.warn?.(
-          "[memory-store] Chroma raw message search failed; falling back to database search:",
-          error
+        if (reasoningInfo) {
+          reasoningInfo.rewrittenQueries = variants;
+          if (deps.reasoning.queryRewriter.lastDegraded?.()) {
+            reasoningInfo.degraded = true;
+          }
+        }
+        const embeddings = await Promise.all(
+          variants.map((variant) => embedQueryVariant(embedQuery, input, variant))
+        );
+        const lists = await Promise.all(
+          embeddings.map(
+            (embedding) => runSemanticSearchForEmbedding(deps, input, embedding, limit, threshold, logger)
+          )
         );
+        semantic = mergeByMaxScore(lists);
+      } catch (error) {
+        logger.warn?.("[memory-store] Query rewriting failed; falling back to original query:", error);
+        warnings.push({
+          source: "memory",
+          code: "memory_query_rewrite_failed",
+          message: `Query rewriting failed: ${error.message ?? "Unknown error"}. Using original query.`
+        });
+        if (reasoningInfo) reasoningInfo.degraded = true;
       }
-    } else if (typeof deps.searchRawMessagesAnn === "function") {
-      semantic = (await Promise.all(
-        filters.map(
-          (filter) => deps.searchRawMessagesAnn({
-            userId: input.userId,
-            queryEmbedding,
-            limit,
-            threshold,
-            botId: "botId" in filter ? filter.botId : void 0
-          })
-        )
-      )).flat().filter(isRawMemorySemanticResult).map(toMemoryResult);
     }
     if (semantic.length === 0) {
-      try {
-        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 results = await manager2.searchMessagesSemantically({
-            userId: input.userId,
-            queryEmbedding,
-            limit,
-            threshold
-          });
-          semantic = results.map((r) => ({
-            type: "memory",
-            id: r.id,
-            content: r.content,
-            similarity: r.similarity,
-            metadata: r.metadata ?? {}
-          }));
-        }
-      } catch (error) {
-        logger.warn?.("[memory-store] SQLite semantic search failed:", error);
-      }
+      const queryEmbedding = await embedQueryVariant(embedQuery, input, input.query);
+      semantic = await runSemanticSearchForEmbedding(deps, input, queryEmbedding, limit, threshold, logger);
     }
     let lexical = [];
-    if (typeof deps.searchRawMessagesLexical === "function") {
-      const keywords = deriveLexicalKeywords(input.query);
-      if (keywords.length > 0) {
+    const keywords = deriveLexicalKeywords(input.query);
+    if (keywords.length > 0) {
+      if (typeof deps.searchRawMessagesLexical === "function") {
         try {
           const lexFilters = input.botIds && input.botIds.length > 0 ? input.botIds : [void 0];
+          const searchRawMessagesLexical = deps.searchRawMessagesLexical;
           lexical = (await Promise.all(
             lexFilters.map(
-              (botId) => deps.searchRawMessagesLexical({
+              (botId) => searchRawMessagesLexical({
                 userId: input.userId,
                 keywords,
                 limit,
@@ -604,20 +868,24 @@ function createUnifiedSearch(deps = {}) {
             message: error.message ?? "memory_lexical_search_failed"
           });
         }
+      } else if (input.mergeStrategy === "rrf") {
+        warnings.push({
+          source: "memory",
+          code: "memory_lexical_search_not_configured",
+          message: "RRF merge requested but lexical search is not configured; falling back to semantic-only RRF."
+        });
       }
-    } else if (input.mergeStrategy === "rrf") {
-      warnings.push({
-        source: "memory",
-        code: "memory_lexical_search_not_configured",
-        message: "RRF merge requested but lexical search is not configured; falling back to semantic-only RRF."
-      });
     }
-    return { semantic, lexical };
+    return {
+      semantic: filterByDateRange(semantic, input.dateFrom, input.dateTo),
+      lexical: filterByDateRange(lexical, input.dateFrom, input.dateTo)
+    };
   }
   async function searchRawMemorySemantically(input) {
     const limit = clampUnifiedMemorySearchLimit(input.limit);
     const threshold = clampUnifiedMemorySearchThreshold(input.threshold);
-    const sub = await runMemorySource(input, limit, threshold, []);
+    const reasoningStrategy = resolveReasoningStrategy(input);
+    const sub = await runMemorySource(input, limit, threshold, [], reasoningStrategy);
     return mergeAcrossSources({
       memorySubs: sub,
       insightHits: [],
@@ -662,6 +930,362 @@ function mergeAcrossSources(input) {
 init_raw_message_store();
 init_raw_message_store();
 init_postgres_raw_message_factory();
+
+// src/search/query-rewriter.ts
+var SYSTEM_PROMPT = `You are a memory retrieval assistant.
+
+The memory store contains a user's past messages, written in the first person (e.g. "I told you about my sister's wedding", "I prefer dark mode").
+
+Your job is NOT to answer the question. Your job is to rewrite the assistant's question into a short, natural question that the USER would ask their own memory log to find the relevant entry.
+
+Rules:
+- Use first person: "Did I tell you about ...?", "What did I say about ...?", "Have I mentioned ...?"
+- Do NOT address the user as "you".
+- Do NOT answer the question.
+- Output each rephrasing on its own line, prefixed with "- ".
+- Keep each rephrasing under 20 words.
+- Output exactly the requested number of lines.`;
+function buildPrompt(query, numVariants) {
+  const label = numVariants === 1 ? "1 alternative rephrasing" : `${numVariants} alternative rephrasings`;
+  return `${SYSTEM_PROMPT}
+
+Output exactly ${label}.
+
+Example:
+Question: What is the name of my cat?
+- Did I tell you the name of my cat?
+
+Question: ${query}
+Output:`;
+}
+function sanitizeLine(text) {
+  return text.replace(/^\s*["'`]+|["'`]+\s*$/g, "").replace(/^Rewritten:\s*/i, "").trim();
+}
+function parseVariants(raw, maxVariants, original) {
+  const lines = raw.split(/\r?\n/).map((line) => sanitizeLine(line.replace(/^\s*-\s+/, ""))).filter((line) => line.length > 0);
+  if (lines.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set([original.toLowerCase()]);
+  const variants = [];
+  for (const line of lines) {
+    if (variants.length >= maxVariants) break;
+    const key = line.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    variants.push(line);
+  }
+  return variants;
+}
+function createUserVoiceRewriter(options) {
+  const { complete, maxVariants = 1, disabled = false } = options;
+  const wantedVariants = Math.max(0, Math.floor(maxVariants));
+  let lastDegraded = false;
+  return {
+    async rewrite(input) {
+      if (disabled || !input.query || !input.query.trim()) {
+        lastDegraded = false;
+        return [input.query];
+      }
+      const original = input.query.trim();
+      if (wantedVariants === 0) {
+        lastDegraded = false;
+        return [original];
+      }
+      try {
+        const raw = await complete(buildPrompt(original, wantedVariants));
+        const variants = parseVariants(raw, wantedVariants, original);
+        if (variants.length === 0) {
+          lastDegraded = true;
+          return [original];
+        }
+        lastDegraded = false;
+        return [original, ...variants];
+      } catch {
+        lastDegraded = true;
+        return [original];
+      }
+    },
+    lastDegraded() {
+      return lastDegraded;
+    }
+  };
+}
+function createIdentityRewriter() {
+  return {
+    async rewrite(input) {
+      return [input.query];
+    }
+  };
+}
+
+// src/search/iterative-recall.ts
+var SYSTEM_PROMPT2 = `You are a research assistant collecting evidence from a user's conversation history. You are NOT answering the question; only gather the most useful memory.
+
+Actions:
+search \u2014 search by concise keywords. Previously returned chunks are automatically excluded.
+Action Input: {"keywords":["keyword1","keyword2"],"date_from":"YYYY-MM-DD","date_to":"YYYY-MM-DD"}
+The date fields are optional; omit them unless an absolute date range is useful.
+
+note \u2014 save relevant results from the LAST search by their 1-based result number.
+Action Input: {"indices":[1,3]}
+
+finish \u2014 finish collecting evidence.
+Action Input: {}
+
+Workflow: search -> note -> search again -> note -> finish.
+Review every result. Call note before another search because the prior result list is replaced. Use diverse keywords on later searches. Never answer the question.
+
+Output exactly:
+Thought: one short sentence
+Action: one action name
+Action Input: valid JSON object`;
+function deriveKeywordsFromQuery(query) {
+  return query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((token) => token.length >= 2);
+}
+function formatDateHint(dateFrom, dateTo) {
+  if (!dateFrom && !dateTo) {
+    return void 0;
+  }
+  const fromText = dateFrom ?? "the beginning";
+  const toText = dateTo ?? "now";
+  return `Restrict searches to the date range ${fromText} to ${toText}. You may still emit narrower date_from/date_to bounds when useful.`;
+}
+function buildInitialPrompt(query, dateHint) {
+  const hintText = dateHint ? `
+${dateHint}` : "";
+  return `${SYSTEM_PROMPT2}
+
+Question to research: ${query}${hintText}
+Search the conversation history and collect all relevant evidence. Start with a broad keyword search.`;
+}
+function buildObservationPrompt(hits) {
+  if (hits.length === 0) {
+    return "Observation: No matching memory found.\nRespond with the next action only.";
+  }
+  const blocks = hits.map((hit, index) => {
+    const lines = [`Result ${index + 1} | score=${hit.similarity.toFixed(4)}`];
+    for (const line of hit.content.split("\n")) {
+      if (line.trim()) lines.push(line);
+    }
+    return lines.join("\n");
+  });
+  return `Observation:
+${blocks.join("\n\n")}
+
+Respond with the next action only.`;
+}
+function stripCodeFences(text) {
+  return text.replace(/```(?:json)?\s*([\s\S]*?)\s*```/g, "$1");
+}
+function extractJsonObject(text) {
+  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 parseAction(text) {
+  const cleaned = stripCodeFences(text);
+  const actionMatch = cleaned.match(/Action:\s*([\w_]+)/);
+  if (!actionMatch) return null;
+  const action = actionMatch[1].trim().toLowerCase();
+  if (action === "finish") {
+    return { type: "finish" };
+  }
+  const inputMatch = cleaned.match(/Action Input:\s*/s);
+  if (!inputMatch || inputMatch.index === void 0) return null;
+  const jsonText = extractJsonObject(cleaned.slice(inputMatch.index + inputMatch[0].length));
+  if (!jsonText) return null;
+  let parsedJson = null;
+  for (const candidate of [jsonText, jsonText.replace(/'/g, '"')]) {
+    try {
+      parsedJson = JSON.parse(candidate);
+      break;
+    } catch {
+    }
+  }
+  if (!parsedJson) return null;
+  if (action === "search") {
+    const keywords = parsedJson.keywords;
+    if (!Array.isArray(keywords) || !keywords.every((k) => typeof k === "string")) {
+      return null;
+    }
+    return {
+      type: "search",
+      keywords,
+      dateFrom: typeof parsedJson.date_from === "string" ? parsedJson.date_from : void 0,
+      dateTo: typeof parsedJson.date_to === "string" ? parsedJson.date_to : void 0
+    };
+  }
+  if (action === "note") {
+    const indices = parsedJson.indices;
+    if (!Array.isArray(indices) || !indices.every((i) => typeof i === "number")) {
+      return null;
+    }
+    return { type: "note", indices };
+  }
+  return null;
+}
+function createIterativeRecallPlanner(deps) {
+  const { complete, options = {} } = deps;
+  const defaults = {
+    maxIterations: 4,
+    searchTopK: 5,
+    disabled: false,
+    fallbackToBaseline: true
+  };
+  let lastDegraded = false;
+  let iterationsWithValidAction = 0;
+  return {
+    lastDegraded: () => lastDegraded,
+    async plan(input) {
+      const opts = {
+        ...defaults,
+        ...options,
+        ...input.options
+      };
+      lastDegraded = false;
+      iterationsWithValidAction = 0;
+      if (opts.disabled || !input.query.trim()) {
+        return { evidence: [], stats: { iterations: 0, searches: 0, notes: 0 } };
+      }
+      const messages = [
+        { role: "system", content: SYSTEM_PROMPT2 },
+        {
+          role: "user",
+          content: buildInitialPrompt(input.query, formatDateHint(input.dateFrom, input.dateTo))
+        }
+      ];
+      const evidence = /* @__PURE__ */ new Map();
+      const excludedIds = /* @__PURE__ */ new Set();
+      let lastHits = [];
+      let searches = 0;
+      let notes = 0;
+      let iterations = 0;
+      let completeThrew = false;
+      for (let i = 0; i < opts.maxIterations; i += 1) {
+        iterations = i + 1;
+        let reply;
+        try {
+          reply = await complete(messages.map((m) => `${m.role}: ${m.content}`).join("\n\n"));
+        } catch {
+          completeThrew = true;
+          break;
+        }
+        messages.push({ role: "assistant", content: reply });
+        const action = parseAction(reply);
+        if (!action) {
+          messages.push({
+            role: "user",
+            content: "Observation: Use exactly one valid action: search, note, or finish. Respond with the next action only."
+          });
+          continue;
+        }
+        iterationsWithValidAction += 1;
+        if (action.type === "finish") {
+          break;
+        }
+        if (action.type === "search") {
+          const result = await input.executor.search({
+            keywords: action.keywords,
+            dateFrom: action.dateFrom ?? input.dateFrom,
+            dateTo: action.dateTo ?? input.dateTo
+          });
+          lastHits = result.candidates.filter((c) => !excludedIds.has(c.id)).slice(0, opts.searchTopK);
+          for (const hit of lastHits) {
+            excludedIds.add(hit.id);
+          }
+          searches += 1;
+          messages.push({ role: "user", content: buildObservationPrompt(lastHits) });
+          continue;
+        }
+        if (action.type === "note") {
+          let saved = 0;
+          for (const index of action.indices) {
+            if (index >= 1 && index <= lastHits.length) {
+              const hit = lastHits[index - 1];
+              if (!evidence.has(hit.id)) {
+                evidence.set(hit.id, hit);
+                saved += 1;
+              }
+            }
+          }
+          notes += saved;
+          messages.push({
+            role: "user",
+            content: `Observation: Saved ${saved} new result(s). Total notes: ${evidence.size}.
+Respond with the next action only.`
+          });
+        }
+      }
+      let fallbackRan = false;
+      if (evidence.size === 0 && opts.fallbackToBaseline) {
+        fallbackRan = true;
+        if (lastHits.length > 0) {
+          for (const hit of lastHits) {
+            if (!evidence.has(hit.id)) {
+              evidence.set(hit.id, hit);
+            }
+          }
+        } else {
+          const baseline = await input.executor.search({
+            keywords: deriveKeywordsFromQuery(input.query),
+            dateFrom: input.dateFrom,
+            dateTo: input.dateTo
+          });
+          searches += 1;
+          for (const hit of baseline.candidates.slice(0, opts.searchTopK)) {
+            if (!evidence.has(hit.id)) {
+              evidence.set(hit.id, hit);
+            }
+          }
+        }
+      }
+      lastDegraded = completeThrew || iterationsWithValidAction === 0 || fallbackRan;
+      return {
+        evidence: Array.from(evidence.values()),
+        stats: { iterations, searches, notes }
+      };
+    }
+  };
+}
+function createIdentityIterativePlanner() {
+  return {
+    lastDegraded: () => false,
+    async plan() {
+      return { evidence: [], stats: { iterations: 0, searches: 0, notes: 0 } };
+    }
+  };
+}
+
+// src/index.ts
 async function createMemoryStore(config = {}) {
   const dbPath = config.dbPath ?? (config.db && "path" in config.db ? config.db.path : void 0);
   const raw = createRawMessageStore({ env: config.env, dbPath });
@@ -676,4 +1300,4 @@ async function createMemoryStore(config = {}) {
   };
 }
 
-export { clampUnifiedMemorySearchLimit, clampUnifiedMemorySearchThreshold, clearPostgresFactory, closeRawMessageStore, createMemoryStore, createRawMessageStore, createUnifiedSearch, getRawMessageManager, getRawMessageStorageBackend, hasPostgresFactory, isRawMemorySemanticResult, isRawMessageStorageAvailable, mergeUnifiedMemorySearchResults, normalizeUnifiedMemorySearchSources, registerPostgresFactory, resolvePostgresFactory, toKnowledgeResult, toMemoryResult };
+export { clampUnifiedMemorySearchLimit, clampUnifiedMemorySearchThreshold, clearPostgresFactory, closeRawMessageStore, createIdentityIterativePlanner, createIdentityRewriter, createIterativeRecallPlanner, createMemoryStore, createRawMessageStore, createUnifiedSearch, createUserVoiceRewriter, getRawMessageManager, getRawMessageStorageBackend, hasPostgresFactory, isRawMemorySemanticResult, isRawMessageStorageAvailable, mergeUnifiedMemorySearchResults, normalizeUnifiedMemoryReasoningStrategy, normalizeUnifiedMemorySearchSources, registerPostgresFactory, resolvePostgresFactory, toKnowledgeResult, toMemoryResult };