@exaudeus/memory-mcp 1.5.2 → 1.7.0

package/dist/embedder.d.ts

@@ -0,0 +1,66 @@
+import type { EmbeddingVector } from './types.js';
+/** Why embedding failed — discriminated union for observability.
+ *  The store doesn't branch on the reason (always falls back to keywords),
+ *  but structured errors enable logging and diagnostics. */
+export type EmbedFailure = {
+    readonly kind: 'provider-unavailable';
+    readonly reason: string;
+} | {
+    readonly kind: 'timeout';
+    readonly ms: number;
+} | {
+    readonly kind: 'invalid-input';
+    readonly reason: string;
+};
+/** Embedding outcome — success carries the vector, failure carries structured diagnostics.
+ *  Matches the StoreResult/CorrectResult pattern from types.ts. */
+export type EmbedResult = {
+    readonly ok: true;
+    readonly vector: EmbeddingVector;
+} | {
+    readonly ok: false;
+    readonly failure: EmbedFailure;
+};
+/** Embedding provider boundary — injected into the store.
+ *  Implementations: OllamaEmbedder (production), FakeEmbedder (tests).
+ *
+ *  Minimal interface: one method + one property.
+ *  No isAvailable() — redundant with embed() returning a failure.
+ *  No embedBatch() — interface segregation; batch is a standalone utility. */
+export interface Embedder {
+    embed(text: string, signal?: AbortSignal): Promise<EmbedResult>;
+    readonly dimensions: number;
+}
+/** Production embedder using local Ollama instance.
+ *  Uses node:http directly — no external dependencies. */
+export declare class OllamaEmbedder implements Embedder {
+    readonly dimensions: number;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(opts?: {
+        readonly model?: string;
+        readonly baseUrl?: string;
+        readonly timeoutMs?: number;
+        readonly dimensions?: number;
+    });
+    embed(text: string, signal?: AbortSignal): Promise<EmbedResult>;
+}
+/** Deterministic embedder for testing — uses character trigram frequency to produce
+ *  a fixed-dimension vector from input text. Same text → same vector. Similar texts
+ *  → high cosine similarity. Dissimilar texts → low cosine similarity.
+ *
+ *  Limitation: models *string* similarity, not *semantic* similarity.
+ *  "async workflows" and "asynchronous work patterns" score low despite being
+ *  semantically identical. FakeEmbedder tests prove pipeline mechanics (merge,
+ *  degradation, round-trip). Real semantic ordering is tested separately with
+ *  fixture vectors from nomic-embed-text. */
+export declare class FakeEmbedder implements Embedder {
+    readonly dimensions: number;
+    constructor(dimensions?: 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. */
+export declare function batchEmbed(embedder: Embedder, texts: readonly string[]): Promise<ReadonlyArray<EmbedResult>>;

package/dist/embedder.js

@@ -0,0 +1,204 @@
+// Embedding provider boundary — the only seam that touches embedding infrastructure.
+// Injected into the store for testability; FakeEmbedder for tests, OllamaEmbedder for production.
+//
+// Design:
+//   - Errors are data: EmbedResult discriminated union, never throws
+//   - Small interface: one method + one property. Batch is a standalone utility.
+//   - Cancellation first-class: AbortSignal propagated through embed()
+//   - Graceful degradation: embed failure → keyword-only search, never a crash
+import http from 'node:http';
+import { asEmbeddingVector } from './types.js';
+// ─── OllamaEmbedder ───────────────────────────────────────────────────────
+/** Default timeout for embed calls — generous for cold model loads */
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Production embedder using local Ollama instance.
+ *  Uses node:http directly — no external dependencies. */
+export class OllamaEmbedder {
+    constructor(opts) {
+        this.model = opts?.model ?? 'nomic-embed-text';
+        this.baseUrl = opts?.baseUrl ?? 'http://localhost:11434';
+        this.timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.dimensions = opts?.dimensions ?? 384;
+    }
+    async embed(text, signal) {
+        // Validate at boundary — no HTTP call wasted on empty input
+        const trimmed = text.trim();
+        if (!trimmed) {
+            return { ok: false, failure: { kind: 'invalid-input', reason: 'empty text' } };
+        }
+        // Compose caller's signal with internal timeout
+        const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+        const combinedSignal = signal
+            ? AbortSignal.any([signal, timeoutSignal])
+            : timeoutSignal;
+        const body = JSON.stringify({ model: this.model, prompt: trimmed });
+        const url = new URL('/api/embeddings', this.baseUrl);
+        const httpResult = await httpPost(url, body, combinedSignal);
+        // HTTP layer failed — map to embed failure
+        if (!httpResult.ok) {
+            if (httpResult.failure === 'aborted') {
+                return { ok: false, failure: { kind: 'timeout', ms: this.timeoutMs } };
+            }
+            return { ok: false, failure: { kind: 'provider-unavailable', reason: httpResult.failure } };
+        }
+        const response = httpResult.body;
+        // Validate response shape — Ollama returns { embedding: number[] }
+        if (!response.embedding || !Array.isArray(response.embedding)) {
+            return {
+                ok: false,
+                failure: { kind: 'provider-unavailable', reason: 'unexpected response format — missing embedding array' },
+            };
+        }
+        // Validate array contents — coercion to Float32Array silently produces NaN for non-numbers
+        if (response.embedding.length > 0 && typeof response.embedding[0] !== 'number') {
+            return {
+                ok: false,
+                failure: { kind: 'provider-unavailable', reason: 'embedding array contains non-numeric values' },
+            };
+        }
+        const vector = asEmbeddingVector(new Float32Array(response.embedding));
+        // Dimension sanity check — catches model mismatch at boundary
+        if (vector.length !== this.dimensions) {
+            return {
+                ok: false,
+                failure: {
+                    kind: 'provider-unavailable',
+                    reason: `dimension mismatch: expected ${this.dimensions}, got ${vector.length}`,
+                },
+            };
+        }
+        return { ok: true, vector };
+    }
+}
+// ─── FakeEmbedder ─────────────────────────────────────────────────────────
+/** Deterministic embedder for testing — uses character trigram frequency to produce
+ *  a fixed-dimension vector from input text. Same text → same vector. Similar texts
+ *  → high cosine similarity. Dissimilar texts → low cosine similarity.
+ *
+ *  Limitation: models *string* similarity, not *semantic* similarity.
+ *  "async workflows" and "asynchronous work patterns" score low despite being
+ *  semantically identical. FakeEmbedder tests prove pipeline mechanics (merge,
+ *  degradation, round-trip). Real semantic ordering is tested separately with
+ *  fixture vectors from nomic-embed-text. */
+export class FakeEmbedder {
+    constructor(dimensions = 384) {
+        this.dimensions = dimensions;
+    }
+    async embed(text, _signal) {
+        const trimmed = text.trim();
+        if (!trimmed) {
+            return { ok: false, failure: { kind: 'invalid-input', reason: 'empty text' } };
+        }
+        const vector = trigramVector(trimmed, this.dimensions);
+        return { ok: true, vector };
+    }
+}
+/** Produce a deterministic vector from text using character trigram frequency.
+ *  Each trigram hashes to a bucket (dimension index). The resulting vector is
+ *  L2-normalized so cosine similarity between two vectors is meaningful.
+ *
+ *  Pure function — no side effects, deterministic. */
+function trigramVector(text, dimensions) {
+    const normalized = text.toLowerCase();
+    const raw = new Float32Array(dimensions);
+    // Accumulate trigram counts into dimension buckets
+    for (let i = 0; i <= normalized.length - 3; i++) {
+        const trigram = normalized.substring(i, i + 3);
+        const bucket = trigramHash(trigram, dimensions);
+        raw[bucket] += 1;
+    }
+    // L2 normalize — cosine similarity requires unit-length or at least
+    // consistent normalization to be meaningful
+    let norm = 0;
+    for (let i = 0; i < dimensions; i++) {
+        norm += raw[i] * raw[i];
+    }
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let i = 0; i < dimensions; i++) {
+            raw[i] /= norm;
+        }
+    }
+    return asEmbeddingVector(raw);
+}
+/** Simple hash of a trigram string to a bucket index.
+ *  Deterministic: same trigram always maps to the same bucket. */
+function trigramHash(trigram, buckets) {
+    let hash = 0;
+    for (let i = 0; i < trigram.length; i++) {
+        hash = ((hash << 5) - hash + trigram.charCodeAt(i)) | 0;
+    }
+    return ((hash % buckets) + buckets) % buckets;
+}
+// ─── Batch utility ────────────────────────────────────────────────────────
+/** 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. */
+export async function batchEmbed(embedder, texts) {
+    const results = [];
+    for (const text of texts) {
+        results.push(await embedder.embed(text));
+    }
+    return results;
+}
+/** Minimal HTTP POST using node:http — returns a result type, never throws.
+ *  No external dependencies — the Ollama API is simple enough for raw HTTP.
+ *
+ *  Uses a settled guard to prevent double-resolution when abort races with
+ *  a network error (req.destroy triggers error handler alongside abort handler). */
+function httpPost(url, body, signal) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            resolve(result);
+        };
+        // Already aborted before we start — fail fast
+        if (signal.aborted) {
+            resolve({ ok: false, failure: 'aborted' });
+            return;
+        }
+        const onAbort = () => {
+            req.destroy();
+            settle({ ok: false, failure: 'aborted' });
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        const req = http.request({
+            hostname: url.hostname,
+            port: url.port || 80,
+            path: url.pathname,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const raw = Buffer.concat(chunks).toString('utf-8');
+                if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                    settle({ ok: false, failure: `HTTP ${res.statusCode}: ${raw.slice(0, 200)}` });
+                    return;
+                }
+                try {
+                    settle({ ok: true, body: JSON.parse(raw) });
+                }
+                catch {
+                    settle({ ok: false, failure: `invalid JSON response: ${raw.slice(0, 200)}` });
+                }
+            });
+            res.on('error', (err) => {
+                settle({ ok: false, failure: err.message });
+            });
+        });
+        req.on('error', (err) => {
+            settle({ ok: false, failure: err.message });
+        });
+        req.write(body);
+        req.end();
+    });
+}

package/dist/index.js

@@ -909,6 +909,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;

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,10 +1,13 @@
 import type { MemoryEntry, TopicScope, TrustLevel, DetailLevel, DurabilityDecision, QueryResult, StoreResult, CorrectResult, MemoryStats, BriefingResult, ConflictPair, MemoryConfig } from './types.js';
+import type { ScoredEntry } from './ranking.js';
 export declare class MarkdownMemoryStore {
     private readonly config;
     private readonly memoryPath;
     private readonly clock;
     private readonly git;
+    private readonly embedder;
     private entries;
+    private vectors;
     private corruptFileCount;
     constructor(config: MemoryConfig);
     /** Resolved behavior thresholds — user config merged over defaults.
@@ -27,13 +30,14 @@ export declare class MarkdownMemoryStore {
     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 */
@@ -46,6 +50,26 @@ export declare class MarkdownMemoryStore {
     private persistEntry;
     /** Delete the file for an entry */
     private deleteEntryFile;
+    /** .vec file format version — future-proofs for metadata additions.
+     *  v1: [u8 version=0x01][u32LE dimensions][f32LE × dimensions] */
+    private static readonly VEC_FORMAT_VERSION;
+    /** Write a vector sidecar file for an entry.
+     *  Format: [u8 version][u32LE dims][f32LE × dims]. Total: 5 + dims*4 bytes. */
+    private persistVector;
+    /** Load and validate a vector sidecar file.
+     *  Returns null on: missing file, unknown version, wrong dimensions, corrupt size.
+     *  Null is not an error — it means the entry works via keyword fallback. */
+    private loadVector;
+    /** Delete a vector sidecar file. Fire-and-forget — failure is harmless. */
+    private deleteVector;
+    /** Derive the .vec path from a .md relative path */
+    private vecPathFromMdPath;
+    /** Load vectors for all known entries. Cleans up orphan .vec files.
+     *  Skipped entirely when embedder is null (no wasted I/O).
+     *  Returns a fresh map — no mutation of store state. */
+    private loadVectorSnapshot;
+    /** Recursively find all .vec files in a directory */
+    private findVecFiles;
     /** Load all entries from disk and return as an immutable snapshot.
      *  Pure read — no mutation. Callers decide whether to cache.
      *  Tracks corrupt files for observability without failing the load. */
@@ -71,6 +95,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

@@ -6,10 +6,11 @@ import path from 'path';
 import crypto from 'crypto';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { DEFAULT_CONFIDENCE, realClock, parseTopicScope, parseTrustLevel, parseTags } 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 { DEFAULT_CONFIDENCE, realClock, parseTopicScope, parseTrustLevel, parseTags, asEmbeddingVector } from './types.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, 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
@@ -17,11 +18,13 @@ const execFileAsync = promisify(execFile);
 export class MarkdownMemoryStore {
     constructor(config) {
         this.entries = new Map();
+        this.vectors = new Map();
         this.corruptFileCount = 0;
         this.config = config;
         this.memoryPath = config.memoryPath;
         this.clock = config.clock ?? realClock;
         this.git = config.git ?? realGitService;
+        this.embedder = config.embedder ?? null;
     }
     /** Resolved behavior thresholds — user config merged over defaults.
      *  Centralizes threshold resolution so every caller gets the same value. */
@@ -99,8 +102,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)
@@ -304,6 +321,19 @@ 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' };
     }
     /** Get memory health statistics */
@@ -415,59 +445,77 @@ 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 queryResult = await this.embedder.embed(context);
+            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 });
-        }
-        // Always include user entries even if no keyword match (they're always relevant)
+            // If embed fails: semanticResults stays empty, keyword results used alone
+        }
+        // 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);
@@ -544,6 +592,8 @@ export class MarkdownMemoryStore {
             await fs.unlink(fullPath);
         }
         catch { /* already gone */ }
+        // Delete companion .vec file if it exists
+        await this.deleteVector(relativePath);
         // Clean up empty parent directories
         try {
             const dir = path.dirname(fullPath);
@@ -554,6 +604,128 @@ export class MarkdownMemoryStore {
         }
         catch { /* ignore */ }
     }
+    /** Write a vector sidecar file for an entry.
+     *  Format: [u8 version][u32LE dims][f32LE × dims]. Total: 5 + dims*4 bytes. */
+    async persistVector(relativePath, vector) {
+        const vecPath = this.vecPathFromMdPath(relativePath);
+        const buf = Buffer.alloc(5 + vector.length * 4);
+        buf.writeUInt8(MarkdownMemoryStore.VEC_FORMAT_VERSION, 0);
+        buf.writeUInt32LE(vector.length, 1);
+        for (let i = 0; i < vector.length; i++) {
+            buf.writeFloatLE(vector[i], 5 + i * 4);
+        }
+        await fs.mkdir(path.dirname(vecPath), { recursive: true });
+        await fs.writeFile(vecPath, buf);
+    }
+    /** Load and validate a vector sidecar file.
+     *  Returns null on: missing file, unknown version, wrong dimensions, corrupt size.
+     *  Null is not an error — it means the entry works via keyword fallback. */
+    async loadVector(relativePath) {
+        if (!this.embedder)
+            return null;
+        const vecPath = this.vecPathFromMdPath(relativePath);
+        let buf;
+        try {
+            buf = await fs.readFile(vecPath);
+        }
+        catch {
+            return null; // missing — entry predates embeddings
+        }
+        // Minimum valid size: 1 (version) + 4 (dims) = 5 bytes
+        if (buf.length < 5) {
+            process.stderr.write(`[memory-mcp] Corrupt .vec file (too small): ${vecPath}\n`);
+            return null;
+        }
+        const version = buf.readUInt8(0);
+        if (version !== MarkdownMemoryStore.VEC_FORMAT_VERSION) {
+            process.stderr.write(`[memory-mcp] Unknown .vec version ${version}: ${vecPath}\n`);
+            return null;
+        }
+        const storedDims = buf.readUInt32LE(1);
+        if (storedDims !== this.embedder.dimensions) {
+            // Dimension mismatch — model changed. Entry needs re-embed, not an error.
+            process.stderr.write(`[memory-mcp] Dimension mismatch in ${vecPath}: stored ${storedDims}, expected ${this.embedder.dimensions}\n`);
+            return null;
+        }
+        const expectedSize = 5 + storedDims * 4;
+        if (buf.length !== expectedSize) {
+            process.stderr.write(`[memory-mcp] Corrupt .vec file (expected ${expectedSize} bytes, got ${buf.length}): ${vecPath}\n`);
+            return null;
+        }
+        const raw = new Float32Array(storedDims);
+        for (let i = 0; i < storedDims; i++) {
+            raw[i] = buf.readFloatLE(5 + i * 4);
+        }
+        return asEmbeddingVector(raw);
+    }
+    /** Delete a vector sidecar file. Fire-and-forget — failure is harmless. */
+    async deleteVector(mdRelativePath) {
+        const vecPath = this.vecPathFromMdPath(mdRelativePath);
+        try {
+            await fs.unlink(vecPath);
+        }
+        catch { /* already gone or never existed */ }
+    }
+    /** Derive the .vec path from a .md relative path */
+    vecPathFromMdPath(mdRelativePath) {
+        const vecRelative = mdRelativePath.replace(/\.md$/, '.vec');
+        return path.join(this.memoryPath, vecRelative);
+    }
+    /** Load vectors for all known entries. Cleans up orphan .vec files.
+     *  Skipped entirely when embedder is null (no wasted I/O).
+     *  Returns a fresh map — no mutation of store state. */
+    async loadVectorSnapshot(entries) {
+        if (!this.embedder)
+            return new Map();
+        const vectors = new Map();
+        const entryIds = new Set(entries.keys());
+        // Load vectors for known entries
+        for (const entry of entries.values()) {
+            const relativePath = this.entryToRelativePath(entry);
+            const vector = await this.loadVector(relativePath);
+            if (vector) {
+                vectors.set(entry.id, vector);
+            }
+        }
+        // Clean up orphan .vec files — entries deleted while embedder was unavailable
+        try {
+            const vecFiles = await this.findVecFiles(this.memoryPath);
+            for (const vecFile of vecFiles) {
+                const relativePath = path.relative(this.memoryPath, vecFile);
+                // Derive the entry ID: the .vec filename without extension matches the .md filename
+                const mdRelative = relativePath.replace(/\.vec$/, '.md');
+                // Check if any entry maps to this path
+                const hasMatchingEntry = Array.from(entries.values()).some(e => this.entryToRelativePath(e) === mdRelative);
+                if (!hasMatchingEntry) {
+                    try {
+                        await fs.unlink(vecFile);
+                        process.stderr.write(`[memory-mcp] Cleaned up orphan .vec: ${relativePath}\n`);
+                    }
+                    catch { /* ignore cleanup failures */ }
+                }
+            }
+        }
+        catch { /* ignore — directory may not exist yet */ }
+        return vectors;
+    }
+    /** Recursively find all .vec files in a directory */
+    async findVecFiles(dir) {
+        const results = [];
+        try {
+            const dirEntries = await fs.readdir(dir, { withFileTypes: true });
+            for (const dirEntry of dirEntries) {
+                const fullPath = path.join(dir, dirEntry.name);
+                if (dirEntry.isDirectory()) {
+                    results.push(...await this.findVecFiles(fullPath));
+                }
+                else if (dirEntry.name.endsWith('.vec')) {
+                    results.push(fullPath);
+                }
+            }
+        }
+        catch { /* ignore */ }
+        return results;
+    }
     /** Load all entries from disk and return as an immutable snapshot.
      *  Pure read — no mutation. Callers decide whether to cache.
      *  Tracks corrupt files for observability without failing the load. */
@@ -576,13 +748,16 @@ export class MarkdownMemoryStore {
         catch {
             // Empty memory — first run
         }
-        return { entries, corruptFileCount };
+        // Load vectors after entries — needs the entry map for orphan detection
+        const vectors = await this.loadVectorSnapshot(entries);
+        return { entries, vectors, corruptFileCount };
     }
     /** Reload entries from disk into the store's working state.
      *  This is the single mutation point for disk reads. */
     async reloadFromDisk() {
         const snapshot = await this.loadSnapshot();
         this.entries = new Map(snapshot.entries);
+        this.vectors = new Map(snapshot.vectors);
         this.corruptFileCount = snapshot.corruptFileCount;
     }
     /** Recursively find all .md files in a directory */
@@ -785,6 +960,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() {
@@ -889,3 +1109,10 @@ export class MarkdownMemoryStore {
         }));
     }
 }
+// ─── Vector sidecar storage ─────────────────────────────────────────────
+// Sidecar .vec files alongside .md entries. Embeddings are a cache — delete
+// all .vec files and the system degrades to keyword search. Non-atomic with
+// .md writes (both failure modes are benign since vectors are derived data).
+/** .vec file format version — future-proofs for metadata additions.
+ *  v1: [u8 version=0x01][u32LE dimensions][f32LE × dimensions] */
+MarkdownMemoryStore.VEC_FORMAT_VERSION = 0x01;

package/dist/text-analyzer.d.ts

@@ -1,3 +1,4 @@
+import type { EmbeddingVector } from './types.js';
 /** Parsed filter group: required, excluded, exact-match, and tag terms */
 export interface FilterGroup {
     readonly must: Set<string>;
@@ -36,6 +37,12 @@ export declare function jaccardSimilarity(a: Set<string>, b: Set<string>): numbe
 /** Containment similarity: |intersection| / min(|a|, |b|)
  *  Catches when one entry is a subset of a larger one */
 export declare function containmentSimilarity(a: Set<string>, b: Set<string>): number;
+/** Cosine similarity between two embedding vectors.
+ *  Returns 0.0–1.0 for normalized vectors (most embedding models normalize output).
+ *  Returns 0 for zero vectors (not NaN) — no information means no similarity.
+ *
+ *  Pure function. No allocations beyond locals. ~1ms for 200 entries at 384 dims. */
+export declare function cosineSimilarity(a: EmbeddingVector, b: EmbeddingVector): number;
 /** Combined similarity: max(jaccard, containment) with title boost.
  *  Title keywords get double weight by being included twice. */
 export declare function similarity(titleA: string, contentA: string, titleB: string, contentB: string): number;

package/dist/text-analyzer.js

@@ -1,10 +1,10 @@
 // Pure text analysis: stemming, keyword extraction, similarity, filter parsing.
 // Stateless — all functions are pure. No I/O, no side effects.
 //
-// Design: this module is the seam for future search strategies.
+// Design: this module is the seam for search strategies.
 // v1: keyword matching with naive stemming (this file)
-// v2: spreading activation over a knowledge graph
-// v3: embedding-based cosine similarity
+// v2: embedding-based cosine similarity (this file + embedder.ts)
+// v3: graph-enriched retrieval (if proven needed — see graph-library-design.md)
 // Stopwords for keyword extraction — common English words with no semantic value
 const STOPWORDS = new Set([
     'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
@@ -139,6 +139,21 @@ export function containmentSimilarity(a, b) {
     }
     return intersection / Math.min(a.size, b.size);
 }
+/** Cosine similarity between two embedding vectors.
+ *  Returns 0.0–1.0 for normalized vectors (most embedding models normalize output).
+ *  Returns 0 for zero vectors (not NaN) — no information means no similarity.
+ *
+ *  Pure function. No allocations beyond locals. ~1ms for 200 entries at 384 dims. */
+export function cosineSimilarity(a, b) {
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
 /** Combined similarity: max(jaccard, containment) with title boost.
  *  Title keywords get double weight by being included twice. */
 export function similarity(titleA, contentA, titleB, contentB) {

package/dist/thresholds.d.ts

@@ -14,6 +14,22 @@ 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;
 /** 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,22 @@ 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;
 /** 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

@@ -1,3 +1,4 @@
+import type { Embedder } from './embedder.js';
 /** Trust levels for knowledge sources, ordered by reliability */
 export type TrustLevel = 'user' | 'agent-confirmed' | 'agent-inferred';
 /** Ephemeral detection severity — three distinct levels so consumers can branch exhaustively.
@@ -12,6 +13,16 @@ export type TopicScope = 'user' | 'preferences' | 'architecture' | 'conventions'
 export type Tag = string & {
     readonly __brand: 'Tag';
 };
+/** Embedding vector — branded Float32Array to prevent passing arbitrary float arrays.
+ *  The brand carries domain intent: this is a valid embedding from a specific model,
+ *  not an arbitrary numeric buffer. Decoupled from embedder.ts so text-analyzer.ts
+ *  can import it without depending on the embedding provider. */
+export type EmbeddingVector = Float32Array & {
+    readonly __brand: 'EmbeddingVector';
+};
+/** Construct an EmbeddingVector from a Float32Array. Boundary validation only —
+ *  callers (OllamaEmbedder, FakeEmbedder, vector deserialization) validate dimensions. */
+export declare function asEmbeddingVector(raw: Float32Array): EmbeddingVector;
 /** Parse a raw string into a Tag, returning null for invalid input.
  *  Normalizes to lowercase. Rejects empty, too-long, or non-slug strings. */
 export declare function parseTag(raw: string): Tag | null;
@@ -220,6 +231,7 @@ export interface MemoryConfig {
     readonly behavior?: BehaviorConfig;
     readonly clock?: Clock;
     readonly git?: GitService;
+    readonly embedder?: Embedder;
 }
 /** Default confidence values by trust level */
 export declare const DEFAULT_CONFIDENCE: Record<TrustLevel, number>;

package/dist/types.js

@@ -10,6 +10,11 @@ export function parseTrustLevel(raw) {
     return TRUST_LEVELS.includes(raw) ? raw : null;
 }
 const FIXED_TOPICS = ['user', 'preferences', 'architecture', 'conventions', 'gotchas', 'recent-work'];
+/** Construct an EmbeddingVector from a Float32Array. Boundary validation only —
+ *  callers (OllamaEmbedder, FakeEmbedder, vector deserialization) validate dimensions. */
+export function asEmbeddingVector(raw) {
+    return raw;
+}
 const TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const MAX_TAG_LENGTH = 50;
 const MAX_TAGS_PER_ENTRY = 10;

package/package.json

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