@exaudeus/memory-mcp 1.7.0 → 1.9.0

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-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;
@@ -13,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 */
@@ -26,6 +34,11 @@ 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 */

package/dist/store.js

@@ -7,7 +7,7 @@ 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, 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 { 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, similarity, cosineSimilarity, matchesFilter, computeRelevanceScore, } from './text-analyzer.js';
 import { keywordRank, semanticRank, mergeRankings } from './ranking.js';
@@ -38,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 });
@@ -336,6 +350,44 @@ export class MarkdownMemoryStore {
         }
         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();
@@ -368,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,
@@ -483,7 +536,8 @@ export class MarkdownMemoryStore {
         const debug = process.env.MEMORY_MCP_DEBUG === '1';
         let semanticResults = [];
         if (this.embedder) {
-            const queryResult = await this.embedder.embed(context);
+            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);

package/dist/text-analyzer.d.ts

@@ -60,3 +60,15 @@ export declare function matchesFilter(allKeywords: Set<string>, filter: string,
  *  Title matches get 2x weight over content-only matches.
  *  Tag and exact matches count as full-weight hits (same as title). */
 export declare function computeRelevanceScore(titleKeywords: Set<string>, contentKeywords: Set<string>, confidence: number, filter: string, tags?: readonly string[]): number;
+/** Extract a title and content from a single observation string.
+ *  Title: first sentence (terminated by . ! ? or newline), capped at MAX_TITLE_LENGTH.
+ *  Content: the full observation text (title is a derived label, not subtracted).
+ *
+ *  Abbreviation-safe: requires 2+ word characters before the period to avoid
+ *  splitting on "e.g.", "U.S.", "i.e.", etc.
+ *
+ *  Pure function — no I/O, no side effects. */
+export declare function extractTitle(observation: string): {
+    readonly title: string;
+    readonly content: string;
+};

package/dist/text-analyzer.js

@@ -275,3 +275,31 @@ export function computeRelevanceScore(titleKeywords, contentKeywords, confidence
     }
     return bestScore * confidence;
 }
+/** Maximum title length before truncation */
+const MAX_TITLE_LENGTH = 80;
+/** Extract a title and content from a single observation string.
+ *  Title: first sentence (terminated by . ! ? or newline), capped at MAX_TITLE_LENGTH.
+ *  Content: the full observation text (title is a derived label, not subtracted).
+ *
+ *  Abbreviation-safe: requires 2+ word characters before the period to avoid
+ *  splitting on "e.g.", "U.S.", "i.e.", etc.
+ *
+ *  Pure function — no I/O, no side effects. */
+export function extractTitle(observation) {
+    const trimmed = observation.trim();
+    if (trimmed.length === 0)
+        return { title: '', content: '' };
+    // Find first sentence boundary.
+    // The lookbehind (?<=\w{2}) ensures we don't split on abbreviations like "e.g." or "U.S."
+    // where a period follows a single character. Newlines always end a sentence.
+    const sentenceMatch = trimmed.match(/(?<=\w{2})[.!?](?:\s|$)|\n/);
+    const sentenceEnd = sentenceMatch?.index ?? -1;
+    const firstSentence = sentenceEnd >= 0
+        ? trimmed.slice(0, sentenceEnd + 1).trim()
+        : trimmed;
+    // Truncate if too long
+    const title = firstSentence.length <= MAX_TITLE_LENGTH
+        ? firstSentence
+        : firstSentence.slice(0, MAX_TITLE_LENGTH - 3).trimEnd() + '...';
+    return { title, content: trimmed };
+}

package/dist/thresholds.d.ts

@@ -30,6 +30,10 @@ export declare const SEMANTIC_MIN_SIMILARITY = 0.45;
  *  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

@@ -56,6 +56,10 @@ export const SEMANTIC_MIN_SIMILARITY = 0.45;
  *  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

@@ -7,7 +7,7 @@ export type EphemeralSeverity = 'high' | 'medium' | 'low';
 /** Parse a raw string into a TrustLevel, returning null for invalid input */
 export declare function parseTrustLevel(raw: string): TrustLevel | null;
 /** Predefined topic scopes for organizing knowledge */
-export type TopicScope = 'user' | 'preferences' | 'architecture' | 'conventions' | 'gotchas' | 'recent-work' | `modules/${string}`;
+export type TopicScope = 'user' | 'preferences' | 'architecture' | 'conventions' | 'gotchas' | 'general' | 'recent-work' | `modules/${string}`;
 /** Validated tag: lowercase alphanumeric slug (letters, digits, hyphens).
  *  Branded type prevents accidentally passing raw strings where validated tags are expected. */
 export type Tag = string & {
@@ -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/dist/types.js

@@ -9,7 +9,7 @@ const TRUST_LEVELS = ['user', 'agent-confirmed', 'agent-inferred'];
 export function parseTrustLevel(raw) {
     return TRUST_LEVELS.includes(raw) ? raw : null;
 }
-const FIXED_TOPICS = ['user', 'preferences', 'architecture', 'conventions', 'gotchas', 'recent-work'];
+const FIXED_TOPICS = ['user', 'preferences', 'architecture', 'conventions', 'gotchas', 'general', 'recent-work'];
 /** Construct an EmbeddingVector from a Float32Array. Boundary validation only —
  *  callers (OllamaEmbedder, FakeEmbedder, vector deserialization) validate dimensions. */
 export function asEmbeddingVector(raw) {

package/package.json

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