@exaudeus/memory-mcp 1.7.0 → 1.9.0

package/dist/config.d.ts

@@ -1,4 +1,5 @@
-import type { MemoryConfig, BehaviorConfig } from './types.js';
+import type { MemoryConfig, BehaviorConfig, EmbedderConfig } from './types.js';
+import type { Embedder } from './embedder.js';
 /** How the config was loaded — discriminated union so configFilePath
  *  only exists when source is 'file' (illegal states unrepresentable) */
 export type ConfigOrigin = {
@@ -15,6 +16,8 @@ export interface LoadedConfig {
     readonly origin: ConfigOrigin;
     /** Resolved behavior config — present when a "behavior" block was found in memory-config.json */
     readonly behavior?: BehaviorConfig;
+    /** Resolved embedder — shared across all lobes. Constructed from config or auto-detected. */
+    readonly embedder?: Embedder;
 }
 interface MemoryConfigFileBehavior {
     staleDaysStandard?: number;
@@ -23,10 +26,26 @@ interface MemoryConfigFileBehavior {
     maxDedupSuggestions?: number;
     maxConflictPairs?: number;
 }
+interface MemoryConfigFileEmbedder {
+    provider?: string;
+    model?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    dimensions?: number;
+}
 /** Parse and validate a behavior config block, falling back to defaults for each field.
  *  Warns to stderr for unknown keys (likely typos) and out-of-range values.
  *  Exported for testing — validates and clamps all fields. */
 export declare function parseBehaviorConfig(raw?: MemoryConfigFileBehavior): BehaviorConfig;
+/** Parse and validate an embedder config block.
+ *  Returns undefined when block is absent (auto-detect mode).
+ *  Exported for testing. */
+export declare function parseEmbedderConfig(raw?: MemoryConfigFileEmbedder): EmbedderConfig | undefined;
+/** Create an Embedder from config.
+ *  - provider "none" → null (keyword-only)
+ *  - provider "ollama" → LazyEmbedder wrapping OllamaEmbedder with config params
+ *  - No config (auto-detect) → LazyEmbedder wrapping default OllamaEmbedder */
+export declare function createEmbedderFromConfig(config?: EmbedderConfig): Embedder | undefined;
 /** Load lobe configs with priority: memory-config.json -> env vars -> single-repo default */
 export declare function getLobeConfigs(): LoadedConfig;
 export {};

package/dist/config.js

@@ -7,6 +7,7 @@ import { execFileSync } from 'child_process';
 import path from 'path';
 import os from 'os';
 import { DEFAULT_STORAGE_BUDGET_BYTES } from './types.js';
+import { OllamaEmbedder, LazyEmbedder } from './embedder.js';
 import { DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, } from './thresholds.js';
 /** Validate and clamp a numeric threshold to a given range.
  *  Returns the default if the value is missing, NaN, or out of range. */
@@ -46,6 +47,61 @@ export function parseBehaviorConfig(raw) {
         maxConflictPairs: clampThreshold(raw.maxConflictPairs, DEFAULT_MAX_CONFLICT_PAIRS, 1, 5),
     };
 }
+/** Known embedder config keys — used to warn on typos/unknown fields. */
+const KNOWN_EMBEDDER_KEYS = new Set([
+    'provider', 'model', 'baseUrl', 'timeoutMs', 'dimensions',
+]);
+const VALID_PROVIDERS = new Set(['ollama', 'none']);
+/** Parse and validate an embedder config block.
+ *  Returns undefined when block is absent (auto-detect mode).
+ *  Exported for testing. */
+export function parseEmbedderConfig(raw) {
+    if (!raw)
+        return undefined;
+    // Warn on unrecognized keys
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_EMBEDDER_KEYS.has(key)) {
+            process.stderr.write(`[memory-mcp] Unknown embedder config key "${key}" — ignored. ` +
+                `Valid keys: ${Array.from(KNOWN_EMBEDDER_KEYS).join(', ')}\n`);
+        }
+    }
+    // Validate provider — default to 'ollama' if present but not set
+    const provider = raw.provider && VALID_PROVIDERS.has(raw.provider)
+        ? raw.provider
+        : 'ollama';
+    if (raw.provider && !VALID_PROVIDERS.has(raw.provider)) {
+        process.stderr.write(`[memory-mcp] Unknown embedder provider "${raw.provider}" — using "ollama". Valid: ${Array.from(VALID_PROVIDERS).join(', ')}\n`);
+    }
+    return {
+        provider,
+        model: raw.model,
+        baseUrl: raw.baseUrl,
+        timeoutMs: raw.timeoutMs !== undefined
+            ? clampThreshold(raw.timeoutMs, 5000, 500, 30000)
+            : undefined,
+        dimensions: raw.dimensions !== undefined
+            ? clampThreshold(raw.dimensions, 384, 64, 4096)
+            : undefined,
+    };
+}
+/** Create an Embedder from config.
+ *  - provider "none" → null (keyword-only)
+ *  - provider "ollama" → LazyEmbedder wrapping OllamaEmbedder with config params
+ *  - No config (auto-detect) → LazyEmbedder wrapping default OllamaEmbedder */
+export function createEmbedderFromConfig(config) {
+    // Explicit opt-out
+    if (config?.provider === 'none')
+        return undefined;
+    // Explicit or default Ollama config
+    const candidate = new OllamaEmbedder({
+        model: config?.model,
+        baseUrl: config?.baseUrl,
+        timeoutMs: config?.timeoutMs,
+        dimensions: config?.dimensions,
+    });
+    // Both explicit "ollama" and auto-detect use LazyEmbedder for fast startup
+    return new LazyEmbedder(candidate);
+}
 function resolveRoot(root) {
     return root
         .replace(/^\$HOME\b/, process.env.HOME ?? '')
@@ -84,7 +140,7 @@ function resolveMemoryPath(repoRoot, workspaceName, explicitMemoryDir) {
 /** If no lobe has alwaysInclude: true AND the legacy global store directory has actual entries,
  *  auto-create a "global" lobe pointing to it. Protects existing users who haven't updated their config.
  *  Only fires when the dir contains .md files — an empty dir doesn't trigger creation. */
-function ensureAlwaysIncludeLobe(configs, behavior) {
+function ensureAlwaysIncludeLobe(configs, behavior, embedder) {
     const hasAlwaysInclude = Array.from(configs.values()).some(c => c.alwaysInclude);
     if (hasAlwaysInclude)
         return;
@@ -114,6 +170,7 @@ function ensureAlwaysIncludeLobe(configs, behavior) {
         storageBudgetBytes: DEFAULT_STORAGE_BUDGET_BYTES,
         alwaysInclude: true,
         behavior,
+        embedder,
     });
     process.stderr.write(`[memory-mcp] Auto-created "global" lobe (alwaysInclude) from existing ${globalPath}\n`);
 }
@@ -131,6 +188,8 @@ export function getLobeConfigs() {
         else {
             // Parse global behavior config once — applies to all lobes
             const behavior = parseBehaviorConfig(external.behavior);
+            const embedderConfig = parseEmbedderConfig(external.embedder);
+            const embedder = createEmbedderFromConfig(embedderConfig);
             for (const [name, config] of Object.entries(external.lobes)) {
                 if (!config.root) {
                     process.stderr.write(`[memory-mcp] Skipping lobe "${name}": missing "root" field\n`);
@@ -143,14 +202,15 @@ export function getLobeConfigs() {
                     storageBudgetBytes: (config.budgetMB ?? 2) * 1024 * 1024,
                     alwaysInclude: config.alwaysInclude ?? false,
                     behavior,
+                    embedder,
                 });
             }
             if (configs.size > 0) {
                 // Reuse the already-parsed behavior config for the alwaysInclude fallback
                 const resolvedBehavior = external.behavior ? behavior : undefined;
-                ensureAlwaysIncludeLobe(configs, resolvedBehavior);
+                ensureAlwaysIncludeLobe(configs, resolvedBehavior, embedder);
                 process.stderr.write(`[memory-mcp] Loaded ${configs.size} lobe(s) from memory-config.json\n`);
-                return { configs, origin: { source: 'file', path: configPath }, behavior: resolvedBehavior };
+                return { configs, origin: { source: 'file', path: configPath }, behavior: resolvedBehavior, embedder };
             }
         }
     }
@@ -162,6 +222,8 @@ export function getLobeConfigs() {
             process.stderr.write(`[memory-mcp] Failed to parse memory-config.json: ${message}\n`);
         }
     }
+    // Auto-detect embedder for env var and default modes (no config file)
+    const autoEmbedder = createEmbedderFromConfig(undefined);
     // 2. Try env var multi-repo mode
     const workspacesJson = process.env.MEMORY_MCP_WORKSPACES;
     if (workspacesJson) {
@@ -176,12 +238,13 @@ export function getLobeConfigs() {
                     memoryPath: resolveMemoryPath(repoRoot, name, explicitDir),
                     storageBudgetBytes: storageBudget,
                     alwaysInclude: false,
+                    embedder: autoEmbedder,
                 });
             }
             if (configs.size > 0) {
-                ensureAlwaysIncludeLobe(configs);
+                ensureAlwaysIncludeLobe(configs, undefined, autoEmbedder);
                 process.stderr.write(`[memory-mcp] Loaded ${configs.size} lobe(s) from MEMORY_MCP_WORKSPACES env var\n`);
-                return { configs, origin: { source: 'env' } };
+                return { configs, origin: { source: 'env' }, embedder: autoEmbedder };
             }
         }
         catch (e) {
@@ -197,8 +260,9 @@ export function getLobeConfigs() {
         memoryPath: resolveMemoryPath(repoRoot, 'default', explicitDir),
         storageBudgetBytes: storageBudget,
         alwaysInclude: false,
+        embedder: autoEmbedder,
     });
     // No ensureAlwaysIncludeLobe here — single-repo default users have everything in one lobe
     process.stderr.write(`[memory-mcp] Using single-lobe default mode (cwd: ${repoRoot})\n`);
-    return { configs, origin: { source: 'default' } };
+    return { configs, origin: { source: 'default' }, embedder: autoEmbedder };
 }

package/dist/embedder.d.ts

@@ -60,6 +60,28 @@ export declare class FakeEmbedder implements Embedder {
     constructor(dimensions?: number);
     embed(text: string, _signal?: AbortSignal): Promise<EmbedResult>;
 }
+/** Lazy auto-detecting embedder — probes on first use, caches the result.
+ *  Re-probes on failure after a TTL window so the system recovers if
+ *  Ollama starts after MCP startup.
+ *
+ *  Implements the same Embedder interface — the store never knows it's lazy.
+ *  The probe uses the candidate's own timeout (5s for cold starts).
+ *  The caller's signal is only forwarded to the actual embed call, not the probe. */
+export declare class LazyEmbedder implements Embedder {
+    readonly dimensions: number;
+    private inner;
+    private lastProbeTime;
+    private hasLoggedUnavailable;
+    private readonly candidate;
+    private readonly reprobeIntervalMs;
+    private readonly now;
+    constructor(candidate: Embedder, opts?: {
+        readonly reprobeIntervalMs?: number;
+        /** Injectable clock for testing — default Date.now */
+        readonly now?: () => number;
+    });
+    embed(text: string, signal?: AbortSignal): Promise<EmbedResult>;
+}
 /** Batch embed texts sequentially. Pure composition over Embedder.embed().
  *  Sequential because local Ollama benefits from serialized requests (single GPU/CPU).
  *  Not on the interface — interface segregation. */

package/dist/embedder.js

@@ -130,6 +130,56 @@ function trigramHash(trigram, buckets) {
     }
     return ((hash % buckets) + buckets) % buckets;
 }
+// ─── LazyEmbedder ─────────────────────────────────────────────────────────
+/** Default reprobe interval — how long to wait before retrying after a failed probe.
+ *  2 minutes balances responsiveness (recovery after Ollama starts) with
+ *  avoiding excessive probes when Ollama isn't installed. */
+const DEFAULT_REPROBE_INTERVAL_MS = 2 * 60 * 1000;
+/** Lazy auto-detecting embedder — probes on first use, caches the result.
+ *  Re-probes on failure after a TTL window so the system recovers if
+ *  Ollama starts after MCP startup.
+ *
+ *  Implements the same Embedder interface — the store never knows it's lazy.
+ *  The probe uses the candidate's own timeout (5s for cold starts).
+ *  The caller's signal is only forwarded to the actual embed call, not the probe. */
+export class LazyEmbedder {
+    constructor(candidate, opts) {
+        this.inner = null;
+        this.lastProbeTime = -Infinity;
+        this.hasLoggedUnavailable = false;
+        this.candidate = candidate;
+        this.dimensions = candidate.dimensions;
+        this.reprobeIntervalMs = opts?.reprobeIntervalMs ?? DEFAULT_REPROBE_INTERVAL_MS;
+        this.now = opts?.now ?? Date.now;
+    }
+    async embed(text, signal) {
+        const now = this.now();
+        const shouldProbe = !this.inner && (now - this.lastProbeTime >= this.reprobeIntervalMs);
+        if (shouldProbe) {
+            this.lastProbeTime = now;
+            // Probe without caller's signal — use candidate's default timeout (5s)
+            // so cold model loads aren't aborted by a tight query-time timeout
+            const probe = await this.candidate.embed('probe');
+            if (probe.ok) {
+                this.inner = this.candidate;
+                if (this.hasLoggedUnavailable) {
+                    // Recovery after previous failure — notify
+                    process.stderr.write('[memory-mcp] Embedding provider recovered — semantic search active\n');
+                    this.hasLoggedUnavailable = false;
+                }
+            }
+            else if (!this.hasLoggedUnavailable) {
+                // Only log first failure — avoid noisy repeated warnings
+                process.stderr.write(`[memory-mcp] Embedding provider not available — using keyword-only search (will retry in ${Math.round(this.reprobeIntervalMs / 1000)}s)\n`);
+                this.hasLoggedUnavailable = true;
+            }
+        }
+        if (!this.inner) {
+            return { ok: false, failure: { kind: 'provider-unavailable', reason: 'auto-detect: provider not available' } };
+        }
+        return this.inner.embed(text, signal);
+    }
+}
 // ─── Batch utility ────────────────────────────────────────────────────────
 /** Batch embed texts sequentially. Pure composition over Embedder.embed().
  *  Sequential because local Ollama benefits from serialized requests (single GPU/CPU).

package/dist/formatters.d.ts

@@ -1,6 +1,15 @@
-import type { MemoryStats, StaleEntry, ConflictPair, BehaviorConfig } from './types.js';
+import type { MemoryStats, StaleEntry, ConflictPair, BehaviorConfig, RelatedEntry } from './types.js';
 import { type FilterGroup } from './text-analyzer.js';
 import type { MarkdownMemoryStore } from './store.js';
+/** Format the search mode indicator for context/recall responses.
+ *  Pure function — no I/O, no state.
+ *
+ *  Shows whether semantic search is active and vector coverage. */
+export declare function formatSearchMode(embedderAvailable: boolean, vectorCount: number, totalCount: number): string;
+/** Format the loot-drop section — related entries shown after a storage operation.
+ *  Transforms storage from "chore for the future" into "immediate value exchange."
+ *  Pure function. */
+export declare function formatLootDrop(related: readonly RelatedEntry[]): string;
 /** Format the stale entries section for briefing/context responses */
 export declare function formatStaleSection(staleDetails: readonly StaleEntry[]): string;
 /** Format the conflict detection warning for query/context responses */

package/dist/formatters.js

@@ -4,6 +4,31 @@
 // and returns a formatted string for the tool response.
 import { DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, MAX_FOOTER_TAGS, WARN_SEPARATOR, } from './thresholds.js';
 import { analyzeFilterGroups } from './text-analyzer.js';
+/** Format the search mode indicator for context/recall responses.
+ *  Pure function — no I/O, no state.
+ *
+ *  Shows whether semantic search is active and vector coverage. */
+export function formatSearchMode(embedderAvailable, vectorCount, totalCount) {
+    if (!embedderAvailable) {
+        return '*Search: keyword-only (install Ollama for semantic search)*';
+    }
+    if (vectorCount === 0 && totalCount > 0) {
+        return `*Search: semantic + keyword (0/${totalCount} entries vectorized — run memory_reembed)*`;
+    }
+    if (totalCount === 0) {
+        return '*Search: semantic + keyword (no entries yet)*';
+    }
+    return `*Search: semantic + keyword (${vectorCount}/${totalCount} entries vectorized)*`;
+}
+/** Format the loot-drop section — related entries shown after a storage operation.
+ *  Transforms storage from "chore for the future" into "immediate value exchange."
+ *  Pure function. */
+export function formatLootDrop(related) {
+    if (related.length === 0)
+        return '';
+    const lines = related.map(r => `- [${r.id}] "${r.title}" (confidence: ${r.confidence.toFixed(2)})`);
+    return `\n**Related knowledge:**\n${lines.join('\n')}`;
+}
 /** Format the stale entries section for briefing/context responses */
 export function formatStaleSection(staleDetails) {
     const lines = [
@@ -61,11 +86,12 @@ export function formatStats(lobe, result) {
             .join('\n')
         : '  (none)';
     const corruptLine = result.corruptFiles > 0 ? `\n**Corrupt files:** ${result.corruptFiles}` : '';
+    const vectorLine = `\n**Vectors:** ${result.vectorCount}/${result.totalEntries} entries vectorized`;
     return [
         `## [${lobe}] Memory Stats`,
         ``,
         `**Memory location:** ${result.memoryPath}`,
-        `**Total entries:** ${result.totalEntries}${corruptLine}`,
+        `**Total entries:** ${result.totalEntries}${corruptLine}${vectorLine}`,
         `**Storage:** ${result.storageSize} / ${Math.round(result.storageBudgetBytes / 1024 / 1024)}MB budget`,
         ``,
         `### By Topic`,