@danielsimonjr/memory-mcp 11.0.1 → 11.1.1

package/dist/search/ParallelSearchExecutor.js

@@ -1,309 +0,0 @@
-/**
- * Parallel Search Executor
- *
- * Phase 12 Sprint 2: Executes search layers (semantic, lexical, symbolic)
- * concurrently using Promise.all with graceful fallback on failures.
- *
- * @module search/ParallelSearchExecutor
- */
-import { SymbolicSearch } from './SymbolicSearch.js';
-import { SEMANTIC_SEARCH_LIMITS } from '../utils/constants.js';
-/**
- * ParallelSearchExecutor - Execute search layers concurrently
- *
- * Orchestrates parallel execution of semantic, lexical, and symbolic search
- * layers using Promise.all. Provides:
- * - Concurrent execution for improved latency
- * - Per-layer timing metadata
- * - Graceful fallback on individual layer failures
- * - Layer-specific error isolation
- *
- * @example
- * ```typescript
- * const executor = new ParallelSearchExecutor(semanticSearch, rankedSearch);
- *
- * const result = await executor.execute(graph, 'machine learning', {
- *   semantic: { minSimilarity: 0.5 },
- *   symbolic: { tags: ['ai'] }
- * });
- *
- * console.log(`Total time: ${result.totalTimeMs}ms`);
- * for (const timing of result.timings) {
- *   console.log(`${timing.layer}: ${timing.durationMs}ms, ${timing.resultCount} results`);
- * }
- * ```
- */
-export class ParallelSearchExecutor {
-    semanticSearch;
-    rankedSearch;
-    symbolicSearch;
-    constructor(semanticSearch, rankedSearch) {
-        this.semanticSearch = semanticSearch;
-        this.rankedSearch = rankedSearch;
-        this.symbolicSearch = new SymbolicSearch();
-    }
-    /**
-     * Execute all search layers in parallel.
-     *
-     * @param graph - Knowledge graph to search
-     * @param query - Search query text
-     * @param options - Search options for each layer
-     * @returns Parallel search results with timing metadata
-     */
-    async execute(graph, query, options = {}) {
-        const { semantic = {}, lexical = {}, symbolic = {}, limit = SEMANTIC_SEARCH_LIMITS.DEFAULT_LIMIT, timeoutMs = 30000, } = options;
-        const overallStart = Date.now();
-        const timings = [];
-        const failedLayers = [];
-        // Execute all three layers in parallel
-        const [semanticResult, lexicalResult, symbolicResult] = await Promise.all([
-            this.executeSemanticLayer(graph, query, semantic, limit * 2, timeoutMs),
-            this.executeLexicalLayer(query, lexical, limit * 2, timeoutMs),
-            this.executeSymbolicLayer(graph.entities, symbolic, timeoutMs),
-        ]);
-        // Collect timing information
-        timings.push(semanticResult.timing);
-        timings.push(lexicalResult.timing);
-        timings.push(symbolicResult.timing);
-        // Track failed layers
-        if (!semanticResult.timing.success)
-            failedLayers.push('semantic');
-        if (!lexicalResult.timing.success)
-            failedLayers.push('lexical');
-        if (!symbolicResult.timing.success)
-            failedLayers.push('symbolic');
-        const totalTimeMs = Date.now() - overallStart;
-        return {
-            semanticResults: semanticResult.results,
-            lexicalResults: lexicalResult.results,
-            symbolicResults: symbolicResult.results,
-            timings,
-            totalTimeMs,
-            allSucceeded: failedLayers.length === 0,
-            failedLayers,
-        };
-    }
-    /**
-     * Execute semantic search layer with timing.
-     */
-    async executeSemanticLayer(graph, query, options, limit, _timeoutMs) {
-        const startTime = Date.now();
-        const results = new Map();
-        let success = true;
-        let error;
-        if (!this.semanticSearch) {
-            // Semantic search not available - treat as graceful degradation
-            return {
-                results,
-                timing: {
-                    layer: 'semantic',
-                    startTime,
-                    endTime: Date.now(),
-                    durationMs: Date.now() - startTime,
-                    success: true, // Not an error, just not configured
-                    resultCount: 0,
-                },
-            };
-        }
-        try {
-            // Execute semantic search with timeout
-            const semanticResults = await Promise.race([
-                this.semanticSearch.search(graph, query, options.topK ?? limit, options.minSimilarity ?? 0),
-                this.createTimeout(_timeoutMs, 'Semantic search timeout'),
-            ]);
-            for (const result of semanticResults) {
-                results.set(result.entity.name, result.similarity);
-            }
-        }
-        catch (err) {
-            success = false;
-            error = err instanceof Error ? err.message : String(err);
-        }
-        const endTime = Date.now();
-        return {
-            results,
-            timing: {
-                layer: 'semantic',
-                startTime,
-                endTime,
-                durationMs: endTime - startTime,
-                success,
-                error,
-                resultCount: results.size,
-            },
-        };
-    }
-    /**
-     * Execute lexical search layer (TF-IDF/BM25) with timing.
-     */
-    async executeLexicalLayer(query, _options, limit, _timeoutMs) {
-        const startTime = Date.now();
-        const results = new Map();
-        let success = true;
-        let error;
-        try {
-            // Execute lexical search with timeout
-            const lexicalResults = await Promise.race([
-                this.rankedSearch.searchNodesRanked(query, undefined, // tags
-                undefined, // minImportance
-                undefined, // maxImportance
-                limit),
-                this.createTimeout(_timeoutMs, 'Lexical search timeout'),
-            ]);
-            // Normalize scores to 0-1 range
-            const maxScore = Math.max(...lexicalResults.map(r => r.score), 1);
-            for (const result of lexicalResults) {
-                results.set(result.entity.name, result.score / maxScore);
-            }
-        }
-        catch (err) {
-            success = false;
-            error = err instanceof Error ? err.message : String(err);
-        }
-        const endTime = Date.now();
-        return {
-            results,
-            timing: {
-                layer: 'lexical',
-                startTime,
-                endTime,
-                durationMs: endTime - startTime,
-                success,
-                error,
-                resultCount: results.size,
-            },
-        };
-    }
-    /**
-     * Execute symbolic search layer with timing.
-     */
-    async executeSymbolicLayer(entities, filters, _timeoutMs) {
-        const startTime = Date.now();
-        const results = new Map();
-        let success = true;
-        let error;
-        try {
-            // Symbolic search is synchronous but wrap for consistency
-            if (!filters || Object.keys(filters).length === 0) {
-                // No filters - give all entities base score
-                for (const entity of entities) {
-                    results.set(entity.name, 0.5);
-                }
-            }
-            else {
-                const symbolicResults = this.symbolicSearch.search(entities, filters);
-                for (const result of symbolicResults) {
-                    results.set(result.entity.name, result.score);
-                }
-            }
-        }
-        catch (err) {
-            success = false;
-            error = err instanceof Error ? err.message : String(err);
-        }
-        const endTime = Date.now();
-        return {
-            results,
-            timing: {
-                layer: 'symbolic',
-                startTime,
-                endTime,
-                durationMs: endTime - startTime,
-                success,
-                error,
-                resultCount: results.size,
-            },
-        };
-    }
-    /**
-     * Create a timeout promise.
-     */
-    createTimeout(ms, message) {
-        return new Promise((_, reject) => {
-            setTimeout(() => reject(new Error(message)), ms);
-        });
-    }
-    /**
-     * Execute a single layer independently.
-     *
-     * @param layer - Layer to execute
-     * @param graph - Knowledge graph
-     * @param query - Search query
-     * @param options - Layer-specific options
-     * @returns Layer results with timing
-     */
-    async executeLayer(layer, graph, query, options = {}) {
-        const limit = options.limit ?? SEMANTIC_SEARCH_LIMITS.DEFAULT_LIMIT;
-        const timeoutMs = options.timeoutMs ?? 30000;
-        switch (layer) {
-            case 'semantic':
-                return this.executeSemanticLayer(graph, query, options.semantic ?? {}, limit * 2, timeoutMs);
-            case 'lexical':
-                return this.executeLexicalLayer(query, options.lexical ?? {}, limit * 2, timeoutMs);
-            case 'symbolic':
-                return this.executeSymbolicLayer(graph.entities, options.symbolic, timeoutMs);
-        }
-    }
-    /**
-     * Execute only specific layers in parallel.
-     *
-     * @param layers - Layers to execute
-     * @param graph - Knowledge graph
-     * @param query - Search query
-     * @param options - Search options
-     * @returns Partial results for requested layers
-     */
-    async executeSelectedLayers(layers, graph, query, options = {}) {
-        const overallStart = Date.now();
-        const results = new Map();
-        const timings = [];
-        const layerPromises = layers.map(layer => this.executeLayer(layer, graph, query, options).then(result => ({
-            layer,
-            ...result,
-        })));
-        const layerExecutionResults = await Promise.all(layerPromises);
-        for (const { layer, results: layerData, timing } of layerExecutionResults) {
-            results.set(layer, layerData);
-            timings.push(timing);
-        }
-        return {
-            results,
-            timings,
-            totalTimeMs: Date.now() - overallStart,
-        };
-    }
-    /**
-     * Get timing summary from results.
-     *
-     * @param timings - Array of layer timings
-     * @returns Formatted timing summary
-     */
-    static formatTimingSummary(timings) {
-        const lines = [];
-        let totalTime = 0;
-        let maxTime = 0;
-        for (const timing of timings) {
-            const status = timing.success ? 'OK' : `FAILED: ${timing.error}`;
-            lines.push(`  ${timing.layer}: ${timing.durationMs}ms (${timing.resultCount} results) [${status}]`);
-            totalTime += timing.durationMs;
-            maxTime = Math.max(maxTime, timing.durationMs);
-        }
-        lines.unshift('Search Layer Timings:');
-        lines.push(`  Total (sequential): ${totalTime}ms`);
-        lines.push(`  Max (parallel bottleneck): ${maxTime}ms`);
-        lines.push(`  Speedup: ${(totalTime / maxTime).toFixed(2)}x`);
-        return lines.join('\n');
-    }
-    /**
-     * Calculate potential speedup from parallel execution.
-     *
-     * @param timings - Array of layer timings
-     * @returns Speedup metrics
-     */
-    static calculateSpeedup(timings) {
-        const sequentialTime = timings.reduce((sum, t) => sum + t.durationMs, 0);
-        const parallelTime = Math.max(...timings.map(t => t.durationMs));
-        const speedup = sequentialTime / parallelTime;
-        return { sequentialTime, parallelTime, speedup };
-    }
-}

package/dist/search/QuantizedVectorStore.d.ts

@@ -1,171 +0,0 @@
-/**
- * Quantized Vector Store
- *
- * Phase 12 Sprint 6: 8-bit scalar quantization for 4x vector memory reduction.
- * Uses asymmetric similarity computation for improved accuracy.
- *
- * @module search/QuantizedVectorStore
- */
-/**
- * Quantization parameters for a vector set.
- */
-export interface QuantizationParams {
-    /** Minimum value in the original vectors */
-    min: number;
-    /** Maximum value in the original vectors */
-    max: number;
-    /** Scale factor for quantization */
-    scale: number;
-    /** Dimension of vectors */
-    dimension: number;
-}
-/**
- * Statistics for the quantized vector store.
- */
-export interface QuantizedVectorStoreStats {
-    /** Number of stored vectors */
-    vectorCount: number;
-    /** Vector dimension */
-    dimension: number;
-    /** Full precision memory usage (bytes) */
-    fullPrecisionBytes: number;
-    /** Quantized memory usage (bytes) */
-    quantizedBytes: number;
-    /** Memory reduction ratio */
-    memoryReductionRatio: number;
-    /** Average quantization error */
-    avgQuantizationError: number;
-}
-/**
- * Search result from quantized vector store.
- */
-export interface QuantizedSearchResult {
-    /** Entity ID */
-    id: string;
-    /** Similarity score (0-1) */
-    similarity: number;
-    /** Whether result used quantized computation */
-    quantized: boolean;
-}
-/**
- * Configuration options for QuantizedVectorStore.
- */
-export interface QuantizedVectorStoreOptions {
-    /** Use asymmetric similarity (query in full precision) */
-    asymmetric?: boolean;
-    /** Minimum vectors before enabling quantization */
-    minVectorsForQuantization?: number;
-    /** Enable accuracy tracking */
-    trackAccuracy?: boolean;
-}
-/**
- * Quantized Vector Store with 8-bit scalar quantization.
- *
- * Provides 4x memory reduction while maintaining >95% accuracy
- * using asymmetric similarity computation.
- *
- * @example
- * ```typescript
- * const store = new QuantizedVectorStore();
- *
- * // Add vectors
- * store.add('entity1', [0.1, 0.2, 0.3, ...]);
- * store.add('entity2', [0.4, 0.5, 0.6, ...]);
- *
- * // Search
- * const results = store.search([0.15, 0.25, 0.35, ...], 10);
- *
- * // Get stats
- * const stats = store.getStats();
- * console.log(`Memory reduction: ${stats.memoryReductionRatio}x`);
- * ```
- */
-export declare class QuantizedVectorStore {
-    private fullPrecisionVectors;
-    private quantizedVectors;
-    private quantizationParams;
-    private options;
-    private isQuantized;
-    private quantizationErrors;
-    constructor(options?: QuantizedVectorStoreOptions);
-    /**
-     * Add a vector to the store.
-     *
-     * @param id - Entity identifier
-     * @param vector - Float vector (any dimension, must be consistent)
-     */
-    add(id: string, vector: number[]): void;
-    /**
-     * Remove a vector from the store.
-     *
-     * @param id - Entity identifier
-     * @returns True if vector was removed
-     */
-    remove(id: string): boolean;
-    /**
-     * Check if a vector exists.
-     *
-     * @param id - Entity identifier
-     */
-    has(id: string): boolean;
-    /**
-     * Get a vector (dequantized if necessary).
-     *
-     * @param id - Entity identifier
-     * @returns Vector or undefined
-     */
-    get(id: string): number[] | undefined;
-    /**
-     * Search for similar vectors.
-     *
-     * @param query - Query vector
-     * @param k - Number of results to return
-     * @returns Top k similar vectors with scores
-     */
-    search(query: number[], k: number): QuantizedSearchResult[];
-    /**
-     * Compute similarity between a query and specific entity.
-     *
-     * @param query - Query vector
-     * @param id - Entity identifier
-     * @returns Similarity score or undefined if not found
-     */
-    computeSimilarity(query: number[], id: string): number | undefined;
-    /**
-     * Force quantization of all vectors.
-     */
-    quantize(): void;
-    /**
-     * Get store statistics.
-     */
-    getStats(): QuantizedVectorStoreStats;
-    /**
-     * Check if store is currently using quantization.
-     */
-    isUsingQuantization(): boolean;
-    /**
-     * Get the number of stored vectors.
-     */
-    size(): number;
-    /**
-     * Clear all vectors from the store.
-     */
-    clear(): void;
-    /**
-     * Export all vectors.
-     */
-    export(): Map<string, number[]>;
-    /**
-     * Import vectors from a map.
-     *
-     * @param vectors - Map of id to vector
-     * @param quantize - Whether to quantize after import
-     */
-    import(vectors: Map<string, number[]>, quantize?: boolean): void;
-    private computeQuantizationParams;
-    private quantizeVector;
-    private dequantizeVector;
-    private cosineSimilarity;
-    private computeError;
-}
-//# sourceMappingURL=QuantizedVectorStore.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"QuantizedVectorStore.d.ts","sourceRoot":"","sources":["../../src/search/QuantizedVectorStore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gBAAgB;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0DAA0D;IAC1D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mDAAmD;IACnD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,+BAA+B;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,oBAAoB,CAA4B;IACxD,OAAO,CAAC,gBAAgB,CAA0B;IAClD,OAAO,CAAC,kBAAkB,CAAmC;IAC7D,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,kBAAkB,CAAgB;gBAE9B,OAAO,CAAC,EAAE,2BAA2B;IAMjD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAuBvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAM3B;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAKrC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,qBAAqB,EAAE;IAyB3D;;;;;;OAMG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAelE;;OAEG;IACH,QAAQ,IAAI,IAAI;IAqBhB;;OAEG;IACH,QAAQ,IAAI,yBAAyB;IAsBrC;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAI9B;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAQ/B;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,UAAO,GAAG,IAAI;IAa7D,OAAO,CAAC,yBAAyB;IAkBjC,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,YAAY;CAQrB"}