memorix 1.2.4 → 1.2.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.5] - 2026-07-27
+
+### Added
+- **Explicit retrieval profiles** -- Search now accepts `fast`, `balanced` (default), or `thorough` through the CLI, MCP, and SDK. Fast is fully local, balanced keeps optional LLM work out of everyday retrieval, and thorough explicitly opts into configured LLM query refinement.
+- **Reproducible retrieval evidence** -- Added `npm run benchmark:retrieval` for a clearly-labelled hot in-process SDK lexical benchmark with p50/p95/p99 output. It does not present CLI startup, MCP transport, remote embedding, or LLM latency as the same metric.
+
+### Changed
+- **Lighter read-only CLI path** -- Memory search, detail, timeline, recent, graph context, and help no longer create session bookkeeping or maintenance-target metadata. Identity and visibility checks remain unchanged.
+
+### Fixed
+- **Completed searches no longer retain timeout watchdogs** -- Embedding, rerank, MCP search, and maintenance timeout paths share a helper that clears the timer when work settles. This removes the avoidable CLI exit delay caused by an already-completed optional rerank.
+- **OpenRouter lane isolation** -- An embedding-only `OPENROUTER_API_KEY` no longer silently enables the memory LLM lane. It remains valid for a memory LLM only when that lane explicitly selects an OpenRouter provider or base URL.
+
 ## [1.2.4] - 2026-07-26
 
 ### Added

package/dist/cli/index.js

@@ -3212,7 +3212,7 @@ ${import_picocolors.default.gray(m3)}  ${s2}
 
 // src/cli/version.ts
 function getCliVersion() {
-  return true ? "1.2.4" : pkg.version;
+  return true ? "1.2.5" : pkg.version;
 }
 var init_version = __esm({
   "src/cli/version.ts"() {
@@ -13763,6 +13763,25 @@ function getResolvedConfig(options2 = {}) {
   const legacy = loadFileConfig();
   const embeddingBaseUrl = first(process.env.MEMORIX_EMBEDDING_BASE_URL, toml.embedding?.base_url, yaml4.embedding?.baseUrl, legacy.embeddingApi?.baseUrl);
   const openRouterEmbeddingApiKey = isOpenRouterUrl(embeddingBaseUrl) ? process.env.OPENROUTER_API_KEY : void 0;
+  const memoryLlmProvider = first(
+    process.env.MEMORIX_LLM_PROVIDER,
+    toml.memory?.llm?.provider,
+    yaml4.llm?.provider,
+    legacy.llm?.provider
+  );
+  const memoryLlmModel = first(
+    process.env.MEMORIX_LLM_MODEL,
+    toml.memory?.llm?.model,
+    yaml4.llm?.model,
+    legacy.llm?.model
+  );
+  const memoryLlmBaseUrl = first(
+    process.env.MEMORIX_LLM_BASE_URL,
+    toml.memory?.llm?.base_url,
+    yaml4.llm?.baseUrl,
+    legacy.llm?.baseUrl
+  );
+  const openRouterMemoryLlmApiKey = isOpenRouterMemoryLane(memoryLlmProvider, memoryLlmBaseUrl) ? process.env.OPENROUTER_API_KEY : void 0;
   const resolved = {
     agent: {
       provider: first(
@@ -13800,9 +13819,9 @@ function getResolvedConfig(options2 = {}) {
       autoCleanup: firstBool(toml.memory?.auto_cleanup, yaml4.behavior?.autoCleanup),
       syncAdvisory: firstBool(toml.memory?.sync_advisory, yaml4.behavior?.syncAdvisory),
       llm: {
-        provider: first(process.env.MEMORIX_LLM_PROVIDER, toml.memory?.llm?.provider, yaml4.llm?.provider, legacy.llm?.provider),
-        model: first(process.env.MEMORIX_LLM_MODEL, toml.memory?.llm?.model, yaml4.llm?.model, legacy.llm?.model),
-        baseUrl: first(process.env.MEMORIX_LLM_BASE_URL, toml.memory?.llm?.base_url, yaml4.llm?.baseUrl, legacy.llm?.baseUrl),
+        provider: memoryLlmProvider,
+        model: memoryLlmModel,
+        baseUrl: memoryLlmBaseUrl,
         apiKey: first(
           process.env.MEMORIX_LLM_API_KEY,
           process.env.MEMORIX_API_KEY,
@@ -13811,7 +13830,7 @@ function getResolvedConfig(options2 = {}) {
           legacy.llm?.apiKey,
           process.env.OPENAI_API_KEY,
           process.env.ANTHROPIC_API_KEY,
-          process.env.OPENROUTER_API_KEY
+          openRouterMemoryLlmApiKey
         )
       }
     },
@@ -13948,6 +13967,9 @@ function isOpenRouterUrl(value) {
     return /(^|\.)openrouter\.ai(?::|\/|$)/i.test(value);
   }
 }
+function isOpenRouterMemoryLane(provider2, baseUrl) {
+  return provider2?.trim().toLowerCase() === "openrouter" || isOpenRouterUrl(baseUrl);
+}
 function normalizeExternalContext(value) {
   const normalized = value?.trim().toLowerCase();
   if (normalized === "auto" || normalized === "off") return normalized;
@@ -15995,6 +16017,29 @@ Rules:
   }
 });
 
+// src/timeout.ts
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve6, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve6(value);
+      },
+      (error2) => {
+        clearTimeout(timer);
+        reject(error2);
+      }
+    );
+  });
+}
+var init_timeout = __esm({
+  "src/timeout.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/project/aliases.ts
 var aliases_exports = {};
 __export(aliases_exports, {
@@ -19599,8 +19644,12 @@ async function searchObservations(options2) {
     }
   };
   const modeKey = options2.projectId ?? SEARCH_MODE_DEFAULT_KEY;
-  lastSearchModeByProject.set(modeKey, embeddingEnabled ? "hybrid" : "fulltext");
+  const quality = options2.quality ?? "balanced";
   const database = await getDb();
+  lastSearchModeByProject.set(
+    modeKey,
+    quality === "fast" ? "fulltext (fast profile)" : embeddingEnabled ? "hybrid" : "fulltext"
+  );
   let projectIds = null;
   if (options2.projectId) {
     try {
@@ -19622,11 +19671,15 @@ async function searchObservations(options2) {
   }
   const hasQuery = options2.query && options2.query.trim().length > 0;
   const originalQuery = options2.query;
-  const tier = hasQuery ? classifyQueryTier(originalQuery) : "fast";
+  const tier = quality === "fast" ? "fast" : hasQuery ? classifyQueryTier(originalQuery) : "fast";
   mark(`tier=${tier}`);
-  const expandedEmbeddingQuery = tier === "heavy" ? await maybeExpandSearchQuery(options2.query) : options2.query;
+  if (quality === "thorough" && hasQuery) {
+    const { initLLM: initLLM2, isLLMEnabled: isLLMEnabled2 } = await Promise.resolve().then(() => (init_provider2(), provider_exports2));
+    if (!isLLMEnabled2()) initLLM2();
+  }
+  const expandedEmbeddingQuery = quality === "thorough" && tier === "heavy" ? await maybeExpandSearchQuery(options2.query) : options2.query;
   mark("queryExpansion");
-  const intentResult = hasQuery ? detectQueryIntent(originalQuery) : null;
+  const intentResult = quality === "fast" || !hasQuery ? null : detectQueryIntent(originalQuery);
   const requestLimit = projectIds ? (options2.limit ?? 20) * 3 : options2.limit ?? 20;
   const defaultBoost = {
     title: 3,
@@ -19640,17 +19693,21 @@ async function searchObservations(options2) {
   let searchParams = {
     term: originalQuery,
     limit: requestLimit,
-    includeVectors: true,
+    // Fast search never uses vectors, so returning them only adds work and
+    // payload pressure to an explicitly latency-sensitive path.
+    includeVectors: quality !== "fast",
     ...Object.keys(filters).length > 0 ? { where: filters } : {},
     // Search specific fields (not tokens, accessCount, etc.)
     properties: ["title", "entityName", "narrative", "facts", "concepts", "filesModified"],
     // Field boosting: intent-aware or default
     boost: fieldBoost,
     // Fuzzy tolerance: allow 1-char typos for short queries, 2 for longer
-    ...hasQuery ? { tolerance: originalQuery.length > 6 ? 2 : 1 } : {}
+    // Fuzzy matching is useful for ordinary recall, but grows sharply with
+    // corpus size. The fast profile deliberately uses exact lexical matching.
+    ...hasQuery && quality !== "fast" ? { tolerance: originalQuery.length > 6 ? 2 : 1 } : {}
   };
   let queryVector = null;
-  if (embeddingEnabled && hasQuery && tier !== "fast") {
+  if (quality !== "fast" && embeddingEnabled && hasQuery && tier !== "fast") {
     try {
       const provider2 = await getEmbeddingProvider();
       if (provider2) {
@@ -19665,11 +19722,11 @@ async function searchObservations(options2) {
           );
         } else {
           const EMBEDDING_TIMEOUT_MS = 15e3;
-          const embedPromise = provider2.embed(expandedEmbeddingQuery);
-          const timeoutPromise = new Promise(
-            (_4, reject) => setTimeout(() => reject(new Error(`Embedding timeout after ${EMBEDDING_TIMEOUT_MS}ms`)), EMBEDDING_TIMEOUT_MS)
+          queryVector = await withTimeout(
+            provider2.embed(expandedEmbeddingQuery),
+            EMBEDDING_TIMEOUT_MS,
+            "Embedding"
           );
-          queryVector = await Promise.race([embedPromise, timeoutPromise]);
           mark("embedding");
           const cjkRatio = (originalQuery.match(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g) || []).length / originalQuery.length;
           const isCJKHeavy = cjkRatio > 0.3;
@@ -19910,7 +19967,7 @@ async function searchObservations(options2) {
       }
     }
   }
-  const shouldRerank = tier === "heavy" && hasQuery && intermediate.length > 2 && (() => {
+  const shouldRerank = quality === "thorough" && tier === "heavy" && hasQuery && intermediate.length > 2 && (() => {
     const top = intermediate[0]?.score ?? 0;
     const second2 = intermediate[1]?.score ?? 0;
     return top > 0 && second2 / top > 0.7;
@@ -19934,11 +19991,11 @@ async function searchObservations(options2) {
       }));
       const _parsedRerank = parseInt(process.env.MEMORIX_RERANK_TIMEOUT_MS || "", 10);
       const RERANK_TIMEOUT_MS = Number.isFinite(_parsedRerank) && _parsedRerank > 0 ? _parsedRerank : 5e3;
-      const rerankPromise = rerankResults2(originalQuery, candidates);
-      const timeoutPromise = new Promise(
-        (_4, reject) => setTimeout(() => reject(new Error(`LLM rerank timeout after ${RERANK_TIMEOUT_MS}ms`)), RERANK_TIMEOUT_MS)
+      const { reranked, usedLLM } = await withTimeout(
+        rerankResults2(originalQuery, candidates),
+        RERANK_TIMEOUT_MS,
+        "LLM rerank"
       );
-      const { reranked, usedLLM } = await Promise.race([rerankPromise, timeoutPromise]);
       mark(`rerank(usedLLM=${usedLLM})`);
       if (usedLLM) {
         lastSearchModeByProject.set(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + LLM rerank");
@@ -20131,6 +20188,7 @@ var init_orama_store = __esm({
     init_project_affinity();
     init_intent_detector();
     init_query_expansion();
+    init_timeout();
     db = null;
     dbInitPromise = null;
     dbGeneration = 0;
@@ -23491,7 +23549,7 @@ var init_session_store = __esm({
 });
 
 // src/cli/commands/operator-shared.ts
-async function getCliProjectContext(options2) {
+async function resolveCliProjectContext(options2) {
   const invocation = getCliInvocation();
   const detection = detectProjectWithDiagnostics(
     options2?.projectRoot ?? invocation.projectRoot ?? process.env.MEMORIX_PROJECT_ROOT ?? process.cwd()
@@ -23502,6 +23560,40 @@ async function getCliProjectContext(options2) {
   }
   const project = detection.project;
   const dataDir = await getProjectDataDir(project.id);
+  return { project, dataDir, invocation };
+}
+async function getCliReadContext(options2) {
+  const { project, dataDir, invocation } = await resolveCliProjectContext(options2);
+  await initObservations(dataDir);
+  if (options2?.searchIndex) {
+    await prepareSearchIndex();
+  }
+  const storedIdentity = await loadCliIdentity(dataDir, project.id);
+  if (!invocation.actorId && !storedIdentity) {
+    return {
+      project,
+      dataDir,
+      reader: { projectId: project.id },
+      identity: null
+    };
+  }
+  const teamStore = await initTeamStore(dataDir);
+  const identity = await resolveCliIdentity({
+    project,
+    dataDir,
+    teamStore,
+    explicitActorId: invocation.actorId
+  });
+  return {
+    project,
+    dataDir,
+    reader: identity.reader,
+    identity: identity.identity,
+    ...identity.warning ? { identityWarning: identity.warning } : {}
+  };
+}
+async function getCliProjectContext(options2) {
+  const { project, dataDir, invocation } = await resolveCliProjectContext(options2);
   try {
     const { MaintenanceTargetStore: MaintenanceTargetStore2 } = await Promise.resolve().then(() => (init_maintenance_targets(), maintenance_targets_exports));
     new MaintenanceTargetStore2(dataDir).register({
@@ -23583,6 +23675,13 @@ function coerceObservationStatus(input) {
   }
   return normalized;
 }
+function coerceRetrievalQuality(input) {
+  const normalized = (input ?? "balanced").trim().toLowerCase();
+  if (!RETRIEVAL_QUALITIES.includes(normalized)) {
+    throw new Error("quality must be fast, balanced, or thorough");
+  }
+  return normalized;
+}
 function coerceObservationVisibility(input) {
   const normalized = (input ?? "project").trim().toLowerCase();
   if (normalized === "personal" || normalized === "project" || normalized === "team") {
@@ -23613,7 +23712,7 @@ function resolveCliActorId(explicitValue, identity, field = "agentId") {
   }
   return explicit || identity?.agentId;
 }
-var OBSERVATION_TYPES, OBSERVATION_STATUSES;
+var OBSERVATION_TYPES, OBSERVATION_STATUSES, RETRIEVAL_QUALITIES;
 var init_operator_shared = __esm({
   "src/cli/commands/operator-shared.ts"() {
     "use strict";
@@ -23639,6 +23738,7 @@ var init_operator_shared = __esm({
       "probe"
     ];
     OBSERVATION_STATUSES = ["active", "resolved", "archived"];
+    RETRIEVAL_QUALITIES = ["fast", "balanced", "thorough"];
   }
 });
 
@@ -24063,6 +24163,7 @@ var init_memory = __esm({
         topicKey: { type: "string", description: "Stable topic key override" },
         action: { type: "string", description: "Secondary action for advanced memory commands" },
         limit: { type: "string", description: "Limit for search/recent output" },
+        quality: { type: "string", description: "Retrieval profile: fast, balanced (default), or thorough" },
         graphLimit: { type: "string", description: "Limit for graph-context output" },
         graphQuery: { type: "string", description: "Query for graph-context packet" },
         format: { type: "string", description: "Output format for graph-context: summary or prompt" },
@@ -24082,7 +24183,10 @@ var init_memory = __esm({
         const positional = (args._ ?? []).slice(1);
         const asJson = !!args.json;
         try {
-          const { project, dataDir, reader, identity } = await getCliProjectContext({ searchIndex: true });
+          const readOnlyActions = /* @__PURE__ */ new Set(["", "search", "graph-context", "recent", "suggest-topic-key", "detail", "timeline"]);
+          const needsSearchIndex = action === "search" || action === "detail" || action === "timeline";
+          const context = readOnlyActions.has(action) ? await getCliReadContext({ searchIndex: needsSearchIndex }) : await getCliProjectContext({ searchIndex: true });
+          const { project, dataDir, reader, identity } = context;
           switch (action) {
             case "search": {
               const query = getStringArg(args.query, positional);
@@ -24091,7 +24195,8 @@ var init_memory = __esm({
                 return;
               }
               const limit = parsePositiveInt(args.limit, 10);
-              const result = await compactSearch({ query, limit, projectId: project.id, reader });
+              const quality = coerceRetrievalQuality(args.quality);
+              const result = await compactSearch({ query, limit, quality, projectId: project.id, reader });
               emitResult({ project, entries: result.entries }, result.formatted, asJson);
               return;
             }
@@ -24396,7 +24501,7 @@ var init_memory = __esm({
               console.log("Memorix Memory Commands");
               console.log("");
               console.log("Usage:");
-              console.log('  memorix memory search --query "timeout bug" [--limit 10]');
+              console.log('  memorix memory search --query "timeout bug" [--limit 10] [--quality fast|balanced|thorough]');
               console.log("  memorix memory recent [--limit 10]");
               console.log('  memorix memory store --text "..." [--title "..."] [--type discovery] [--visibility project|personal|team]');
               console.log('  memorix memory suggest-topic-key --type decision --title "..."');
@@ -67802,21 +67907,6 @@ async function loadWorkspaceForMaintenance(projectId, projectDir2, mode) {
   ]);
   return versioned ?? local;
 }
-function withTimeout(promise, ms, label) {
-  return new Promise((resolve6, reject) => {
-    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve6(value);
-      },
-      (error2) => {
-        clearTimeout(timer);
-        reject(error2);
-      }
-    );
-  });
-}
 async function runAutomaticConsolidation(projectId, projectDir2, options2) {
   const { isLLMEnabled: isLLMEnabled2 } = await Promise.resolve().then(() => (init_provider2(), provider_exports2));
   if (!isLLMEnabled2()) {
@@ -68201,6 +68291,7 @@ var init_project_maintenance = __esm({
     init_esm_shims();
     init_isolated_maintenance();
     init_lifecycle();
+    init_timeout();
     DEFAULT_VECTOR_BATCH_SIZE = 12;
     DEFAULT_RETENTION_BATCH_SIZE = 100;
     DEFAULT_CONSOLIDATION_BATCH_SIZE = 200;
@@ -69960,15 +70051,6 @@ __export(server_exports2, {
   shouldAwaitProjectRuntime: () => shouldAwaitProjectRuntime
 });
 import { createHash as createHash14 } from "crypto";
-function withTimeout2(promise, ms, label) {
-  let timer;
-  return Promise.race([
-    promise,
-    new Promise((_4, reject) => {
-      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-    })
-  ]).finally(() => clearTimeout(timer));
-}
 function formatFormationStageDurations(stageDurationsMs) {
   const orderedStages = ["extract", "resolve", "evaluate"];
   const parts = orderedStages.filter((stage) => stageDurationsMs[stage] !== void 0).map((stage) => `${stage}=${stageDurationsMs[stage]}ms`);
@@ -70323,7 +70405,7 @@ The path should point to a directory containing a .git folder.`
   };
   const server = existingServer ?? new McpServer({
     name: "memorix",
-    version: true ? "1.2.4" : "1.0.1"
+    version: true ? "1.2.5" : "1.0.1"
   });
   const originalRegisterTool = server.registerTool.bind(server);
   server.registerTool = ((name, ...args) => {
@@ -70520,7 +70602,7 @@ The path should point to a directory containing a .git folder.`
                 getEntityNames: () => graphManager.getEntityNames(),
                 onStageEvent: onFormationStageEvent
               };
-              formationResult = await withTimeout2(
+              formationResult = await withTimeout(
                 runFormation({
                   entityName,
                   type,
@@ -70641,7 +70723,7 @@ ${modeIcon} Formation[active]: ${formationResult.evaluation.category} (${formati
                   facts: d3.facts,
                   score: similarEntries[i2]?.score ?? 0
                 }));
-                const decision = await withTimeout2(
+                const decision = await withTimeout(
                   compactOnWrite(
                     { title, narrative, facts: safeFacts ?? [] },
                     existingMemories
@@ -70737,7 +70819,7 @@ Mode: ${decision.usedLLM ? "LLM" : "heuristic"}`
           let compressionNote = "";
           try {
             const { compressNarrative: compressNarrative2 } = await Promise.resolve().then(() => (init_quality(), quality_exports));
-            const { compressed, saved, usedLLM } = await withTimeout2(
+            const { compressed, saved, usedLLM } = await withTimeout(
               compressNarrative2(narrative, safeFacts, type),
               COMPRESSION_TIMEOUT_MS,
               "Narrative compression"
@@ -70859,7 +70941,7 @@ Auto-enriched: ${enrichmentParts.join(", ")}` : "";
                 },
                 getEntityNames: () => graphManager.getEntityNames()
               };
-              const formed = await withTimeout2(
+              const formed = await withTimeout(
                 runFormation({ entityName, type, title, narrative, facts: safeFacts, projectId: project.id, source: "explicit", topicKey }, formationConfig),
                 FORMATION_TIMEOUT_MS,
                 "Shadow formation"
@@ -70950,6 +71032,9 @@ Use this as the \`topicKey\` parameter in \`memorix_store\` to enable upsert beh
         source: external_exports.enum(["agent", "git", "manual"]).optional().describe(
           'Filter by memory source. "git" returns only commit-derived ground truth memories. Omit for all sources.'
         ),
+        quality: external_exports.enum(["fast", "balanced", "thorough"]).optional().default("balanced").describe(
+          "Retrieval profile: fast stays local, balanced uses configured embeddings, thorough explicitly permits optional LLM refinement."
+        ),
         purpose: external_exports.string().optional().describe(
           "Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user's explicit request."
         ),
@@ -70958,7 +71043,7 @@ Use this as the \`topicKey\` parameter in \`memorix_store\` to enable upsert beh
         )
       }
     },
-    async ({ query, limit, type, maxTokens, scope, since, until, status, source, purpose, force }) => {
+    async ({ query, limit, type, maxTokens, scope, since, until, status, source, quality, purpose, force }) => {
       if (scope !== "global") {
         const unresolved = requireResolvedProject("search the current project");
         if (unresolved) return unresolved;
@@ -70983,16 +71068,14 @@ Use this as the \`topicKey\` parameter in \`memorix_store\` to enable upsert beh
           projectId: scope === "global" ? void 0 : project.id,
           status: status ?? "active",
           source,
+          quality,
           reader: getObservationReader(scope === "global" ? "global" : "project")
         });
-        const timeoutPromise = new Promise(
-          (_4, reject) => setTimeout(() => reject(new Error(`Search timeout after ${TIMEOUT_MS}ms`)), TIMEOUT_MS)
-        );
         let result;
         try {
-          result = await Promise.race([searchPromise, timeoutPromise]);
+          result = await withTimeout(searchPromise, TIMEOUT_MS, "Search");
         } catch (error2) {
-          if (error2 instanceof Error && error2.message.includes("timeout")) {
+          if (error2 instanceof Error && /\btimeout\b|timed out/i.test(error2.message)) {
             return {
               content: [
                 {
@@ -74085,6 +74168,7 @@ var init_server4 = __esm({
     init_memory_manager();
     init_formation();
     init_formation_timeout();
+    init_timeout();
     FORMATION_TIMEOUT_MS = parseFormationTimeoutMs(process.env.MEMORIX_FORMATION_TIMEOUT_MS);
     COMPACT_ON_WRITE_TIMEOUT_MS = 12e3;
     COMPRESSION_TIMEOUT_MS = 5e3;
@@ -91533,12 +91617,14 @@ var main = defineCommand({
       args: {
         query: { type: "positional", description: "Search query", required: true },
         limit: { type: "string", description: "Maximum results" },
+        quality: { type: "string", description: "Retrieval profile: fast, balanced (default), or thorough" },
         json: { type: "boolean", description: "Emit machine-readable JSON output" }
       },
       async run({ args }) {
         await runMemoryShortcut("search", {
           query: args.query,
           limit: args.limit,
+          quality: args.quality,
           json: args.json
         });
       }