@danielsimonjr/memory-mcp 11.0.1 → 11.1.1

package/dist/search/OptimizedInvertedIndex.js

@@ -1,358 +0,0 @@
-/**
- * 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

@@ -1,172 +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 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

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