@exaudeus/memory-mcp 1.6.0 → 1.8.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,11 @@
 import type { MemoryStats, StaleEntry, ConflictPair, BehaviorConfig } 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 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,22 @@
 // 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 stale entries section for briefing/context responses */
 export function formatStaleSection(staleDetails) {
     const lines = [
@@ -61,11 +77,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`,

package/dist/index.js

@@ -14,7 +14,7 @@ import { getLobeConfigs } from './config.js';
 import { ConfigManager } from './config-manager.js';
 import { normalizeArgs } from './normalize.js';
 import { buildCrashReport, writeCrashReport, writeCrashReportSync, readLatestCrash, readCrashHistory, clearLatestCrash, formatCrashReport, formatCrashSummary, markServerStarted, } from './crash-journal.js';
-import { formatStaleSection, formatConflictWarning, formatStats, formatBehaviorConfigSection, mergeTagFrequencies, buildQueryFooter, buildBriefingTagPrimerSections } from './formatters.js';
+import { formatStaleSection, formatConflictWarning, formatStats, formatBehaviorConfigSection, mergeTagFrequencies, buildQueryFooter, buildBriefingTagPrimerSections, formatSearchMode } from './formatters.js';
 import { parseFilter } from './text-analyzer.js';
 import { VOCABULARY_ECHO_LIMIT, WARN_SEPARATOR } from './thresholds.js';
 import { matchRootsToLobeNames, buildLobeResolution } from './lobe-resolution.js';
@@ -398,6 +398,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // memory_diagnose is intentionally hidden from the tool list — it clutters
             // agent tool discovery and should only be called when directed by error messages
             // or crash reports. The handler still works if called directly.
+            // memory_reembed is hidden — utility for generating/regenerating embeddings.
+            // Surfaced via hint in memory_context when >50% of entries lack vectors.
         ] };
 });
 // --- Tool handlers ---
@@ -909,6 +911,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 // --- Search mode: context provided → keyword search across all topics ---
                 const max = maxResults ?? 10;
                 const threshold = minMatch ?? 0.2;
+                // Resolve which lobes to search — follows the degradation ladder via resolveLobesForRead().
                 const allLobeResults = [];
                 const ctxEntryLobeMap = new Map(); // entry id → lobe name
                 let label;
@@ -973,10 +976,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const noResultHint = ctxGlobalOnlyHint
                         ? `\n\n> ${ctxGlobalOnlyHint}`
                         : '\n\nThis is fine — proceed without prior context. As you learn things worth remembering, store them with memory_store.';
+                    // Mode indicator on no-results path — helps diagnose why nothing was found
+                    const modeHint = primaryStore
+                        ? `\n${formatSearchMode(primaryStore.hasEmbedder, primaryStore.vectorCount, primaryStore.entryCount)}`
+                        : '';
                     return {
                         content: [{
                                 type: 'text',
-                                text: `[${label}] No relevant knowledge found for: "${context}"${noResultHint}\n\n---\n${ctxFooter}`,
+                                text: `[${label}] No relevant knowledge found for: "${context}"${noResultHint}${modeHint}\n\n---\n${ctxFooter}`,
                             }],
                     };
                 }
@@ -1019,6 +1026,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         sections.push(formatConflictWarning(ctxConflicts));
                     }
                 }
+                // Search mode indicator — lightweight getters, no extra disk reload
+                if (primaryStore) {
+                    sections.push(formatSearchMode(primaryStore.hasEmbedder, primaryStore.vectorCount, primaryStore.entryCount));
+                }
                 // Collect all matched keywords and topics for the dedup hint
                 const allMatchedKeywords = new Set();
                 const matchedTopics = new Set();
@@ -1070,6 +1081,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 return { content: [{ type: 'text', text: sections.join('\n\n---\n\n') }] };
             }
+            case 'memory_reembed': {
+                const { lobe: rawLobe } = z.object({
+                    lobe: z.string().optional(),
+                }).parse(args ?? {});
+                const lobeName = rawLobe ?? lobeNames[0];
+                const ctx = resolveToolContext(lobeName);
+                if (!ctx.ok)
+                    return contextError(ctx);
+                const result = await ctx.store.reEmbed();
+                if (result.error) {
+                    return { content: [{ type: 'text', text: `[${ctx.label}] Re-embed failed: ${result.error}` }] };
+                }
+                const parts = [
+                    `[${ctx.label}] Re-embedded ${result.embedded} entries`,
+                    `(${result.skipped} skipped, ${result.failed} failed).`,
+                ];
+                // Hint if many entries were vectorized
+                if (result.embedded > 0) {
+                    parts.push('\nSemantic search is now active for these entries.');
+                }
+                return { content: [{ type: 'text', text: parts.join(' ') }] };
+            }
             case 'memory_bootstrap': {
                 const { lobe: rawLobe, root, budgetMB } = z.object({
                     lobe: z.string().optional(),

package/dist/ranking.d.ts

@@ -0,0 +1,57 @@
+import type { MemoryEntry, EmbeddingVector } from './types.js';
+/** Which ranking signal produced this result. */
+export type RankSource = 'keyword' | 'semantic' | 'merged';
+/** A scored search result. Shared return type for all ranking functions. */
+export interface ScoredEntry {
+    readonly entry: MemoryEntry;
+    readonly score: number;
+    readonly matchedKeywords: readonly string[];
+    readonly source: RankSource;
+    /** Raw cosine similarity before boost multiplication.
+     *  Present for semantic and merged results; absent for keyword-only.
+     *  Used for debug logging (threshold calibration) and display. */
+    readonly semanticSimilarity?: number;
+}
+/** Shared context for ranking functions — pure data, no callbacks.
+ *  Groups the parameters that keywordRank and semanticRank need,
+ *  keeping function signatures tight.
+ *
+ *  freshEntryIds is precomputed by the store — the ranking function checks
+ *  set membership rather than calling into the store's private staleness logic.
+ *  This keeps the function provably pure.
+ *
+ *  defaultModuleBoost is the fallback boost for modules/* topics not in topicBoost.
+ *  Injected here so ranking.ts needs zero direct threshold imports. */
+export interface RankContext {
+    readonly currentBranch: string;
+    readonly branchFilter: string | undefined;
+    readonly topicBoost: Readonly<Record<string, number>>;
+    readonly freshEntryIds: ReadonlySet<string>;
+    readonly defaultModuleBoost: number;
+}
+/** Rank entries by keyword overlap with context keywords.
+ *  Pure extraction of the ranking logic from contextSearch — identical scoring.
+ *
+ *  Filter + rank in one pass for efficiency (~200 entries, not worth two iterations).
+ *  Branch filtering for recent-work is applied here because it's a pre-condition
+ *  for ranking, not a separate pipeline stage.
+ *
+ *  Does NOT include the "always include user entries" policy — that's an
+ *  orchestration concern that stays in contextSearch. */
+export declare function keywordRank(entries: readonly MemoryEntry[], contextKeywords: ReadonlySet<string>, minMatch: number, ctx: RankContext): readonly ScoredEntry[];
+/** Rank entries by cosine similarity between query embedding and stored vectors.
+ *  Pure function — no I/O, no side effects.
+ *
+ *  Entries without vectors are silently skipped — they participate via keyword ranking only.
+ *  Branch filtering applied (recent-work scoped to current branch).
+ *
+ *  @param minSimilarity Minimum cosine similarity to include. Caller provides the
+ *    threshold (SEMANTIC_MIN_SIMILARITY for production, 0 for debug mode to see all scores). */
+export declare function semanticRank(entries: readonly MemoryEntry[], vectors: ReadonlyMap<string, EmbeddingVector>, queryVector: EmbeddingVector, minSimilarity: number, ctx: RankContext): readonly ScoredEntry[];
+/** Merge keyword and semantic ranking results using max-score strategy.
+ *  For each entry: final score = max(keywordScore, semanticScore).
+ *  Entries in both lists get source: 'merged', preserving matchedKeywords from
+ *  keyword result and semanticSimilarity from semantic result.
+ *
+ *  No weighted fusion, no magic constants. Deterministic — same inputs, same output. */
+export declare function mergeRankings(keywordResults: readonly ScoredEntry[], semanticResults: readonly ScoredEntry[]): readonly ScoredEntry[];

package/dist/ranking.js

@@ -0,0 +1,140 @@
+// Domain ranking functions — scoring MemoryEntries using text analysis primitives.
+// Pure functions: no I/O, no side effects, deterministic.
+//
+// Separated from text-analyzer.ts (which works on strings/sets, not domain types)
+// and from store.ts (which handles orchestration and persistence).
+// This module is the ranking pipeline seam for keyword, semantic, and merged ranking.
+import { REFERENCE_BOOST_MULTIPLIER, TAG_MATCH_BOOST, } from './thresholds.js';
+import { extractKeywords, stem, cosineSimilarity } from './text-analyzer.js';
+// ─── Shared helpers ────────────────────────────────────────────────────────
+/** Resolve topic boost for an entry. Falls back to defaultModuleBoost for
+ *  modules/* topics, or 1.0 for unknown topics. */
+function getTopicBoost(topic, ctx) {
+    return ctx.topicBoost[topic] ?? (topic.startsWith('modules/') ? ctx.defaultModuleBoost : 1.0);
+}
+/** Check whether a recent-work entry should be filtered out by branch. */
+function isBranchFiltered(entry, ctx) {
+    return entry.topic === 'recent-work'
+        && ctx.branchFilter !== '*'
+        && !!entry.branch
+        && entry.branch !== ctx.currentBranch;
+}
+// ─── Keyword ranking ───────────────────────────────────────────────────────
+/** Rank entries by keyword overlap with context keywords.
+ *  Pure extraction of the ranking logic from contextSearch — identical scoring.
+ *
+ *  Filter + rank in one pass for efficiency (~200 entries, not worth two iterations).
+ *  Branch filtering for recent-work is applied here because it's a pre-condition
+ *  for ranking, not a separate pipeline stage.
+ *
+ *  Does NOT include the "always include user entries" policy — that's an
+ *  orchestration concern that stays in contextSearch. */
+export function keywordRank(entries, contextKeywords, minMatch, ctx) {
+    const results = [];
+    for (const entry of entries) {
+        if (isBranchFiltered(entry, ctx))
+            continue;
+        // Include tag values as keywords so tagged entries surface in context search
+        const tagKeywordPart = entry.tags ? ` ${entry.tags.join(' ')}` : '';
+        const entryKeywords = extractKeywords(`${entry.title} ${entry.content}${tagKeywordPart}`);
+        const matchedKeywords = [];
+        for (const kw of contextKeywords) {
+            if (entryKeywords.has(kw))
+                matchedKeywords.push(kw);
+        }
+        if (matchedKeywords.length === 0)
+            continue;
+        // Enforce minimum match threshold
+        const matchRatio = matchedKeywords.length / contextKeywords.size;
+        if (matchRatio < minMatch)
+            continue;
+        // Score = keyword match ratio × confidence × topic boost × freshness × reference boost × tag boost
+        const boost = getTopicBoost(entry.topic, ctx);
+        const freshnessMultiplier = ctx.freshEntryIds.has(entry.id) ? 1.0 : 0.7;
+        // Reference boost: exact class/file name match in references gets a 1.3x multiplier
+        const referenceBoost = entry.references?.some(ref => {
+            const basename = ref.split('/').pop()?.replace(/\.\w+$/, '') ?? ref;
+            return contextKeywords.has(stem(basename.toLowerCase()));
+        }) ? REFERENCE_BOOST_MULTIPLIER : 1.0;
+        // Tag boost: if any tag exactly matches a context keyword, boost the entry
+        const tagBoost = entry.tags?.some(tag => contextKeywords.has(tag))
+            ? TAG_MATCH_BOOST : 1.0;
+        const score = matchRatio * entry.confidence * boost * freshnessMultiplier * referenceBoost * tagBoost;
+        results.push({ entry, score, matchedKeywords, source: 'keyword' });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+// ─── Semantic ranking ──────────────────────────────────────────────────────
+/** Rank entries by cosine similarity between query embedding and stored vectors.
+ *  Pure function — no I/O, no side effects.
+ *
+ *  Entries without vectors are silently skipped — they participate via keyword ranking only.
+ *  Branch filtering applied (recent-work scoped to current branch).
+ *
+ *  @param minSimilarity Minimum cosine similarity to include. Caller provides the
+ *    threshold (SEMANTIC_MIN_SIMILARITY for production, 0 for debug mode to see all scores). */
+export function semanticRank(entries, vectors, queryVector, minSimilarity, ctx) {
+    const results = [];
+    for (const entry of entries) {
+        if (isBranchFiltered(entry, ctx))
+            continue;
+        const entryVector = vectors.get(entry.id);
+        if (!entryVector)
+            continue;
+        const similarity = cosineSimilarity(queryVector, entryVector);
+        if (similarity < minSimilarity)
+            continue;
+        // Score = cosine similarity × confidence × topic boost × freshness
+        // No reference/tag boost — those are keyword-domain signals captured by keywordRank
+        const boost = getTopicBoost(entry.topic, ctx);
+        const freshnessMultiplier = ctx.freshEntryIds.has(entry.id) ? 1.0 : 0.7;
+        const score = similarity * entry.confidence * boost * freshnessMultiplier;
+        results.push({
+            entry,
+            score,
+            matchedKeywords: [],
+            source: 'semantic',
+            semanticSimilarity: similarity,
+        });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+// ─── Merge ─────────────────────────────────────────────────────────────────
+/** Merge keyword and semantic ranking results using max-score strategy.
+ *  For each entry: final score = max(keywordScore, semanticScore).
+ *  Entries in both lists get source: 'merged', preserving matchedKeywords from
+ *  keyword result and semanticSimilarity from semantic result.
+ *
+ *  No weighted fusion, no magic constants. Deterministic — same inputs, same output. */
+export function mergeRankings(keywordResults, semanticResults) {
+    // Index keyword results by entry ID for O(1) lookup during merge
+    const keywordById = new Map();
+    for (const r of keywordResults) {
+        keywordById.set(r.entry.id, r);
+    }
+    const merged = new Map();
+    // Process semantic results — check for keyword counterpart
+    for (const sem of semanticResults) {
+        const kw = keywordById.get(sem.entry.id);
+        if (kw) {
+            // Entry in both lists — use max score, merge signals
+            merged.set(sem.entry.id, {
+                entry: sem.entry,
+                score: Math.max(sem.score, kw.score),
+                matchedKeywords: kw.matchedKeywords, // from keyword (semantic has none)
+                source: 'merged',
+                semanticSimilarity: sem.semanticSimilarity, // from semantic
+            });
+            keywordById.delete(sem.entry.id); // consumed
+        }
+        else {
+            // Semantic-only
+            merged.set(sem.entry.id, sem);
+        }
+    }
+    // Remaining keyword-only results
+    for (const kw of keywordById.values()) {
+        merged.set(kw.entry.id, kw);
+    }
+    return Array.from(merged.values()).sort((a, b) => b.score - a.score);
+}

package/dist/store.d.ts

@@ -1,4 +1,5 @@
-import type { MemoryEntry, TopicScope, TrustLevel, DetailLevel, DurabilityDecision, QueryResult, StoreResult, CorrectResult, MemoryStats, BriefingResult, ConflictPair, MemoryConfig } from './types.js';
+import type { MemoryEntry, TopicScope, TrustLevel, DetailLevel, DurabilityDecision, QueryResult, StoreResult, CorrectResult, MemoryStats, ReEmbedResult, BriefingResult, ConflictPair, MemoryConfig } from './types.js';
+import type { ScoredEntry } from './ranking.js';
 export declare class MarkdownMemoryStore {
     private readonly config;
     private readonly memoryPath;
@@ -12,6 +13,14 @@ export declare class MarkdownMemoryStore {
     /** Resolved behavior thresholds — user config merged over defaults.
      *  Centralizes threshold resolution so every caller gets the same value. */
     private get behavior();
+    /** Whether an embedder is configured — for mode indicator display. Read-only. */
+    get hasEmbedder(): boolean;
+    /** Count of vectorized entries — lightweight, no disk reload.
+     *  For mode indicator display. Use stats() for full diagnostics. */
+    get vectorCount(): number;
+    /** Count of total entries — lightweight, no disk reload.
+     *  For mode indicator display. Use stats() for full diagnostics. */
+    get entryCount(): number;
     /** Initialize the store: create memory dir and load existing entries */
     init(): Promise<void>;
     /** Store a new knowledge entry */
@@ -25,17 +34,23 @@ export declare class MarkdownMemoryStore {
     hasEntry(id: string): Promise<boolean>;
     /** Correct an existing entry */
     correct(id: string, correction: string, action: 'append' | 'replace' | 'delete'): Promise<CorrectResult>;
+    /** Re-embed all entries that don't have vectors.
+     *  Idempotent: entries already in the vectors map are skipped.
+     *  Early-exit: if the first embed fails, returns immediately (avoids burning through
+     *  all entries just to discover the embedder is unavailable). */
+    reEmbed(): Promise<ReEmbedResult>;
     /** Get memory health statistics */
     stats(): Promise<MemoryStats>;
     /** Bootstrap: scan repo structure and seed initial knowledge */
     bootstrap(): Promise<StoreResult[]>;
-    /** Search across all topics using keyword matching with topic-based boosting.
+    /** Search across all topics using keyword + semantic ranking with topic-based boosting.
+     *  Orchestrator: reload, extract keywords, embed query, rank, merge, apply policies.
+     *
+     *  Graceful degradation: when embedder is null or embed fails, semantic results
+     *  are empty and merge produces keyword-only results — identical to pre-embedding behavior.
+     *
      *  @param minMatch Minimum ratio of context keywords that must match (0-1, default 0.2) */
-    contextSearch(context: string, maxResults?: number, branchFilter?: string, minMatch?: number): Promise<Array<{
-        entry: MemoryEntry;
-        score: number;
-        matchedKeywords: string[];
-    }>>;
+    contextSearch(context: string, maxResults?: number, branchFilter?: string, minMatch?: number): Promise<readonly ScoredEntry[]>;
     /** Generate a collision-resistant ID: {prefix}-{8 random hex chars} */
     private generateId;
     /** Compute relative file path for an entry within the memory directory */
@@ -93,6 +108,13 @@ export declare class MarkdownMemoryStore {
     /** Find entries in the same topic with significant overlap (dedup detection).
      *  Uses hybrid jaccard+containment similarity. */
     private findRelatedEntries;
+    /** Find semantic duplicates by cosine similarity against stored vectors.
+     *  Same-topic only. Returns entries above DEDUP_SEMANTIC_THRESHOLD.
+     *  Returns empty when no embedder or no vectors available. */
+    private findSemanticDuplicates;
+    /** Merge keyword-based and semantic-based dedup results, dedup by ID,
+     *  keeping the entry with higher similarity score. */
+    private mergeRelatedEntries;
     /** Tag frequency across all entries — for vocabulary echo in store responses.
      *  Returns tags sorted by frequency (descending). O(N) over entries. */
     getTagFrequency(): ReadonlyMap<string, number>;

package/dist/store.js

@@ -7,9 +7,10 @@ import crypto from 'crypto';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { DEFAULT_CONFIDENCE, realClock, parseTopicScope, parseTrustLevel, parseTags, asEmbeddingVector } from './types.js';
-import { DEDUP_SIMILARITY_THRESHOLD, CONFLICT_SIMILARITY_THRESHOLD_SAME_TOPIC, CONFLICT_SIMILARITY_THRESHOLD_CROSS_TOPIC, CONFLICT_MIN_CONTENT_CHARS, OPPOSITION_PAIRS, PREFERENCE_SURFACE_THRESHOLD, REFERENCE_BOOST_MULTIPLIER, TOPIC_BOOST, MODULE_TOPIC_BOOST, USER_ALWAYS_INCLUDE_SCORE_FRACTION, DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, DEFAULT_MAX_PREFERENCE_SUGGESTIONS, TAG_MATCH_BOOST, } from './thresholds.js';
+import { DEDUP_SIMILARITY_THRESHOLD, DEDUP_SEMANTIC_THRESHOLD, SEMANTIC_MIN_SIMILARITY, CONFLICT_SIMILARITY_THRESHOLD_SAME_TOPIC, CONFLICT_SIMILARITY_THRESHOLD_CROSS_TOPIC, CONFLICT_MIN_CONTENT_CHARS, OPPOSITION_PAIRS, PREFERENCE_SURFACE_THRESHOLD, TOPIC_BOOST, MODULE_TOPIC_BOOST, USER_ALWAYS_INCLUDE_SCORE_FRACTION, QUERY_EMBED_TIMEOUT_MS, DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, DEFAULT_MAX_PREFERENCE_SUGGESTIONS, } from './thresholds.js';
 import { realGitService } from './git-service.js';
-import { extractKeywords, stem, similarity, matchesFilter, computeRelevanceScore, } from './text-analyzer.js';
+import { extractKeywords, similarity, cosineSimilarity, matchesFilter, computeRelevanceScore, } from './text-analyzer.js';
+import { keywordRank, semanticRank, mergeRankings } from './ranking.js';
 import { detectEphemeralSignals, formatEphemeralWarning, getEphemeralSeverity } from './ephemeral.js';
 // Used only by bootstrap() for git log — not part of the GitService boundary
 // because bootstrap is a one-shot utility, not a recurring operation
@@ -37,6 +38,20 @@ export class MarkdownMemoryStore {
             maxConflictPairs: b.maxConflictPairs ?? DEFAULT_MAX_CONFLICT_PAIRS,
         };
     }
+    /** Whether an embedder is configured — for mode indicator display. Read-only. */
+    get hasEmbedder() {
+        return this.embedder !== null;
+    }
+    /** Count of vectorized entries — lightweight, no disk reload.
+     *  For mode indicator display. Use stats() for full diagnostics. */
+    get vectorCount() {
+        return this.vectors.size;
+    }
+    /** Count of total entries — lightweight, no disk reload.
+     *  For mode indicator display. Use stats() for full diagnostics. */
+    get entryCount() {
+        return this.entries.size;
+    }
     /** Initialize the store: create memory dir and load existing entries */
     async init() {
         await fs.mkdir(this.memoryPath, { recursive: true });
@@ -101,8 +116,22 @@ export class MarkdownMemoryStore {
         this.entries.set(id, entry);
         const file = this.entryToRelativePath(entry);
         await this.persistEntry(entry);
-        // Dedup: find related entries in the same topic (excluding the one just stored and any overwritten)
-        const relatedEntries = this.findRelatedEntries(entry, existing?.id);
+        // Embed and persist vector — awaited so .vec exists when store() returns
+        if (this.embedder) {
+            const embedText = `${title}\n\n${content}`;
+            const embedResult = await this.embedder.embed(embedText);
+            if (embedResult.ok) {
+                await this.persistVector(file, embedResult.vector);
+                this.vectors.set(entry.id, embedResult.vector);
+            }
+            else {
+                process.stderr.write(`[memory-mcp] Embedding failed for ${entry.id}: ${embedResult.failure.kind}\n`);
+            }
+        }
+        // Dedup: merge keyword-based and semantic-based duplicate detection
+        const keywordDupes = this.findRelatedEntries(entry, existing?.id);
+        const semanticDupes = this.findSemanticDuplicates(entry.id, topic);
+        const relatedEntries = this.mergeRelatedEntries(keywordDupes, semanticDupes);
         // Surface relevant preferences if storing a non-preference entry
         const relevantPreferences = (topic !== 'preferences' && topic !== 'user')
             ? this.findRelevantPreferences(entry)
@@ -306,8 +335,59 @@ export class MarkdownMemoryStore {
         };
         this.entries.set(id, updated);
         await this.persistEntry(updated);
+        // Re-embed: content changed, old vector is stale
+        if (this.embedder) {
+            const embedText = `${updated.title}\n\n${updated.content}`;
+            const embedResult = await this.embedder.embed(embedText);
+            if (embedResult.ok) {
+                const updatedFile = this.entryToRelativePath(updated);
+                await this.persistVector(updatedFile, embedResult.vector);
+                this.vectors.set(updated.id, embedResult.vector);
+            }
+            else {
+                process.stderr.write(`[memory-mcp] Re-embedding failed for ${updated.id}: ${embedResult.failure.kind}\n`);
+            }
+        }
         return { corrected: true, id, action, newConfidence: 1.0, trust: 'user' };
     }
+    /** Re-embed all entries that don't have vectors.
+     *  Idempotent: entries already in the vectors map are skipped.
+     *  Early-exit: if the first embed fails, returns immediately (avoids burning through
+     *  all entries just to discover the embedder is unavailable). */
+    async reEmbed() {
+        if (!this.embedder) {
+            return { embedded: 0, skipped: 0, failed: 0, error: 'No embedder configured' };
+        }
+        await this.reloadFromDisk();
+        // Probe: try embedding a short text to check availability before iterating
+        const probe = await this.embedder.embed('probe');
+        if (!probe.ok) {
+            return { embedded: 0, skipped: 0, failed: 0, error: `Embedder unavailable: ${probe.failure.kind}` };
+        }
+        let embedded = 0;
+        let skipped = 0;
+        let failed = 0;
+        for (const entry of this.entries.values()) {
+            // Entry already has a vector with correct dimensions — skip
+            if (this.vectors.has(entry.id)) {
+                skipped++;
+                continue;
+            }
+            // Embed the entry
+            const embedText = `${entry.title}\n\n${entry.content}`;
+            const result = await this.embedder.embed(embedText);
+            if (result.ok) {
+                const file = this.entryToRelativePath(entry);
+                await this.persistVector(file, result.vector);
+                this.vectors.set(entry.id, result.vector);
+                embedded++;
+            }
+            else {
+                failed++;
+            }
+        }
+        return { embedded, skipped, failed };
+    }
     /** Get memory health statistics */
     async stats() {
         await this.reloadFromDisk();
@@ -340,6 +420,7 @@ export class MarkdownMemoryStore {
         return {
             totalEntries: allEntries.length,
             corruptFiles: this.corruptFileCount,
+            vectorCount: this.vectors.size,
             byTopic, byTrust, byFreshness, byTag,
             storageSize: this.formatBytes(storageSize ?? 0),
             storageBudgetBytes: this.config.storageBudgetBytes,
@@ -417,59 +498,78 @@ export class MarkdownMemoryStore {
         return results;
     }
     // --- Contextual search (memory_context) ---
-    /** Search across all topics using keyword matching with topic-based boosting.
+    /** Search across all topics using keyword + semantic ranking with topic-based boosting.
+     *  Orchestrator: reload, extract keywords, embed query, rank, merge, apply policies.
+     *
+     *  Graceful degradation: when embedder is null or embed fails, semantic results
+     *  are empty and merge produces keyword-only results — identical to pre-embedding behavior.
+     *
      *  @param minMatch Minimum ratio of context keywords that must match (0-1, default 0.2) */
     async contextSearch(context, maxResults = 10, branchFilter, minMatch = 0.2) {
         // Reload from disk to pick up changes from other processes
         await this.reloadFromDisk();
         const contextKeywords = extractKeywords(context);
-        if (contextKeywords.size === 0)
+        // Only bail on zero keywords when there's no embedder to fall back on.
+        // Stopword-heavy queries produce zero keywords but can yield semantic results.
+        if (contextKeywords.size === 0 && !this.embedder)
             return [];
         const currentBranch = branchFilter || await this.getCurrentBranch();
-        // Topic boost factors — higher = more likely to surface
-        const topicBoost = TOPIC_BOOST;
-        const results = [];
-        for (const entry of this.entries.values()) {
-            // Filter recent-work by branch (unless branchFilter is "*")
-            if (entry.topic === 'recent-work' && branchFilter !== '*' && entry.branch && entry.branch !== currentBranch) {
-                continue;
-            }
-            // Include tag values as keywords so tagged entries surface in context search
-            const tagKeywordPart = entry.tags ? ` ${entry.tags.join(' ')}` : '';
-            const entryKeywords = extractKeywords(`${entry.title} ${entry.content}${tagKeywordPart}`);
-            const matchedKeywords = [];
-            for (const kw of contextKeywords) {
-                if (entryKeywords.has(kw))
-                    matchedKeywords.push(kw);
+        const allEntries = Array.from(this.entries.values());
+        // Precompute freshness set — keeps ranking functions provably pure (no callbacks)
+        const freshEntryIds = new Set();
+        for (const entry of allEntries) {
+            if (this.isFresh(entry))
+                freshEntryIds.add(entry.id);
+        }
+        const ctx = {
+            currentBranch,
+            branchFilter,
+            topicBoost: TOPIC_BOOST,
+            freshEntryIds,
+            defaultModuleBoost: MODULE_TOPIC_BOOST,
+        };
+        // Keyword ranking (may be empty for stopword-heavy queries)
+        const keywordResults = contextKeywords.size > 0
+            ? keywordRank(allEntries, contextKeywords, minMatch, ctx)
+            : [];
+        // Semantic ranking (only if embedder available and query embeds successfully)
+        const debug = process.env.MEMORY_MCP_DEBUG === '1';
+        let semanticResults = [];
+        if (this.embedder) {
+            const querySignal = AbortSignal.timeout(QUERY_EMBED_TIMEOUT_MS);
+            const queryResult = await this.embedder.embed(context, querySignal);
+            if (queryResult.ok) {
+                // In debug mode, get ALL scores (threshold=0) for calibration logging
+                const rawSemanticResults = semanticRank(allEntries, this.vectors, queryResult.vector, debug ? 0 : SEMANTIC_MIN_SIMILARITY, ctx);
+                if (debug) {
+                    for (const r of rawSemanticResults) {
+                        const included = (r.semanticSimilarity ?? 0) >= SEMANTIC_MIN_SIMILARITY;
+                        process.stderr.write(`[memory-mcp:debug] semantic ${(r.semanticSimilarity ?? 0).toFixed(3)} ${r.entry.id} "${r.entry.title}"${included ? '' : ' ← below threshold'}\n`);
+                    }
+                    // Filter to threshold after logging all scores
+                    semanticResults = rawSemanticResults.filter(r => (r.semanticSimilarity ?? 0) >= SEMANTIC_MIN_SIMILARITY);
+                }
+                else {
+                    semanticResults = rawSemanticResults;
+                }
             }
-            if (matchedKeywords.length === 0)
-                continue;
-            // Enforce minimum match threshold
-            const matchRatio = matchedKeywords.length / contextKeywords.size;
-            if (matchRatio < minMatch)
-                continue;
-            // Score = keyword match ratio x confidence x topic boost x reference boost
-            const boost = topicBoost[entry.topic] ?? (entry.topic.startsWith('modules/') ? MODULE_TOPIC_BOOST : 1.0);
-            const freshnessMultiplier = this.isFresh(entry) ? 1.0 : 0.7;
-            // Reference boost: exact class/file name match in references gets a 1.3x multiplier.
-            // Extracts the basename (without extension) from each reference path and stems it,
-            // then checks for overlap with the context keywords.
-            const referenceBoost = entry.references?.some(ref => {
-                const basename = ref.split('/').pop()?.replace(/\.\w+$/, '') ?? ref;
-                return contextKeywords.has(stem(basename.toLowerCase()));
-            }) ? REFERENCE_BOOST_MULTIPLIER : 1.0;
-            // Tag boost: if any tag exactly matches a context keyword, boost the entry
-            const tagBoost = entry.tags?.some(tag => contextKeywords.has(tag))
-                ? TAG_MATCH_BOOST : 1.0;
-            const score = matchRatio * entry.confidence * boost * freshnessMultiplier * referenceBoost * tagBoost;
-            results.push({ entry, score, matchedKeywords });
+            // If embed fails: semanticResults stays empty, keyword results used alone
         }
-        // Always include user entries even if no keyword match (they're always relevant)
+        // Merge keyword + semantic results using max-score strategy
+        const merged = mergeRankings(keywordResults, semanticResults);
+        // Policy: always include user entries even if no keyword/semantic match
+        const results = [...merged];
         for (const entry of this.entries.values()) {
             if (entry.topic === 'user' && !results.find(r => r.entry.id === entry.id)) {
-                results.push({ entry, score: entry.confidence * USER_ALWAYS_INCLUDE_SCORE_FRACTION, matchedKeywords: [] });
+                results.push({
+                    entry,
+                    score: entry.confidence * USER_ALWAYS_INCLUDE_SCORE_FRACTION,
+                    matchedKeywords: [],
+                    source: 'keyword',
+                });
             }
         }
+        // Re-sort after policy injections to maintain score-descending invariant
         return results
             .sort((a, b) => b.score - a.score)
             .slice(0, maxResults);
@@ -914,6 +1014,51 @@ export class MarkdownMemoryStore {
             trust: r.entry.trust,
         }));
     }
+    /** Find semantic duplicates by cosine similarity against stored vectors.
+     *  Same-topic only. Returns entries above DEDUP_SEMANTIC_THRESHOLD.
+     *  Returns empty when no embedder or no vectors available. */
+    findSemanticDuplicates(excludeId, topic) {
+        const newVector = this.vectors.get(excludeId);
+        if (!newVector)
+            return [];
+        const related = [];
+        for (const entry of this.entries.values()) {
+            if (entry.id === excludeId)
+                continue;
+            if (entry.topic !== topic)
+                continue;
+            const entryVector = this.vectors.get(entry.id);
+            if (!entryVector)
+                continue;
+            const sim = cosineSimilarity(newVector, entryVector);
+            if (sim > DEDUP_SEMANTIC_THRESHOLD) {
+                related.push({ entry, similarity: sim });
+            }
+        }
+        return related
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, this.behavior.maxDedupSuggestions)
+            .map(r => ({
+            id: r.entry.id,
+            title: r.entry.title,
+            content: r.entry.content,
+            confidence: r.entry.confidence,
+            trust: r.entry.trust,
+        }));
+    }
+    /** Merge keyword-based and semantic-based dedup results, dedup by ID,
+     *  keeping the entry with higher similarity score. */
+    mergeRelatedEntries(keywordDupes, semanticDupes) {
+        const byId = new Map();
+        for (const r of keywordDupes)
+            byId.set(r.id, r);
+        for (const r of semanticDupes) {
+            if (!byId.has(r.id))
+                byId.set(r.id, r);
+            // If already present from keyword dedup, keep whichever — both indicate duplication
+        }
+        return Array.from(byId.values()).slice(0, this.behavior.maxDedupSuggestions);
+    }
     /** Tag frequency across all entries — for vocabulary echo in store responses.
      *  Returns tags sorted by frequency (descending). O(N) over entries. */
     getTagFrequency() {

package/dist/thresholds.d.ts

@@ -14,6 +14,26 @@ export declare const CONFLICT_MIN_CONTENT_CHARS = 50;
 /** Opposition keyword pairs for enhanced conflict detection.
  *  When entries overlap AND use opposing terms, boost the conflict signal. */
 export declare const OPPOSITION_PAIRS: ReadonlyArray<readonly [string, string]>;
+/** Minimum cosine similarity for semantic search results.
+ *  Below this, entries are noise — embedding models produce non-zero similarity
+ *  even for unrelated text.
+ *
+ *  CALIBRATION NOTE: 0.45 is a strict starting point. With nomic-embed-text,
+ *  unrelated text pairs routinely score 0.2-0.4 because the model produces
+ *  non-orthogonal embeddings for any English text. Starting strict and loosening
+ *  with data is safer than starting loose.
+ *
+ *  Use MEMORY_MCP_DEBUG=1 env var to see raw cosine scores for calibration. */
+export declare const SEMANTIC_MIN_SIMILARITY = 0.45;
+/** Minimum cosine similarity for semantic dedup at store time.
+ *  Higher than SEMANTIC_MIN_SIMILARITY because flagging false duplicates is more
+ *  disruptive than missing real ones. Two entries must be quite similar to be
+ *  flagged as potential duplicates. */
+export declare const DEDUP_SEMANTIC_THRESHOLD = 0.8;
+/** Query-time embed timeout — tighter than store-time (5s) for responsiveness.
+ *  Model-warm latency is ~10ms; 2s covers machine-under-load with margin.
+ *  Cold starts handled by LazyEmbedder's probe (which uses the full 5s). */
+export declare const QUERY_EMBED_TIMEOUT_MS = 2000;
 /** Score multiplier when a reference path basename matches the context keywords. */
 export declare const REFERENCE_BOOST_MULTIPLIER = 1.3;
 /** Per-topic scoring boost factors for contextSearch().

package/dist/thresholds.js

@@ -40,6 +40,26 @@ export const OPPOSITION_PAIRS = [
     ['throw', 'return'], // exceptions vs Result types
     ['imperative', 'declarative'],
 ];
+/** Minimum cosine similarity for semantic search results.
+ *  Below this, entries are noise — embedding models produce non-zero similarity
+ *  even for unrelated text.
+ *
+ *  CALIBRATION NOTE: 0.45 is a strict starting point. With nomic-embed-text,
+ *  unrelated text pairs routinely score 0.2-0.4 because the model produces
+ *  non-orthogonal embeddings for any English text. Starting strict and loosening
+ *  with data is safer than starting loose.
+ *
+ *  Use MEMORY_MCP_DEBUG=1 env var to see raw cosine scores for calibration. */
+export const SEMANTIC_MIN_SIMILARITY = 0.45;
+/** Minimum cosine similarity for semantic dedup at store time.
+ *  Higher than SEMANTIC_MIN_SIMILARITY because flagging false duplicates is more
+ *  disruptive than missing real ones. Two entries must be quite similar to be
+ *  flagged as potential duplicates. */
+export const DEDUP_SEMANTIC_THRESHOLD = 0.80;
+/** Query-time embed timeout — tighter than store-time (5s) for responsiveness.
+ *  Model-warm latency is ~10ms; 2s covers machine-under-load with margin.
+ *  Cold starts handled by LazyEmbedder's probe (which uses the full 5s). */
+export const QUERY_EMBED_TIMEOUT_MS = 2000;
 /** Score multiplier when a reference path basename matches the context keywords. */
 export const REFERENCE_BOOST_MULTIPLIER = 1.30;
 /** Per-topic scoring boost factors for contextSearch().

package/dist/types.d.ts

@@ -156,6 +156,7 @@ export type CorrectResult = {
 export interface MemoryStats {
     readonly totalEntries: number;
     readonly corruptFiles: number;
+    readonly vectorCount: number;
     readonly byTopic: Record<string, number>;
     readonly byTrust: Record<TrustLevel, number>;
     readonly byFreshness: {
@@ -222,6 +223,24 @@ export interface BehaviorConfig {
     /** Maximum conflict pairs shown per query/context response. Default: 2. Range: 1–5. */
     readonly maxConflictPairs?: number;
 }
+/** Supported embedding providers — closed union for exhaustive handling. */
+export type EmbedderProvider = 'ollama' | 'none';
+/** Embedding configuration from memory-config.json "embedder" block.
+ *  All fields optional except provider — defaults are sensible for nomic-embed-text on localhost. */
+export interface EmbedderConfig {
+    readonly provider: EmbedderProvider;
+    readonly model?: string;
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly dimensions?: number;
+}
+/** Result of a re-embed operation */
+export interface ReEmbedResult {
+    readonly embedded: number;
+    readonly skipped: number;
+    readonly failed: number;
+    readonly error?: string;
+}
 /** Configuration for the memory MCP */
 export interface MemoryConfig {
     readonly repoRoot: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/memory-mcp",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Codebase memory MCP server - persistent, evolving knowledge for AI coding agents",
   "type": "module",
   "main": "dist/index.js",