@danielsimonjr/memory-mcp 9.9.0 → 10.0.0

package/dist/search/OptimizedInvertedIndex.js

@@ -0,0 +1,358 @@
+/**
+ * Optimized Inverted Index
+ *
+ * Memory-efficient inverted index using integer IDs and Uint32Array
+ * for fast multi-term intersection queries.
+ *
+ * Phase 12 Sprint 3: Search Algorithm Optimization
+ *
+ * @module search/OptimizedInvertedIndex
+ */
+/**
+ * Optimized Inverted Index using integer document IDs.
+ *
+ * Memory Optimizations:
+ * 1. Uses integer IDs instead of string entity names
+ * 2. Stores posting lists as Uint32Array (4 bytes per ID vs ~20+ bytes per string)
+ * 3. Maintains sorted posting lists for efficient intersection
+ *
+ * Performance Optimizations:
+ * 1. Sorted array intersection is O(n+m) where n,m are posting list lengths
+ * 2. Early termination when one list is exhausted
+ * 3. Binary search available for unbalanced list sizes
+ *
+ * @example
+ * ```typescript
+ * const index = new OptimizedInvertedIndex();
+ * index.addDocument('entity1', ['machine', 'learning', 'ai']);
+ * index.addDocument('entity2', ['deep', 'learning', 'neural']);
+ *
+ * // Find documents containing both 'machine' AND 'learning'
+ * const results = index.intersect(['machine', 'learning']);
+ * console.log(results); // ['entity1']
+ * ```
+ */
+export class OptimizedInvertedIndex {
+    /** Map from entity name to integer ID */
+    entityToId = new Map();
+    /** Map from integer ID to entity name */
+    idToEntity = new Map();
+    /** Next available ID */
+    nextId = 0;
+    /** Inverted index: term -> sorted array of document IDs */
+    postingLists = new Map();
+    /** Temporary posting lists (before finalization) */
+    tempPostingLists = new Map();
+    /** Whether the index is finalized (posting lists converted to Uint32Array) */
+    finalized = false;
+    /**
+     * Add a document to the index.
+     *
+     * @param entityName - Unique document identifier
+     * @param terms - Array of terms in the document (should be lowercase)
+     */
+    addDocument(entityName, terms) {
+        // Unfinalize if already finalized (allows incremental updates)
+        if (this.finalized) {
+            this.unfinalize();
+        }
+        // Get or assign document ID
+        let docId = this.entityToId.get(entityName);
+        if (docId === undefined) {
+            docId = this.nextId++;
+            this.entityToId.set(entityName, docId);
+            this.idToEntity.set(docId, entityName);
+        }
+        // Add unique terms to posting lists
+        const seenTerms = new Set();
+        for (const term of terms) {
+            if (seenTerms.has(term))
+                continue;
+            seenTerms.add(term);
+            let postingList = this.tempPostingLists.get(term);
+            if (!postingList) {
+                postingList = [];
+                this.tempPostingLists.set(term, postingList);
+            }
+            // Only add if not already present (maintains sorted order if added in order)
+            if (postingList.length === 0 || postingList[postingList.length - 1] !== docId) {
+                postingList.push(docId);
+            }
+        }
+    }
+    /**
+     * Remove a document from the index.
+     *
+     * @param entityName - Document to remove
+     * @returns True if document was found and removed
+     */
+    removeDocument(entityName) {
+        const docId = this.entityToId.get(entityName);
+        if (docId === undefined) {
+            return false;
+        }
+        // Unfinalize if needed
+        if (this.finalized) {
+            this.unfinalize();
+        }
+        // Remove from all posting lists
+        for (const [term, postingList] of this.tempPostingLists) {
+            const idx = postingList.indexOf(docId);
+            if (idx !== -1) {
+                postingList.splice(idx, 1);
+                if (postingList.length === 0) {
+                    this.tempPostingLists.delete(term);
+                }
+            }
+        }
+        // Remove ID mappings
+        this.entityToId.delete(entityName);
+        this.idToEntity.delete(docId);
+        return true;
+    }
+    /**
+     * Finalize the index by converting posting lists to Uint32Array.
+     *
+     * This should be called after bulk indexing for optimal memory usage.
+     * The index can still be updated after finalization, but it will
+     * temporarily use more memory during updates.
+     */
+    finalize() {
+        if (this.finalized)
+            return;
+        // Convert temp posting lists to Uint32Array and sort
+        this.postingLists.clear();
+        for (const [term, list] of this.tempPostingLists) {
+            // Sort and convert to Uint32Array
+            list.sort((a, b) => a - b);
+            const arr = new Uint32Array(list);
+            this.postingLists.set(term, arr);
+        }
+        // Clear temp posting lists to save memory
+        this.tempPostingLists.clear();
+        this.finalized = true;
+    }
+    /**
+     * Convert finalized index back to mutable format.
+     */
+    unfinalize() {
+        if (!this.finalized)
+            return;
+        // Convert Uint32Array back to regular arrays
+        this.tempPostingLists.clear();
+        for (const [term, arr] of this.postingLists) {
+            this.tempPostingLists.set(term, Array.from(arr));
+        }
+        this.postingLists.clear();
+        this.finalized = false;
+    }
+    /**
+     * Get posting list for a term.
+     *
+     * @param term - Term to look up
+     * @returns Posting list result or null if term not found
+     */
+    getPostingList(term) {
+        if (this.finalized) {
+            const arr = this.postingLists.get(term);
+            if (!arr)
+                return null;
+            return { term, docIds: arr };
+        }
+        else {
+            const list = this.tempPostingLists.get(term);
+            if (!list)
+                return null;
+            // Sort and return as Uint32Array
+            const sorted = list.slice().sort((a, b) => a - b);
+            return { term, docIds: new Uint32Array(sorted) };
+        }
+    }
+    /**
+     * Perform intersection of posting lists for multiple terms.
+     *
+     * Returns entity names that contain ALL specified terms.
+     *
+     * @param terms - Array of terms to intersect
+     * @returns Array of entity names containing all terms
+     */
+    intersect(terms) {
+        if (terms.length === 0) {
+            return [];
+        }
+        // Ensure finalized for optimal performance
+        if (!this.finalized) {
+            this.finalize();
+        }
+        // Get posting lists for all terms
+        const postingLists = [];
+        for (const term of terms) {
+            const list = this.postingLists.get(term);
+            if (!list || list.length === 0) {
+                // If any term has no posting list, intersection is empty
+                return [];
+            }
+            postingLists.push(list);
+        }
+        // Sort by length (smallest first for early termination)
+        postingLists.sort((a, b) => a.length - b.length);
+        // Perform multi-way sorted intersection
+        let result = postingLists[0];
+        for (let i = 1; i < postingLists.length; i++) {
+            result = this.intersectTwo(result, postingLists[i]);
+            if (result.length === 0) {
+                return [];
+            }
+        }
+        // Convert IDs back to entity names
+        return Array.from(result).map(id => this.idToEntity.get(id));
+    }
+    /**
+     * Perform union of posting lists for multiple terms.
+     *
+     * Returns entity names that contain ANY of the specified terms.
+     *
+     * @param terms - Array of terms to union
+     * @returns Array of entity names containing any term
+     */
+    union(terms) {
+        if (terms.length === 0) {
+            return [];
+        }
+        // Ensure finalized for optimal performance
+        if (!this.finalized) {
+            this.finalize();
+        }
+        // Collect all unique document IDs
+        const allIds = new Set();
+        for (const term of terms) {
+            const list = this.postingLists.get(term);
+            if (list) {
+                for (const id of list) {
+                    allIds.add(id);
+                }
+            }
+        }
+        // Convert IDs back to entity names
+        return Array.from(allIds).map(id => this.idToEntity.get(id));
+    }
+    /**
+     * Get entities containing a single term.
+     *
+     * @param term - Term to search for
+     * @returns Array of entity names containing the term
+     */
+    search(term) {
+        if (!this.finalized) {
+            const list = this.tempPostingLists.get(term);
+            if (!list)
+                return [];
+            return list.map(id => this.idToEntity.get(id));
+        }
+        const list = this.postingLists.get(term);
+        if (!list)
+            return [];
+        return Array.from(list).map(id => this.idToEntity.get(id));
+    }
+    /**
+     * Intersect two sorted Uint32Arrays.
+     *
+     * Uses merge-style intersection which is O(n+m).
+     */
+    intersectTwo(a, b) {
+        const result = [];
+        let i = 0;
+        let j = 0;
+        while (i < a.length && j < b.length) {
+            if (a[i] === b[j]) {
+                result.push(a[i]);
+                i++;
+                j++;
+            }
+            else if (a[i] < b[j]) {
+                i++;
+            }
+            else {
+                j++;
+            }
+        }
+        return new Uint32Array(result);
+    }
+    /**
+     * Get memory usage statistics.
+     */
+    getMemoryUsage() {
+        let postingListBytes = 0;
+        let termCount = 0;
+        if (this.finalized) {
+            for (const arr of this.postingLists.values()) {
+                // Uint32Array uses 4 bytes per element
+                postingListBytes += arr.byteLength;
+                termCount++;
+            }
+        }
+        else {
+            for (const list of this.tempPostingLists.values()) {
+                // Regular array uses 8 bytes per element (64-bit numbers in V8)
+                // Plus array overhead
+                postingListBytes += list.length * 8 + 32; // Approximate overhead
+                termCount++;
+            }
+        }
+        // Estimate ID map overhead
+        // Map has ~100 bytes overhead + ~50 bytes per entry for string keys
+        const idMapBytes = 100 +
+            this.entityToId.size * 50 +
+            this.idToEntity.size * 8; // number key is ~8 bytes
+        // Estimate term index overhead
+        // ~50 bytes per term entry (key + pointer)
+        const termIndexBytes = termCount * 50;
+        return {
+            postingListBytes,
+            idMapBytes,
+            termIndexBytes,
+            totalBytes: postingListBytes + idMapBytes + termIndexBytes,
+            termCount,
+            documentCount: this.entityToId.size,
+        };
+    }
+    /**
+     * Clear the entire index.
+     */
+    clear() {
+        this.entityToId.clear();
+        this.idToEntity.clear();
+        this.postingLists.clear();
+        this.tempPostingLists.clear();
+        this.nextId = 0;
+        this.finalized = false;
+    }
+    /**
+     * Get the number of documents in the index.
+     */
+    get documentCount() {
+        return this.entityToId.size;
+    }
+    /**
+     * Get the number of unique terms in the index.
+     */
+    get termCount() {
+        return this.finalized
+            ? this.postingLists.size
+            : this.tempPostingLists.size;
+    }
+    /**
+     * Check if an entity is indexed.
+     */
+    hasDocument(entityName) {
+        return this.entityToId.has(entityName);
+    }
+    /**
+     * Check if a term exists in the index.
+     */
+    hasTerm(term) {
+        return this.finalized
+            ? this.postingLists.has(term)
+            : this.tempPostingLists.has(term);
+    }
+}

package/dist/search/ParallelSearchExecutor.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 type { ReadonlyKnowledgeGraph, SymbolicFilters } from '../types/index.js';
+import type { SemanticSearch } from './SemanticSearch.js';
+import type { RankedSearch } from './RankedSearch.js';
+/**
+ * Timing information for a search layer.
+ */
+export interface LayerTiming {
+    /** Layer identifier */
+    layer: 'semantic' | 'lexical' | 'symbolic';
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Whether the layer succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Number of results returned */
+    resultCount: number;
+}
+/**
+ * Result from parallel search execution with timing metadata.
+ */
+export interface ParallelSearchResult {
+    /** Semantic search results: entity name -> similarity score */
+    semanticResults: Map<string, number>;
+    /** Lexical search results: entity name -> normalized score */
+    lexicalResults: Map<string, number>;
+    /** Symbolic search results: entity name -> filter match score */
+    symbolicResults: Map<string, number>;
+    /** Timing information for each layer */
+    timings: LayerTiming[];
+    /** Total execution time in milliseconds */
+    totalTimeMs: number;
+    /** Whether all layers succeeded */
+    allSucceeded: boolean;
+    /** Summary of failed layers */
+    failedLayers: string[];
+}
+/**
+ * Options for parallel search execution.
+ */
+export interface ParallelSearchOptions {
+    /** Semantic search options */
+    semantic?: {
+        minSimilarity?: number;
+        topK?: number;
+    };
+    /** Lexical search options */
+    lexical?: {
+        useStopwords?: boolean;
+        useStemming?: boolean;
+    };
+    /** Symbolic filter criteria */
+    symbolic?: SymbolicFilters;
+    /** Maximum results per layer */
+    limit?: number;
+    /** Timeout per layer in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+/**
+ * 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 declare class ParallelSearchExecutor {
+    private semanticSearch;
+    private rankedSearch;
+    private symbolicSearch;
+    constructor(semanticSearch: SemanticSearch | null, rankedSearch: RankedSearch);
+    /**
+     * 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
+     */
+    execute(graph: ReadonlyKnowledgeGraph, query: string, options?: ParallelSearchOptions): Promise<ParallelSearchResult>;
+    /**
+     * Execute semantic search layer with timing.
+     */
+    private executeSemanticLayer;
+    /**
+     * Execute lexical search layer (TF-IDF/BM25) with timing.
+     */
+    private executeLexicalLayer;
+    /**
+     * Execute symbolic search layer with timing.
+     */
+    private executeSymbolicLayer;
+    /**
+     * Create a timeout promise.
+     */
+    private createTimeout;
+    /**
+     * 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
+     */
+    executeLayer(layer: 'semantic' | 'lexical' | 'symbolic', graph: ReadonlyKnowledgeGraph, query: string, options?: ParallelSearchOptions): Promise<{
+        results: Map<string, number>;
+        timing: LayerTiming;
+    }>;
+    /**
+     * 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
+     */
+    executeSelectedLayers(layers: Array<'semantic' | 'lexical' | 'symbolic'>, graph: ReadonlyKnowledgeGraph, query: string, options?: ParallelSearchOptions): Promise<{
+        results: Map<'semantic' | 'lexical' | 'symbolic', Map<string, number>>;
+        timings: LayerTiming[];
+        totalTimeMs: number;
+    }>;
+    /**
+     * Get timing summary from results.
+     *
+     * @param timings - Array of layer timings
+     * @returns Formatted timing summary
+     */
+    static formatTimingSummary(timings: LayerTiming[]): string;
+    /**
+     * Calculate potential speedup from parallel execution.
+     *
+     * @param timings - Array of layer timings
+     * @returns Speedup metrics
+     */
+    static calculateSpeedup(timings: LayerTiming[]): {
+        sequentialTime: number;
+        parallelTime: number;
+        speedup: number;
+    };
+}
+//# sourceMappingURL=ParallelSearchExecutor.d.ts.map

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

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