@danielsimonjr/memory-mcp 9.9.0 → 10.0.0

package/dist/search/EmbeddingService.js

@@ -2,21 +2,57 @@
  * Embedding Service
  *
  * Phase 4 Sprint 10: Provides embedding abstractions for semantic search.
+ * Phase 12 Sprint 5: Added query/document prefixes, l2Normalize, mode parameter,
+ *                    and batch embedding with progress callback.
  * Supports multiple providers: OpenAI (cloud) and local (transformers.js).
  *
  * @module search/EmbeddingService
  */
 import { EMBEDDING_DEFAULTS, OPENAI_API_CONFIG, getEmbeddingConfig, } from '../utils/constants.js';
+/**
+ * Phase 12 Sprint 5: Prefixes for query-optimized embedding encoding.
+ *
+ * These prefixes are used to distinguish between query and document embeddings,
+ * which can improve retrieval performance with asymmetric embedding models.
+ */
+export const QUERY_PREFIX = 'query: ';
+export const DOCUMENT_PREFIX = 'passage: ';
+/**
+ * Phase 12 Sprint 5: L2 normalize a vector for cosine similarity.
+ *
+ * Normalizes a vector to unit length (magnitude 1), which is required
+ * for accurate cosine similarity calculations.
+ *
+ * @param vector - Input vector to normalize
+ * @returns L2 normalized vector
+ *
+ * @example
+ * ```typescript
+ * const normalized = l2Normalize([3, 4]); // [0.6, 0.8]
+ * ```
+ */
+export function l2Normalize(vector) {
+    let magnitude = 0;
+    for (const v of vector) {
+        magnitude += v * v;
+    }
+    magnitude = Math.sqrt(magnitude);
+    if (magnitude === 0 || magnitude === 1) {
+        return magnitude === 0 ? vector : vector.slice();
+    }
+    return vector.map(v => v / magnitude);
+}
 /**
  * OpenAI Embedding Service
  *
  * Uses OpenAI's text-embedding-3-small model for generating embeddings.
  * Supports single and batch embedding with rate limit handling.
+ * Phase 12 Sprint 5: Added mode parameter and progress callback support.
  *
  * @example
  * ```typescript
  * const service = new OpenAIEmbeddingService('sk-...');
- * const embedding = await service.embed("Hello world");
+ * const embedding = await service.embed("Hello world", 'query');
  * console.log(`Generated ${embedding.length} dimensions`);
  * ```
  */
@@ -45,36 +81,86 @@ export class OpenAIEmbeddingService {
     async isReady() {
         return !!this.apiKey;
     }
+    /**
+     * Apply prefix to text based on embedding mode.
+     *
+     * @param text - Original text
+     * @param mode - Embedding mode ('query' or 'document')
+     * @returns Text with appropriate prefix
+     */
+    applyPrefix(text, mode = 'document') {
+        return mode === 'query' ? `${QUERY_PREFIX}${text}` : `${DOCUMENT_PREFIX}${text}`;
+    }
     /**
      * Generate embedding for a single text.
      *
      * @param text - Text to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
      * @returns Embedding vector
      */
-    async embed(text) {
-        const results = await this.embedBatch([text]);
+    async embed(text, mode = 'document') {
+        const results = await this.embedBatch([text], mode);
         return results[0];
     }
     /**
      * Generate embeddings for multiple texts in batch.
      *
      * @param texts - Array of texts to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
      * @returns Array of embedding vectors
      */
-    async embedBatch(texts) {
+    async embedBatch(texts, mode = 'document') {
         if (texts.length === 0) {
             return [];
         }
+        // Apply prefix based on mode
+        const prefixedTexts = texts.map(text => this.applyPrefix(text, mode));
         // Split into batches if needed
         const maxBatchSize = EMBEDDING_DEFAULTS.OPENAI_MAX_BATCH_SIZE;
         const results = [];
-        for (let i = 0; i < texts.length; i += maxBatchSize) {
-            const batch = texts.slice(i, i + maxBatchSize);
+        for (let i = 0; i < prefixedTexts.length; i += maxBatchSize) {
+            const batch = prefixedTexts.slice(i, i + maxBatchSize);
             const batchResults = await this.embedBatchInternal(batch);
             results.push(...batchResults);
         }
         return results;
     }
+    /**
+     * Generate embeddings with progress callback support.
+     *
+     * Phase 12 Sprint 5: Added for tracking progress on large batch operations.
+     *
+     * @param texts - Array of texts to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
+     * @param onProgress - Optional progress callback
+     * @returns Array of embedding vectors
+     */
+    async embedBatchWithProgress(texts, mode = 'document', onProgress) {
+        if (texts.length === 0) {
+            return [];
+        }
+        // Apply prefix based on mode
+        const prefixedTexts = texts.map(text => this.applyPrefix(text, mode));
+        // Split into batches if needed
+        const maxBatchSize = EMBEDDING_DEFAULTS.OPENAI_MAX_BATCH_SIZE;
+        const results = [];
+        const total = prefixedTexts.length;
+        for (let i = 0; i < prefixedTexts.length; i += maxBatchSize) {
+            const batch = prefixedTexts.slice(i, i + maxBatchSize);
+            const batchResults = await this.embedBatchInternal(batch);
+            results.push(...batchResults);
+            // Report progress
+            if (onProgress) {
+                const current = Math.min(i + maxBatchSize, total);
+                onProgress({
+                    current,
+                    total,
+                    percentage: Math.round((current / total) * 100),
+                });
+            }
+        }
+        return results;
+    }
     /**
      * Internal batch embedding with retry logic.
      */
@@ -148,6 +234,7 @@ export class OpenAIEmbeddingService {
  *
  * Uses @xenova/transformers for local embedding generation.
  * No API calls needed - runs entirely offline after initial model download.
+ * Phase 12 Sprint 5: Added mode parameter and progress callback support.
  *
  * Note: Requires @xenova/transformers to be installed as an optional dependency.
  * If not available, initialization will fail gracefully.
@@ -156,7 +243,7 @@ export class OpenAIEmbeddingService {
  * ```typescript
  * const service = new LocalEmbeddingService();
  * await service.initialize();
- * const embedding = await service.embed("Hello world");
+ * const embedding = await service.embed("Hello world", 'query');
  * ```
  */
 export class LocalEmbeddingService {
@@ -219,16 +306,28 @@ export class LocalEmbeddingService {
         }
         return this.initialized;
     }
+    /**
+     * Apply prefix to text based on embedding mode.
+     *
+     * @param text - Original text
+     * @param mode - Embedding mode ('query' or 'document')
+     * @returns Text with appropriate prefix
+     */
+    applyPrefix(text, mode = 'document') {
+        return mode === 'query' ? `${QUERY_PREFIX}${text}` : `${DOCUMENT_PREFIX}${text}`;
+    }
     /**
      * Generate embedding for a single text.
      *
      * @param text - Text to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
      * @returns Embedding vector
      */
-    async embed(text) {
+    async embed(text, mode = 'document') {
         await this.ensureInitialized();
+        const prefixedText = this.applyPrefix(text, mode);
         const pipelineFn = this.pipeline;
-        const output = await pipelineFn(text, { pooling: 'mean', normalize: true });
+        const output = await pipelineFn(prefixedText, { pooling: 'mean', normalize: true });
         return Array.from(output.data);
     }
     /**
@@ -236,14 +335,44 @@ export class LocalEmbeddingService {
      * Note: Local processing is done sequentially to avoid memory issues.
      *
      * @param texts - Array of texts to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
      * @returns Array of embedding vectors
      */
-    async embedBatch(texts) {
+    async embedBatch(texts, mode = 'document') {
         await this.ensureInitialized();
         const results = [];
         for (const text of texts) {
-            const embedding = await this.embed(text);
+            const embedding = await this.embed(text, mode);
+            results.push(embedding);
+        }
+        return results;
+    }
+    /**
+     * Generate embeddings with progress callback support.
+     *
+     * Phase 12 Sprint 5: Added for tracking progress on large batch operations.
+     *
+     * @param texts - Array of texts to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
+     * @param onProgress - Optional progress callback
+     * @returns Array of embedding vectors
+     */
+    async embedBatchWithProgress(texts, mode = 'document', onProgress) {
+        await this.ensureInitialized();
+        const results = [];
+        const total = texts.length;
+        for (let i = 0; i < texts.length; i++) {
+            const embedding = await this.embed(texts[i], mode);
             results.push(embedding);
+            // Report progress
+            if (onProgress) {
+                const current = i + 1;
+                onProgress({
+                    current,
+                    total,
+                    percentage: Math.round((current / total) * 100),
+                });
+            }
         }
         return results;
     }
@@ -261,6 +390,7 @@ export class LocalEmbeddingService {
  *
  * Generates deterministic mock embeddings for testing purposes.
  * Useful for unit tests that don't need real embeddings.
+ * Phase 12 Sprint 5: Added mode parameter and progress callback support.
  */
 export class MockEmbeddingService {
     dimensions;
@@ -280,15 +410,28 @@ export class MockEmbeddingService {
     async isReady() {
         return true;
     }
+    /**
+     * Apply prefix to text based on embedding mode.
+     *
+     * @param text - Original text
+     * @param mode - Embedding mode ('query' or 'document')
+     * @returns Text with appropriate prefix
+     */
+    applyPrefix(text, mode = 'document') {
+        return mode === 'query' ? `${QUERY_PREFIX}${text}` : `${DOCUMENT_PREFIX}${text}`;
+    }
     /**
      * Generate a deterministic mock embedding for a text.
      *
      * @param text - Text to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
      * @returns Mock embedding vector
      */
-    async embed(text) {
+    async embed(text, mode = 'document') {
+        // Apply prefix based on mode (affects hash for different embeddings per mode)
+        const prefixedText = this.applyPrefix(text, mode);
         // Generate deterministic embedding based on text hash
-        const hash = this.hashString(text);
+        const hash = this.hashString(prefixedText);
         const embedding = [];
         for (let i = 0; i < this.dimensions; i++) {
             // Use hash and index to generate deterministic values
@@ -302,10 +445,39 @@ export class MockEmbeddingService {
      * Generate mock embeddings for multiple texts.
      *
      * @param texts - Array of texts to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
+     * @returns Array of mock embedding vectors
+     */
+    async embedBatch(texts, mode = 'document') {
+        return Promise.all(texts.map(text => this.embed(text, mode)));
+    }
+    /**
+     * Generate mock embeddings with progress callback support.
+     *
+     * Phase 12 Sprint 5: Added for tracking progress on large batch operations.
+     *
+     * @param texts - Array of texts to embed
+     * @param mode - Embedding mode ('query' or 'document', default: 'document')
+     * @param onProgress - Optional progress callback
      * @returns Array of mock embedding vectors
      */
-    async embedBatch(texts) {
-        return Promise.all(texts.map(text => this.embed(text)));
+    async embedBatchWithProgress(texts, mode = 'document', onProgress) {
+        const results = [];
+        const total = texts.length;
+        for (let i = 0; i < texts.length; i++) {
+            const embedding = await this.embed(texts[i], mode);
+            results.push(embedding);
+            // Report progress
+            if (onProgress) {
+                const current = i + 1;
+                onProgress({
+                    current,
+                    total,
+                    percentage: Math.round((current / total) * 100),
+                });
+            }
+        }
+        return results;
     }
     /**
      * Simple string hash function.

package/dist/search/HybridScorer.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Hybrid Scorer
+ *
+ * Combines semantic, lexical, and symbolic search scores with
+ * min-max normalization and configurable weights.
+ *
+ * Phase 12 Sprint 3: Search Algorithm Optimization
+ *
+ * @module search/HybridScorer
+ */
+import type { Entity } from '../types/index.js';
+/**
+ * Result from semantic search layer.
+ */
+export interface SemanticSearchResult {
+    /** Entity name */
+    entityName: string;
+    /** Similarity score (typically 0-1 for cosine similarity) */
+    similarity: number;
+    /** The matched entity (if resolved) */
+    entity?: Entity;
+}
+/**
+ * Result from lexical search layer (TF-IDF or BM25).
+ */
+export interface LexicalSearchResult {
+    /** Entity name */
+    entityName: string;
+    /** Relevance score (unbounded, higher is better) */
+    score: number;
+    /** The matched entity (if resolved) */
+    entity?: Entity;
+}
+/**
+ * Result from symbolic search layer.
+ */
+export interface SymbolicSearchResult {
+    /** Entity name */
+    entityName: string;
+    /** Match score (typically 0-1) */
+    score: number;
+    /** The matched entity (if resolved) */
+    entity?: Entity;
+}
+/**
+ * Combined result with scores from all layers.
+ */
+export interface ScoredResult {
+    /** Entity name */
+    entityName: string;
+    /** The matched entity */
+    entity: Entity;
+    /** Individual layer scores (normalized 0-1) */
+    scores: {
+        semantic: number;
+        lexical: number;
+        symbolic: number;
+        combined: number;
+    };
+    /** Which layers contributed to this result */
+    matchedLayers: ('semantic' | 'lexical' | 'symbolic')[];
+    /** Original raw scores before normalization */
+    rawScores: {
+        semantic?: number;
+        lexical?: number;
+        symbolic?: number;
+    };
+}
+/**
+ * Configurable weights for hybrid scoring.
+ */
+export interface HybridWeights {
+    /** Weight for semantic layer (default: 0.4) */
+    semantic: number;
+    /** Weight for lexical layer (default: 0.4) */
+    lexical: number;
+    /** Weight for symbolic layer (default: 0.2) */
+    symbolic: number;
+}
+/**
+ * Default weights for hybrid search.
+ */
+export declare const DEFAULT_SCORER_WEIGHTS: HybridWeights;
+/**
+ * Options for the HybridScorer.
+ */
+export interface HybridScorerOptions {
+    /** Weights for each layer */
+    weights?: Partial<HybridWeights>;
+    /** Minimum score to include in results (default: 0) */
+    minScore?: number;
+    /** Whether to normalize weights to sum to 1 (default: true) */
+    normalizeWeights?: boolean;
+}
+/**
+ * HybridScorer combines multiple search signals using min-max normalization.
+ *
+ * Features:
+ * 1. Min-max normalization brings all scores to 0-1 range
+ * 2. Configurable weights for each layer
+ * 3. Handles missing layers gracefully (redistributes weights)
+ * 4. Tracks which layers contributed to each result
+ *
+ * @example
+ * ```typescript
+ * const scorer = new HybridScorer({
+ *   weights: { semantic: 0.5, lexical: 0.3, symbolic: 0.2 }
+ * });
+ *
+ * const results = scorer.combine(
+ *   semanticResults,
+ *   lexicalResults,
+ *   symbolicResults,
+ *   entityMap
+ * );
+ * ```
+ */
+export declare class HybridScorer {
+    private weights;
+    private minScore;
+    private normalizeWeights;
+    constructor(options?: HybridScorerOptions);
+    /**
+     * Get current weights configuration.
+     */
+    getWeights(): HybridWeights;
+    /**
+     * Update weights configuration.
+     */
+    setWeights(weights: Partial<HybridWeights>): void;
+    /**
+     * Perform min-max normalization on scores.
+     *
+     * Formula: normalized = (x - min) / (max - min)
+     *
+     * @param scores - Map of entity name to raw score
+     * @returns Map of entity name to normalized score (0-1)
+     */
+    minMaxNormalize(scores: Map<string, number>): Map<string, number>;
+    /**
+     * Combine results from all three search layers.
+     *
+     * @param semanticResults - Results from semantic search
+     * @param lexicalResults - Results from lexical search
+     * @param symbolicResults - Results from symbolic search
+     * @param entityMap - Map of entity names to Entity objects
+     * @returns Array of combined results sorted by score
+     */
+    combine(semanticResults: SemanticSearchResult[], lexicalResults: LexicalSearchResult[], symbolicResults: SymbolicSearchResult[], entityMap: Map<string, Entity>): ScoredResult[];
+    /**
+     * Get weights normalized to sum to 1, redistributing for missing layers.
+     *
+     * @param hasSemantic - Whether semantic results are available
+     * @param hasLexical - Whether lexical results are available
+     * @param hasSymbolic - Whether symbolic results are available
+     * @returns Normalized weights
+     */
+    getNormalizedWeights(hasSemantic: boolean, hasLexical: boolean, hasSymbolic: boolean): HybridWeights;
+    /**
+     * Combine scores from maps directly (alternative interface).
+     *
+     * @param semanticScores - Map of entity name to semantic score
+     * @param lexicalScores - Map of entity name to lexical score
+     * @param symbolicScores - Map of entity name to symbolic score
+     * @param entityMap - Map of entity names to Entity objects
+     * @returns Array of combined results sorted by score
+     */
+    combineFromMaps(semanticScores: Map<string, number>, lexicalScores: Map<string, number>, symbolicScores: Map<string, number>, entityMap: Map<string, Entity>): ScoredResult[];
+    /**
+     * Calculate combined score for a single entity.
+     *
+     * Useful for scoring individual results without full normalization.
+     *
+     * @param semanticScore - Normalized semantic score (0-1)
+     * @param lexicalScore - Normalized lexical score (0-1)
+     * @param symbolicScore - Normalized symbolic score (0-1)
+     * @returns Combined weighted score
+     */
+    calculateScore(semanticScore: number, lexicalScore: number, symbolicScore: number): number;
+}
+//# sourceMappingURL=HybridScorer.d.ts.map

package/dist/search/HybridScorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HybridScorer.d.ts","sourceRoot":"","sources":["../../src/search/HybridScorer.ts"],"names":[],"mappings":"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"}