@danielsimonjr/memory-mcp 12.2.3 → 12.5.2

package/dist/search/FuzzySearch.js

@@ -1,312 +0,0 @@
-/**
- * Fuzzy Search
- *
- * Search with typo tolerance using Levenshtein distance similarity.
- * Uses workerpool for parallel processing on large datasets.
- *
- * @module search/FuzzySearch
- */
-import { levenshteinDistance } from '../utils/index.js';
-import { SEARCH_LIMITS } from '../utils/constants.js';
-import { SearchFilterChain } from './SearchFilterChain.js';
-import workerpool from '@danielsimonjr/workerpool/modern';
-import { fileURLToPath } from 'url';
-import { dirname, join, sep } from 'path';
-/**
- * Default fuzzy search similarity threshold (70% match required).
- * Lower values are more permissive (more typos tolerated).
- * Higher values are stricter (fewer typos tolerated).
- */
-export const DEFAULT_FUZZY_THRESHOLD = 0.7;
-/**
- * Phase 4 Sprint 3: Maximum cache size to prevent memory bloat.
- */
-const FUZZY_CACHE_MAX_SIZE = 100;
-/**
- * Phase 4 Sprint 3: Cache TTL in milliseconds (5 minutes).
- */
-const FUZZY_CACHE_TTL_MS = 5 * 60 * 1000;
-/**
- * Phase 7 Sprint 3: Minimum number of entities to activate worker pool.
- */
-const WORKER_MIN_ENTITIES = 500;
-/**
- * Phase 7 Sprint 3: Maximum threshold for worker pool activation.
- * Higher thresholds have fewer matches, so single-threaded is faster.
- */
-const WORKER_MAX_THRESHOLD = 0.8;
-/**
- * Performs fuzzy search with configurable similarity threshold.
- */
-export class FuzzySearch {
-    storage;
-    /**
-     * Phase 4 Sprint 3: Result cache for fuzzy search.
-     * Maps cache key -> cached entity names.
-     */
-    fuzzyResultCache = new Map();
-    /**
-     * Phase 8: Worker pool using workerpool library.
-     * Initialized lazily when needed.
-     */
-    workerPool = null;
-    /**
-     * Phase 7 Sprint 3: Path to the worker script.
-     */
-    workerPath;
-    /**
-     * Phase 8: Whether to use worker pool for parallel processing.
-     * Can be disabled for testing or when workers are not available.
-     */
-    useWorkerPool;
-    constructor(storage, options = {}) {
-        this.storage = storage;
-        this.useWorkerPool = options.useWorkerPool ?? true;
-        // Calculate worker path using ESM module resolution
-        const currentFileUrl = import.meta.url;
-        const currentDir = dirname(fileURLToPath(currentFileUrl));
-        // Check if we're running from src/ (during tests) or dist/ (production)
-        const isRunningFromSrc = currentDir.includes(`${sep}src${sep}`);
-        if (isRunningFromSrc) {
-            // During tests, worker is in dist/workers/ relative to project root
-            const projectRoot = join(currentDir, '..', '..');
-            this.workerPath = join(projectRoot, 'dist', 'workers', 'levenshteinWorker.js');
-        }
-        else {
-            // In production, worker is in dist/workers/ relative to current dist/search/
-            this.workerPath = join(currentDir, '..', 'workers', 'levenshteinWorker.js');
-        }
-    }
-    /**
-     * Phase 4 Sprint 3: Generate cache key for fuzzy search parameters.
-     */
-    generateCacheKey(query, threshold, tags, minImportance, maxImportance, offset, limit) {
-        return JSON.stringify({
-            q: query.toLowerCase(),
-            t: threshold,
-            tags: tags?.sort().join(',') ?? '',
-            min: minImportance,
-            max: maxImportance,
-            off: offset,
-            lim: limit,
-        });
-    }
-    /**
-     * Phase 4 Sprint 3: Clear the fuzzy search cache.
-     */
-    clearCache() {
-        this.fuzzyResultCache.clear();
-    }
-    /**
-     * Phase 4 Sprint 3: Invalidate stale cache entries.
-     */
-    cleanupCache() {
-        const now = Date.now();
-        const entries = Array.from(this.fuzzyResultCache.entries());
-        // Remove expired entries
-        for (const [key, entry] of entries) {
-            if (now - entry.timestamp > FUZZY_CACHE_TTL_MS) {
-                this.fuzzyResultCache.delete(key);
-            }
-        }
-        // If still over limit, remove oldest entries
-        if (this.fuzzyResultCache.size > FUZZY_CACHE_MAX_SIZE) {
-            const sortedEntries = entries
-                .filter(([k]) => this.fuzzyResultCache.has(k))
-                .sort((a, b) => a[1].timestamp - b[1].timestamp);
-            const toRemove = sortedEntries.slice(0, this.fuzzyResultCache.size - FUZZY_CACHE_MAX_SIZE);
-            for (const [key] of toRemove) {
-                this.fuzzyResultCache.delete(key);
-            }
-        }
-    }
-    /**
-     * Fuzzy search for entities with typo tolerance and pagination.
-     *
-     * Uses Levenshtein distance to calculate similarity between strings.
-     * Matches if similarity >= threshold (0.0 to 1.0).
-     *
-     * Phase 4 Sprint 3: Implements result caching for repeated queries.
-     *
-     * @param query - Search query
-     * @param threshold - Similarity threshold (0.0 to 1.0), default DEFAULT_FUZZY_THRESHOLD
-     * @param tags - Optional tags filter
-     * @param minImportance - Optional minimum importance
-     * @param maxImportance - Optional maximum importance
-     * @param offset - Number of results to skip (default: 0)
-     * @param limit - Maximum number of results (default: 50, max: 200)
-     * @returns Filtered knowledge graph with fuzzy matches and pagination applied
-     */
-    async fuzzySearch(query, threshold = DEFAULT_FUZZY_THRESHOLD, tags, minImportance, maxImportance, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
-        const graph = await this.storage.loadGraph();
-        const queryLower = query.toLowerCase();
-        // Phase 4 Sprint 3: Generate cache key and check cache
-        const cacheKey = this.generateCacheKey(query, threshold, tags, minImportance, maxImportance, offset, limit);
-        const cached = this.fuzzyResultCache.get(cacheKey);
-        // Check if cache is valid (entity count hasn't changed)
-        if (cached && cached.entityCount === graph.entities.length) {
-            const now = Date.now();
-            if (now - cached.timestamp < FUZZY_CACHE_TTL_MS) {
-                // Return cached results
-                const cachedNameSet = new Set(cached.entityNames);
-                const cachedEntities = graph.entities.filter(e => cachedNameSet.has(e.name));
-                const cachedEntityNames = new Set(cached.entityNames);
-                const cachedRelations = graph.relations.filter(r => cachedEntityNames.has(r.from) && cachedEntityNames.has(r.to));
-                return { entities: cachedEntities, relations: cachedRelations };
-            }
-        }
-        // Phase 7 Sprint 3: Use worker pool for large graphs with low thresholds
-        // Phase 8: Respect useWorkerPool flag for testing
-        const shouldUseWorkers = this.useWorkerPool &&
-            graph.entities.length >= WORKER_MIN_ENTITIES &&
-            threshold < WORKER_MAX_THRESHOLD;
-        let fuzzyMatched;
-        if (shouldUseWorkers) {
-            fuzzyMatched = await this.searchWithWorkers(query, threshold, graph.entities);
-        }
-        else {
-            // Perform single-threaded fuzzy search
-            fuzzyMatched = this.performFuzzyMatch(graph.entities, queryLower, threshold);
-        }
-        // Apply tag and importance filters using SearchFilterChain
-        const filters = { tags, minImportance, maxImportance };
-        const filteredEntities = SearchFilterChain.applyFilters(fuzzyMatched, filters);
-        // Apply pagination using SearchFilterChain
-        const pagination = SearchFilterChain.validatePagination(offset, limit);
-        const paginatedEntities = SearchFilterChain.paginate(filteredEntities, pagination);
-        // Phase 4 Sprint 3: Cache the results
-        this.fuzzyResultCache.set(cacheKey, {
-            entityNames: paginatedEntities.map(e => e.name),
-            entityCount: graph.entities.length,
-            timestamp: Date.now(),
-        });
-        // Cleanup old cache entries periodically
-        if (this.fuzzyResultCache.size > FUZZY_CACHE_MAX_SIZE / 2) {
-            this.cleanupCache();
-        }
-        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
-        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
-        return {
-            entities: paginatedEntities,
-            relations: filteredRelations,
-        };
-    }
-    /**
-     * Phase 4 Sprint 3: Perform the actual fuzzy matching logic.
-     * Extracted from fuzzySearch for cleaner code structure.
-     */
-    performFuzzyMatch(entities, queryLower, threshold) {
-        return entities.filter(e => {
-            const lowercased = this.storage.getLowercased(e.name);
-            // Check name match (use pre-computed lowercase)
-            const nameLower = lowercased?.name ?? e.name.toLowerCase();
-            if (this.isFuzzyMatchLower(nameLower, queryLower, threshold))
-                return true;
-            // Check type match (use pre-computed lowercase)
-            const typeLower = lowercased?.entityType ?? e.entityType.toLowerCase();
-            if (this.isFuzzyMatchLower(typeLower, queryLower, threshold))
-                return true;
-            // Check observations (use pre-computed lowercase array)
-            const obsLower = lowercased?.observations ?? e.observations.map(o => o.toLowerCase());
-            return obsLower.some(o => 
-            // For observations, split into words and check each word
-            o
-                .split(/\s+/)
-                .some(word => this.isFuzzyMatchLower(word, queryLower, threshold)) ||
-                // Also check if the observation contains the query
-                this.isFuzzyMatchLower(o, queryLower, threshold));
-        });
-    }
-    /**
-     * Check if two already-lowercase strings match with fuzzy logic.
-     *
-     * OPTIMIZED: Skips toLowerCase() calls when strings are already lowercase.
-     *
-     * @param s1 - First string (already lowercase)
-     * @param s2 - Second string (already lowercase)
-     * @param threshold - Similarity threshold (0.0 to 1.0)
-     * @returns True if strings match fuzzily
-     */
-    isFuzzyMatchLower(s1, s2, threshold = 0.7) {
-        // Exact match
-        if (s1 === s2)
-            return true;
-        // One contains the other
-        if (s1.includes(s2) || s2.includes(s1))
-            return true;
-        // Calculate similarity using Levenshtein distance
-        const distance = levenshteinDistance(s1, s2);
-        const maxLength = Math.max(s1.length, s2.length);
-        const similarity = 1 - distance / maxLength;
-        return similarity >= threshold;
-    }
-    /**
-     * Phase 8: Perform fuzzy search using workerpool for parallel processing.
-     *
-     * Splits entities into chunks and processes them in parallel using worker threads.
-     * Falls back to single-threaded search if worker execution fails.
-     *
-     * @param query - Search query
-     * @param threshold - Similarity threshold
-     * @param entities - Entities to search
-     * @returns Array of matched entities
-     */
-    async searchWithWorkers(query, threshold, entities) {
-        try {
-            // Initialize worker pool lazily using workerpool
-            if (!this.workerPool) {
-                // Enable ESM module support for Node.js 20+
-                // The 'type: module' option is needed for ESM workers but may not be in @types/node
-                const workerThreadOpts = { type: 'module' };
-                this.workerPool = workerpool.pool(this.workerPath, {
-                    maxWorkers: Math.max(1, workerpool.cpus - 1),
-                    workerType: 'thread',
-                    workerThreadOpts,
-                });
-            }
-            // Split entities into chunks based on CPU count
-            const numWorkers = Math.max(1, workerpool.cpus - 1);
-            const chunkSize = Math.ceil(entities.length / numWorkers);
-            const chunks = [];
-            for (let i = 0; i < entities.length; i += chunkSize) {
-                chunks.push(entities.slice(i, i + chunkSize));
-            }
-            // Prepare worker inputs with lowercased data
-            const workerInputs = chunks.map(chunk => ({
-                query,
-                threshold,
-                entities: chunk.map(e => ({
-                    name: e.name,
-                    nameLower: e.name.toLowerCase(),
-                    observations: e.observations.map(o => o.toLowerCase()),
-                })),
-            }));
-            // Execute all chunks in parallel using workerpool with timeout
-            const WORKER_TIMEOUT_MS = 30000; // 30 seconds
-            const results = await Promise.all(workerInputs.map(input => this.workerPool.exec('searchEntities', [input])
-                .timeout(WORKER_TIMEOUT_MS)));
-            // Flatten results and extract matched entity names
-            const matchedNames = new Set(results.flat().map(r => r.name));
-            // Return entities that matched
-            return entities.filter(e => matchedNames.has(e.name));
-        }
-        catch (error) {
-            // Worker execution failed - fall back to single-threaded mode
-            console.warn(`Worker pool execution failed, falling back to single-threaded fuzzy search: ${error instanceof Error ? error.message : String(error)}`);
-            // Use the existing single-threaded implementation
-            const queryLower = query.toLowerCase();
-            return this.performFuzzyMatch(entities, queryLower, threshold);
-        }
-    }
-    /**
-     * Phase 8: Shutdown the worker pool and clean up resources.
-     *
-     * Should be called when FuzzySearch is no longer needed.
-     */
-    async shutdown() {
-        if (this.workerPool) {
-            await this.workerPool.terminate();
-            this.workerPool = null;
-        }
-    }
-}

package/dist/search/RankedSearch.d.ts

@@ -1,71 +0,0 @@
-/**
- * Ranked Search
- *
- * TF-IDF relevance-based search with scoring and pre-calculated indexes.
- *
- * @module search/RankedSearch
- */
-import type { SearchResult } from '../types/index.js';
-import type { GraphStorage } from '../core/GraphStorage.js';
-/**
- * Performs TF-IDF ranked search with optional pre-calculated indexes.
- */
-export declare class RankedSearch {
-    private storage;
-    private indexManager;
-    /**
-     * Phase 4 Sprint 2: Fallback token cache for entities.
-     * Maps entity name -> pre-tokenized entity data.
-     * Invalidated when graph changes (detected by entity count mismatch).
-     */
-    private fallbackTokenCache;
-    private cachedEntityCount;
-    constructor(storage: GraphStorage, storageDir?: string);
-    /**
-     * Phase 4 Sprint 2: Clear the fallback token cache.
-     * Called when graph changes are detected or explicitly by external code.
-     */
-    clearTokenCache(): void;
-    /**
-     * Initialize and build the TF-IDF index for fast searches.
-     *
-     * Should be called after graph changes to keep index up-to-date.
-     */
-    buildIndex(): Promise<void>;
-    /**
-     * Update the index incrementally after entity changes.
-     *
-     * @param changedEntityNames - Names of entities that were created, updated, or deleted
-     */
-    updateIndex(changedEntityNames: Set<string>): Promise<void>;
-    /**
-     * Load the TF-IDF index from disk if available.
-     */
-    private ensureIndexLoaded;
-    /**
-     * Search with TF-IDF relevance ranking.
-     *
-     * Uses pre-calculated index if available, falls back to on-the-fly calculation.
-     *
-     * @param query - Search query
-     * @param tags - Optional tags filter
-     * @param minImportance - Optional minimum importance
-     * @param maxImportance - Optional maximum importance
-     * @param limit - Maximum results to return (default 50, max 200)
-     * @returns Array of search results sorted by relevance
-     */
-    searchNodesRanked(query: string, tags?: string[], minImportance?: number, maxImportance?: number, limit?: number): Promise<SearchResult[]>;
-    /**
-     * Search using pre-calculated TF-IDF index (fast path).
-     */
-    private searchWithIndex;
-    /**
-     * Search without index (on-the-fly calculation, slow path).
-     *
-     * OPTIMIZED: Phase 4 Sprint 2 - Uses fallback token cache to avoid
-     * repeated tokenization of entities. Pre-tokenizes all documents once
-     * and caches for subsequent searches.
-     */
-    private searchWithoutIndex;
-}
-//# sourceMappingURL=RankedSearch.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"RankedSearch.d.ts","sourceRoot":"","sources":["../../src/search/RankedSearch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAU,YAAY,EAA+B,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAM5D;;GAEG;AACH,qBAAa,YAAY;IAYrB,OAAO,CAAC,OAAO;IAXjB,OAAO,CAAC,YAAY,CAAkC;IAEtD;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAA2C;IACrE,OAAO,CAAC,iBAAiB,CAAa;gBAG5B,OAAO,EAAE,YAAY,EAC7B,UAAU,CAAC,EAAE,MAAM;IAQrB;;;OAGG;IACH,eAAe,IAAI,IAAI;IAKvB;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUjC;;;;OAIG;IACG,WAAW,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjE;;OAEG;YACW,iBAAiB;IAe/B;;;;;;;;;;;OAWG;IACG,iBAAiB,CACrB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC,YAAY,EAAE,CAAC;IAsB1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAgEvB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;CAqF3B"}

package/dist/search/RankedSearch.js

@@ -1,238 +0,0 @@
-/**
- * Ranked Search
- *
- * TF-IDF relevance-based search with scoring and pre-calculated indexes.
- *
- * @module search/RankedSearch
- */
-import { calculateTF, calculateIDFFromTokenSets, tokenize } from '../utils/index.js';
-import { SEARCH_LIMITS } from '../utils/constants.js';
-import { TFIDFIndexManager } from './TFIDFIndexManager.js';
-import { SearchFilterChain } from './SearchFilterChain.js';
-/**
- * Performs TF-IDF ranked search with optional pre-calculated indexes.
- */
-export class RankedSearch {
-    storage;
-    indexManager = null;
-    /**
-     * Phase 4 Sprint 2: Fallback token cache for entities.
-     * Maps entity name -> pre-tokenized entity data.
-     * Invalidated when graph changes (detected by entity count mismatch).
-     */
-    fallbackTokenCache = new Map();
-    cachedEntityCount = 0;
-    constructor(storage, storageDir) {
-        this.storage = storage;
-        // Initialize index manager if storage directory is provided
-        if (storageDir) {
-            this.indexManager = new TFIDFIndexManager(storageDir);
-        }
-    }
-    /**
-     * Phase 4 Sprint 2: Clear the fallback token cache.
-     * Called when graph changes are detected or explicitly by external code.
-     */
-    clearTokenCache() {
-        this.fallbackTokenCache.clear();
-        this.cachedEntityCount = 0;
-    }
-    /**
-     * Initialize and build the TF-IDF index for fast searches.
-     *
-     * Should be called after graph changes to keep index up-to-date.
-     */
-    async buildIndex() {
-        if (!this.indexManager) {
-            throw new Error('Index manager not initialized. Provide storageDir to constructor.');
-        }
-        const graph = await this.storage.loadGraph();
-        await this.indexManager.buildIndex(graph);
-        await this.indexManager.saveIndex();
-    }
-    /**
-     * Update the index incrementally after entity changes.
-     *
-     * @param changedEntityNames - Names of entities that were created, updated, or deleted
-     */
-    async updateIndex(changedEntityNames) {
-        if (!this.indexManager) {
-            return; // No index manager, skip
-        }
-        const graph = await this.storage.loadGraph();
-        await this.indexManager.updateIndex(graph, changedEntityNames);
-        await this.indexManager.saveIndex();
-    }
-    /**
-     * Load the TF-IDF index from disk if available.
-     */
-    async ensureIndexLoaded() {
-        if (!this.indexManager) {
-            return null;
-        }
-        // Return cached index if already loaded
-        const cached = this.indexManager.getIndex();
-        if (cached) {
-            return cached;
-        }
-        // Try to load from disk
-        return await this.indexManager.loadIndex();
-    }
-    /**
-     * Search with TF-IDF relevance ranking.
-     *
-     * Uses pre-calculated index if available, falls back to on-the-fly calculation.
-     *
-     * @param query - Search query
-     * @param tags - Optional tags filter
-     * @param minImportance - Optional minimum importance
-     * @param maxImportance - Optional maximum importance
-     * @param limit - Maximum results to return (default 50, max 200)
-     * @returns Array of search results sorted by relevance
-     */
-    async searchNodesRanked(query, tags, minImportance, maxImportance, limit = SEARCH_LIMITS.DEFAULT) {
-        // Enforce maximum search limit
-        const effectiveLimit = Math.min(limit, SEARCH_LIMITS.MAX);
-        const graph = await this.storage.loadGraph();
-        // Apply tag and importance filters using SearchFilterChain
-        const filters = { tags, minImportance, maxImportance };
-        const filteredEntities = SearchFilterChain.applyFilters(graph.entities, filters);
-        // Try to use pre-calculated index
-        const index = await this.ensureIndexLoaded();
-        const queryTerms = tokenize(query);
-        if (index) {
-            // Use pre-calculated index for fast search
-            return this.searchWithIndex(filteredEntities, queryTerms, index, effectiveLimit);
-        }
-        else {
-            // Fall back to on-the-fly calculation
-            return this.searchWithoutIndex(filteredEntities, queryTerms, effectiveLimit);
-        }
-    }
-    /**
-     * Search using pre-calculated TF-IDF index (fast path).
-     */
-    searchWithIndex(entities, queryTerms, index, limit) {
-        const results = [];
-        for (const entity of entities) {
-            const docVector = index.documents.get(entity.name);
-            if (!docVector) {
-                continue; // Entity not in index
-            }
-            // Calculate total terms in document (sum of all term frequencies)
-            const totalTerms = Object.values(docVector.terms).reduce((sum, count) => sum + count, 0);
-            if (totalTerms === 0)
-                continue;
-            // Calculate score using pre-calculated term frequencies and IDF
-            let totalScore = 0;
-            const matchedFields = {};
-            for (const term of queryTerms) {
-                const termCount = docVector.terms[term] || 0;
-                const idf = index.idf.get(term) || 0;
-                // Calculate TF-IDF: (termCount / totalTerms) * IDF
-                const tf = termCount / totalTerms;
-                const tfidf = tf * idf;
-                totalScore += tfidf;
-                // Track which fields matched
-                if (termCount > 0) {
-                    if (entity.name.toLowerCase().includes(term)) {
-                        matchedFields.name = true;
-                    }
-                    if (entity.entityType.toLowerCase().includes(term)) {
-                        matchedFields.entityType = true;
-                    }
-                    const matchedObs = entity.observations.filter(o => o.toLowerCase().includes(term));
-                    if (matchedObs.length > 0) {
-                        matchedFields.observations = matchedObs;
-                    }
-                }
-            }
-            // Only include entities with non-zero scores
-            if (totalScore > 0) {
-                results.push({
-                    entity,
-                    score: totalScore,
-                    matchedFields,
-                });
-            }
-        }
-        // Sort by score descending and apply limit
-        return results
-            .sort((a, b) => b.score - a.score)
-            .slice(0, limit);
-    }
-    /**
-     * Search without index (on-the-fly calculation, slow path).
-     *
-     * OPTIMIZED: Phase 4 Sprint 2 - Uses fallback token cache to avoid
-     * repeated tokenization of entities. Pre-tokenizes all documents once
-     * and caches for subsequent searches.
-     */
-    searchWithoutIndex(entities, queryTerms, limit) {
-        const results = [];
-        // Phase 4 Sprint 2: Check if cache needs invalidation
-        if (entities.length !== this.cachedEntityCount) {
-            this.clearTokenCache();
-            this.cachedEntityCount = entities.length;
-        }
-        // Phase 4 Sprint 2: Get or compute tokenized data for each entity
-        const documentData = entities.map(e => {
-            // Check cache first
-            const cached = this.fallbackTokenCache.get(e.name);
-            if (cached) {
-                return cached;
-            }
-            // Compute and cache tokenized data
-            const text = [e.name, e.entityType, ...e.observations].join(' ');
-            const tokens = tokenize(text);
-            const tokenized = {
-                entity: e,
-                text,
-                tokens,
-                tokenSet: new Set(tokens),
-            };
-            this.fallbackTokenCache.set(e.name, tokenized);
-            return tokenized;
-        });
-        // Pre-compute token sets for IDF calculation (O(1) lookup per document)
-        const tokenSets = documentData.map(d => d.tokenSet);
-        for (const docData of documentData) {
-            const { entity, text } = docData;
-            // Calculate score for each query term
-            let totalScore = 0;
-            const matchedFields = {};
-            for (const term of queryTerms) {
-                // Calculate TF using pre-tokenized tokens
-                const tf = calculateTF(term, text);
-                // Calculate IDF using pre-computed token sets (O(1) per document)
-                const idf = calculateIDFFromTokenSets(term, tokenSets);
-                // TF-IDF score
-                const score = tf * idf;
-                totalScore += score;
-                // Track which fields matched
-                if (entity.name.toLowerCase().includes(term)) {
-                    matchedFields.name = true;
-                }
-                if (entity.entityType.toLowerCase().includes(term)) {
-                    matchedFields.entityType = true;
-                }
-                const matchedObs = entity.observations.filter(o => o.toLowerCase().includes(term));
-                if (matchedObs.length > 0) {
-                    matchedFields.observations = matchedObs;
-                }
-            }
-            // Only include entities with non-zero scores
-            if (totalScore > 0) {
-                results.push({
-                    entity,
-                    score: totalScore,
-                    matchedFields,
-                });
-            }
-        }
-        // Sort by score descending and apply limit
-        return results
-            .sort((a, b) => b.score - a.score)
-            .slice(0, limit);
-    }
-}