memorix 1.2.4 → 1.2.5

package/dist/memcode-runtime/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/sdk.d.ts

@@ -1,4 +1,4 @@
-import { Entity, Relation, KnowledgeGraph, ProjectInfo, DetectionResult, ObservationType, ObservationStatus, ProgressInfo, Observation, IndexEntry } from './types.js';
+import { Entity, Relation, KnowledgeGraph, ProjectInfo, DetectionResult, ObservationType, ObservationStatus, RetrievalQuality, ProgressInfo, Observation, IndexEntry } from './types.js';
 export { AgentTarget, DEFAULT_CONFIG, DetectionFailure, DetectionFailureReason, DocumentType, KnowledgeLayer, MCPConfigAdapter, MCPServerEntry, MemorixConfig, MemorixDocument, MemoryRef, MiniSkill, OBSERVATION_ICONS, ObservationAdmissionState, ObservationReader, ObservationRef, ObservationVisibility, RuleFormatAdapter, RuleSource, SearchOptions, Session, SkillConflict, SkillEntry, SnapshotObservation, SourceSnapshot, TOPIC_KEY_FAMILIES, TimelineContext, UnifiedRule, WorkflowEntry, WorkspaceSyncResult } from './types.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
@@ -559,6 +559,8 @@ interface ClientSearchOptions {
     status?: ObservationStatus | 'all';
     /** Maximum results. Default: 20 */
     limit?: number;
+    /** Retrieval profile. Default: balanced. */
+    quality?: RetrievalQuality;
 }
 /** Result from resolving observations */
 interface ResolveResult {
@@ -687,4 +689,4 @@ declare class MemoryClient {
  */
 declare function createMemoryClient(options: MemoryClientOptions): Promise<MemoryClient>;
 
-export { type ClientSearchOptions, type CreateMemorixServerOptions, DetectionResult, Entity, IndexEntry, KnowledgeGraph, MemoryClient, type MemoryClientOptions, Observation, ObservationStatus, ObservationType, ProgressInfo, ProjectInfo, Relation, type ResolveResult, type StoreInput, type StoreResult, createMemorixServer, createMemoryClient, detectProject, detectProjectWithDiagnostics };
+export { type ClientSearchOptions, type CreateMemorixServerOptions, DetectionResult, Entity, IndexEntry, KnowledgeGraph, MemoryClient, type MemoryClientOptions, Observation, ObservationStatus, ObservationType, ProgressInfo, ProjectInfo, Relation, type ResolveResult, RetrievalQuality, type StoreInput, type StoreResult, createMemorixServer, createMemoryClient, detectProject, detectProjectWithDiagnostics };

package/dist/sdk.js

@@ -2807,6 +2807,25 @@ function getResolvedConfig(options = {}) {
   const legacy = loadFileConfig();
   const embeddingBaseUrl = first(process.env.MEMORIX_EMBEDDING_BASE_URL, toml.embedding?.base_url, yaml2.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,
+    yaml2.llm?.provider,
+    legacy.llm?.provider
+  );
+  const memoryLlmModel = first(
+    process.env.MEMORIX_LLM_MODEL,
+    toml.memory?.llm?.model,
+    yaml2.llm?.model,
+    legacy.llm?.model
+  );
+  const memoryLlmBaseUrl = first(
+    process.env.MEMORIX_LLM_BASE_URL,
+    toml.memory?.llm?.base_url,
+    yaml2.llm?.baseUrl,
+    legacy.llm?.baseUrl
+  );
+  const openRouterMemoryLlmApiKey = isOpenRouterMemoryLane(memoryLlmProvider, memoryLlmBaseUrl) ? process.env.OPENROUTER_API_KEY : void 0;
   const resolved = {
     agent: {
       provider: first(
@@ -2844,9 +2863,9 @@ function getResolvedConfig(options = {}) {
       autoCleanup: firstBool(toml.memory?.auto_cleanup, yaml2.behavior?.autoCleanup),
       syncAdvisory: firstBool(toml.memory?.sync_advisory, yaml2.behavior?.syncAdvisory),
       llm: {
-        provider: first(process.env.MEMORIX_LLM_PROVIDER, toml.memory?.llm?.provider, yaml2.llm?.provider, legacy.llm?.provider),
-        model: first(process.env.MEMORIX_LLM_MODEL, toml.memory?.llm?.model, yaml2.llm?.model, legacy.llm?.model),
-        baseUrl: first(process.env.MEMORIX_LLM_BASE_URL, toml.memory?.llm?.base_url, yaml2.llm?.baseUrl, legacy.llm?.baseUrl),
+        provider: memoryLlmProvider,
+        model: memoryLlmModel,
+        baseUrl: memoryLlmBaseUrl,
         apiKey: first(
           process.env.MEMORIX_LLM_API_KEY,
           process.env.MEMORIX_API_KEY,
@@ -2855,7 +2874,7 @@ function getResolvedConfig(options = {}) {
           legacy.llm?.apiKey,
           process.env.OPENAI_API_KEY,
           process.env.ANTHROPIC_API_KEY,
-          process.env.OPENROUTER_API_KEY
+          openRouterMemoryLlmApiKey
         )
       }
     },
@@ -2992,6 +3011,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;
@@ -5039,6 +5061,29 @@ Rules:
   }
 });
 
+// src/timeout.ts
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve2(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+var init_timeout = __esm({
+  "src/timeout.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/project/aliases.ts
 var aliases_exports = {};
 __export(aliases_exports, {
@@ -5804,8 +5849,12 @@ async function searchObservations(options) {
     }
   };
   const modeKey = options.projectId ?? SEARCH_MODE_DEFAULT_KEY;
-  lastSearchModeByProject.set(modeKey, embeddingEnabled ? "hybrid" : "fulltext");
+  const quality = options.quality ?? "balanced";
   const database = await getDb();
+  lastSearchModeByProject.set(
+    modeKey,
+    quality === "fast" ? "fulltext (fast profile)" : embeddingEnabled ? "hybrid" : "fulltext"
+  );
   let projectIds = null;
   if (options.projectId) {
     try {
@@ -5827,11 +5876,15 @@ async function searchObservations(options) {
   }
   const hasQuery = options.query && options.query.trim().length > 0;
   const originalQuery = options.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(options.query) : options.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(options.query) : options.query;
   mark("queryExpansion");
-  const intentResult = hasQuery ? detectQueryIntent(originalQuery) : null;
+  const intentResult = quality === "fast" || !hasQuery ? null : detectQueryIntent(originalQuery);
   const requestLimit = projectIds ? (options.limit ?? 20) * 3 : options.limit ?? 20;
   const defaultBoost = {
     title: 3,
@@ -5845,17 +5898,21 @@ async function searchObservations(options) {
   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) {
@@ -5870,11 +5927,11 @@ async function searchObservations(options) {
           );
         } else {
           const EMBEDDING_TIMEOUT_MS = 15e3;
-          const embedPromise = provider2.embed(expandedEmbeddingQuery);
-          const timeoutPromise = new Promise(
-            (_, 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;
@@ -6115,7 +6172,7 @@ async function searchObservations(options) {
       }
     }
   }
-  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 second = intermediate[1]?.score ?? 0;
     return top > 0 && second / top > 0.7;
@@ -6139,11 +6196,11 @@ async function searchObservations(options) {
       }));
       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(
-        (_, 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");
@@ -6335,6 +6392,7 @@ var init_orama_store = __esm({
     init_project_affinity();
     init_intent_detector();
     init_query_expansion();
+    init_timeout();
     db = null;
     dbInitPromise = null;
     dbGeneration = 0;
@@ -14859,21 +14917,6 @@ async function loadWorkspaceForMaintenance(projectId, projectDir2, mode) {
   ]);
   return versioned ?? local;
 }
-function withTimeout(promise, ms, label) {
-  return new Promise((resolve2, reject) => {
-    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve2(value);
-      },
-      (error) => {
-        clearTimeout(timer);
-        reject(error);
-      }
-    );
-  });
-}
 async function runAutomaticConsolidation(projectId, projectDir2, options) {
   const { isLLMEnabled: isLLMEnabled2 } = await Promise.resolve().then(() => (init_provider2(), provider_exports2));
   if (!isLLMEnabled2()) {
@@ -15258,6 +15301,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;
@@ -26805,18 +26849,10 @@ function parseFormationTimeoutMs(raw) {
 }
 
 // src/server.ts
+init_timeout();
 var FORMATION_TIMEOUT_MS = parseFormationTimeoutMs(process.env.MEMORIX_FORMATION_TIMEOUT_MS);
 var COMPACT_ON_WRITE_TIMEOUT_MS = 12e3;
 var COMPRESSION_TIMEOUT_MS = 5e3;
-function withTimeout2(promise, ms, label) {
-  let timer;
-  return Promise.race([
-    promise,
-    new Promise((_, 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`);
@@ -27192,7 +27228,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) => {
@@ -27389,7 +27425,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,
@@ -27510,7 +27546,7 @@ ${modeIcon} Formation[active]: ${formationResult.evaluation.category} (${formati
                   facts: d.facts,
                   score: similarEntries[i]?.score ?? 0
                 }));
-                const decision = await withTimeout2(
+                const decision = await withTimeout(
                   compactOnWrite(
                     { title, narrative, facts: safeFacts ?? [] },
                     existingMemories
@@ -27606,7 +27642,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"
@@ -27728,7 +27764,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"
@@ -27819,6 +27855,9 @@ Use this as the \`topicKey\` parameter in \`memorix_store\` to enable upsert beh
         source: z2.enum(["agent", "git", "manual"]).optional().describe(
           'Filter by memory source. "git" returns only commit-derived ground truth memories. Omit for all sources.'
         ),
+        quality: z2.enum(["fast", "balanced", "thorough"]).optional().default("balanced").describe(
+          "Retrieval profile: fast stays local, balanced uses configured embeddings, thorough explicitly permits optional LLM refinement."
+        ),
         purpose: z2.string().optional().describe(
           "Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user's explicit request."
         ),
@@ -27827,7 +27866,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;
@@ -27852,16 +27891,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(
-          (_, 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 (error) {
-          if (error instanceof Error && error.message.includes("timeout")) {
+          if (error instanceof Error && /\btimeout\b|timed out/i.test(error.message)) {
             return {
               content: [
                 {
@@ -31030,6 +31067,7 @@ var MemoryClient = class {
       type: options.type,
       source: options.source,
       status: options.status === "all" ? void 0 : options.status ?? "active",
+      quality: options.quality,
       reader: this._reader
     };
     return this._oramaStore.searchObservations(searchOpts);