@danielsimonjr/memory-mcp 9.9.0 → 10.0.0

package/dist/search/QueryPlanCache.js

@@ -0,0 +1,379 @@
+/**
+ * Query Plan Cache
+ *
+ * Phase 12 Sprint 4: Caches query analysis and planning results
+ * with LRU eviction for improved performance.
+ *
+ * @module search/QueryPlanCache
+ */
+/**
+ * Default cache options.
+ */
+const DEFAULT_OPTIONS = {
+    maxSize: 1000,
+    ttlMs: 5 * 60 * 1000, // 5 minutes
+    normalizeQueries: true,
+    enableStats: true,
+};
+/**
+ * Query Plan Cache with LRU eviction.
+ *
+ * Caches query analysis and planning results to avoid redundant computation.
+ * Uses LRU (Least Recently Used) eviction when cache is full.
+ *
+ * @example
+ * ```typescript
+ * const cache = new QueryPlanCache({ maxSize: 500 });
+ *
+ * // Cache an analysis
+ * cache.setAnalysis('Find Alice', analysis);
+ *
+ * // Retrieve cached analysis
+ * const cached = cache.getAnalysis('Find Alice');
+ * if (cached) {
+ *   console.log('Cache hit!', cached);
+ * }
+ *
+ * // Get statistics
+ * const stats = cache.getStats();
+ * console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+ * ```
+ */
+export class QueryPlanCache {
+    cache;
+    options;
+    // Statistics
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+        this.cache = new Map();
+    }
+    /**
+     * Get cached analysis for a query.
+     *
+     * @param query - The search query
+     * @returns Cached analysis or undefined if not found
+     */
+    getAnalysis(query) {
+        const entry = this.getEntry(query);
+        return entry?.analysis;
+    }
+    /**
+     * Get cached plan for a query.
+     *
+     * @param query - The search query
+     * @returns Cached plan or undefined if not found
+     */
+    getPlan(query) {
+        const entry = this.getEntry(query);
+        return entry?.plan;
+    }
+    /**
+     * Get full cached entry for a query.
+     *
+     * @param query - The search query
+     * @returns Cached entry or undefined if not found
+     */
+    getEntry(query) {
+        const key = this.normalizeQuery(query);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            if (this.options.enableStats)
+                this.misses++;
+            return undefined;
+        }
+        // Check TTL
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            if (this.options.enableStats)
+                this.misses++;
+            return undefined;
+        }
+        // Update access time and count
+        entry.lastAccessed = Date.now();
+        entry.hitCount++;
+        if (this.options.enableStats)
+            this.hits++;
+        return entry;
+    }
+    /**
+     * Cache analysis results for a query.
+     *
+     * @param query - The search query
+     * @param analysis - The analysis result to cache
+     */
+    setAnalysis(query, analysis) {
+        const key = this.normalizeQuery(query);
+        const now = Date.now();
+        const existing = this.cache.get(key);
+        if (existing) {
+            // Update existing entry
+            existing.analysis = analysis;
+            existing.lastAccessed = now;
+        }
+        else {
+            // Evict if necessary
+            this.evictIfNeeded();
+            // Create new entry
+            this.cache.set(key, {
+                normalizedQuery: key,
+                originalQuery: query,
+                analysis,
+                createdAt: now,
+                lastAccessed: now,
+                hitCount: 0,
+            });
+        }
+    }
+    /**
+     * Cache plan results for a query.
+     *
+     * @param query - The search query
+     * @param analysis - The analysis result to cache
+     * @param plan - The plan result to cache
+     */
+    setPlan(query, analysis, plan) {
+        const key = this.normalizeQuery(query);
+        const now = Date.now();
+        const existing = this.cache.get(key);
+        if (existing) {
+            // Update existing entry
+            existing.analysis = analysis;
+            existing.plan = plan;
+            existing.lastAccessed = now;
+        }
+        else {
+            // Evict if necessary
+            this.evictIfNeeded();
+            // Create new entry
+            this.cache.set(key, {
+                normalizedQuery: key,
+                originalQuery: query,
+                analysis,
+                plan,
+                createdAt: now,
+                lastAccessed: now,
+                hitCount: 0,
+            });
+        }
+    }
+    /**
+     * Check if a query is cached.
+     *
+     * @param query - The search query
+     * @returns True if cached (and not expired)
+     */
+    has(query) {
+        const key = this.normalizeQuery(query);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Invalidate a specific query from cache.
+     *
+     * @param query - The search query to invalidate
+     * @returns True if entry was found and removed
+     */
+    invalidate(query) {
+        const key = this.normalizeQuery(query);
+        return this.cache.delete(key);
+    }
+    /**
+     * Invalidate all entries matching a pattern.
+     *
+     * @param pattern - Regex pattern to match against queries
+     * @returns Number of entries invalidated
+     */
+    invalidatePattern(pattern) {
+        let count = 0;
+        for (const [key, entry] of this.cache) {
+            if (pattern.test(entry.originalQuery) || pattern.test(key)) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Clear all cache entries.
+     */
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+    /**
+     * Get cache statistics.
+     *
+     * @returns Cache statistics
+     */
+    getStats() {
+        const now = Date.now();
+        let totalAge = 0;
+        for (const entry of this.cache.values()) {
+            totalAge += now - entry.createdAt;
+        }
+        const total = this.hits + this.misses;
+        return {
+            size: this.cache.size,
+            maxSize: this.options.maxSize,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total > 0 ? this.hits / total : 0,
+            evictions: this.evictions,
+            averageEntryAgeMs: this.cache.size > 0 ? totalAge / this.cache.size : 0,
+        };
+    }
+    /**
+     * Get the current cache size.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Normalize a query for cache lookup.
+     *
+     * Normalization helps improve cache hit rate by treating
+     * similar queries as equivalent.
+     *
+     * @param query - The query to normalize
+     * @returns Normalized query string
+     */
+    normalizeQuery(query) {
+        if (!this.options.normalizeQueries) {
+            return query;
+        }
+        return query
+            .toLowerCase()
+            .trim()
+            // Normalize whitespace
+            .replace(/\s+/g, ' ')
+            // Remove punctuation that doesn't affect meaning
+            .replace(/[.,!?;:]+$/g, '')
+            // Sort operators for consistent matching
+            .replace(/\b(AND|OR|NOT)\b/gi, match => match.toUpperCase());
+    }
+    /**
+     * Check if an entry has expired.
+     * @private
+     */
+    isExpired(entry) {
+        return Date.now() - entry.createdAt > this.options.ttlMs;
+    }
+    /**
+     * Evict entries if cache is at capacity.
+     * Uses LRU (Least Recently Used) eviction.
+     * @private
+     */
+    evictIfNeeded() {
+        if (this.cache.size < this.options.maxSize) {
+            return;
+        }
+        // Find the least recently used entry
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache) {
+            // Also check for expired entries during eviction
+            if (this.isExpired(entry)) {
+                this.cache.delete(key);
+                if (this.options.enableStats)
+                    this.evictions++;
+                if (this.cache.size < this.options.maxSize)
+                    return;
+                continue;
+            }
+            if (entry.lastAccessed < oldestTime) {
+                oldestTime = entry.lastAccessed;
+                oldestKey = key;
+            }
+        }
+        // Evict the oldest entry
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            if (this.options.enableStats)
+                this.evictions++;
+        }
+    }
+    /**
+     * Clean up expired entries.
+     *
+     * Call this periodically to remove stale entries.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup() {
+        let count = 0;
+        for (const [key, entry] of this.cache) {
+            if (this.isExpired(entry)) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get all cache keys (for debugging).
+     */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Preload cache with common queries.
+     *
+     * @param queries - Array of query-analysis pairs to preload
+     */
+    preload(queries) {
+        for (const { query, analysis, plan } of queries) {
+            if (plan) {
+                this.setPlan(query, analysis, plan);
+            }
+            else {
+                this.setAnalysis(query, analysis);
+            }
+        }
+    }
+    /**
+     * Export cache entries for persistence.
+     *
+     * @returns Array of cache entries
+     */
+    export() {
+        const entries = [];
+        for (const entry of this.cache.values()) {
+            if (!this.isExpired(entry)) {
+                entries.push({ ...entry });
+            }
+        }
+        return entries;
+    }
+    /**
+     * Import cache entries from persistence.
+     *
+     * @param entries - Array of cache entries to import
+     * @param preserveTimestamps - Whether to preserve original timestamps
+     */
+    import(entries, preserveTimestamps = false) {
+        const now = Date.now();
+        for (const entry of entries) {
+            if (!preserveTimestamps) {
+                entry.createdAt = now;
+                entry.lastAccessed = now;
+            }
+            // Skip if expired
+            if (this.isExpired(entry))
+                continue;
+            // Evict if needed
+            this.evictIfNeeded();
+            this.cache.set(entry.normalizedQuery, entry);
+        }
+    }
+}

package/dist/search/ReflectionManager.d.ts

@@ -21,6 +21,31 @@ export interface ReflectionOptions {
     minResults?: number;
     /** Hybrid search options */
     searchOptions?: Partial<HybridSearchOptions>;
+    /** Phase 12 Sprint 4: Progressive limit increase factor (default: 1.5) */
+    limitIncreaseFactor?: number;
+    /** Phase 12 Sprint 4: Initial search limit (default: 10) */
+    initialLimit?: number;
+    /** Phase 12 Sprint 4: Focus on specific missing info types */
+    focusMissingTypes?: boolean;
+}
+/**
+ * Phase 12 Sprint 4: Refinement history entry.
+ */
+export interface RefinementHistoryEntry {
+    /** Iteration number (1-based) */
+    iteration: number;
+    /** Query used in this iteration */
+    query: string;
+    /** Search limit used */
+    limit: number;
+    /** Results found in this iteration */
+    resultsFound: number;
+    /** Adequacy score after this iteration */
+    adequacyScore: number;
+    /** Reason for refinement (if not final) */
+    refinementReason?: string;
+    /** Missing info types that triggered refinement */
+    missingInfoTypes?: string[];
 }
 /**
  * Result of reflection-based retrieval.
@@ -31,6 +56,10 @@ export interface ReflectionResult {
     adequate: boolean;
     refinements: string[];
     adequacyScore: number;
+    /** Phase 12 Sprint 4: Detailed refinement history */
+    refinementHistory: RefinementHistoryEntry[];
+    /** Phase 12 Sprint 4: Final search limit used */
+    finalLimit: number;
 }
 /**
  * Reflection Manager for iterative retrieval refinement.
@@ -57,8 +86,28 @@ export declare class ReflectionManager {
     constructor(hybridSearch: HybridSearchManager, analyzer: QueryAnalyzer);
     /**
      * Perform retrieval with reflection-based refinement.
+     *
+     * Phase 12 Sprint 4 enhancements:
+     * - Progressive limit increase per round
+     * - Focused query refinement based on missing information
+     * - Detailed refinement history tracking
      */
     retrieveWithReflection(graph: ReadonlyKnowledgeGraph, query: string, options?: ReflectionOptions): Promise<ReflectionResult>;
+    /**
+     * Find missing information types based on analysis requirements.
+     * @private
+     */
+    private findMissingInfoTypes;
+    /**
+     * Refine query with focus on missing information types.
+     * @private
+     */
+    private refineQueryFocused;
+    /**
+     * Get human-readable reason for refinement.
+     * @private
+     */
+    private getRefinementReason;
     /**
      * Calculate result adequacy score.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"ReflectionManager.d.ts","sourceRoot":"","sources":["../../src/search/ReflectionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,sBAAsB,EAEtB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,QAAQ;gBADR,YAAY,EAAE,mBAAmB,EACjC,QAAQ,EAAE,aAAa;IAGjC;;OAEG;IACG,sBAAsB,CAC1B,KAAK,EAAE,sBAAsB,EAC7B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IA2D5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,WAAW;CA6BpB"}
+{"version":3,"file":"ReflectionManager.d.ts","sourceRoot":"","sources":["../../src/search/ReflectionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,sBAAsB,EAEtB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;IAC5C,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,QAAQ;gBADR,YAAY,EAAE,mBAAmB,EACjC,QAAQ,EAAE,aAAa;IAGjC;;;;;;;OAOG;IACG,sBAAsB,CAC1B,KAAK,EAAE,sBAAsB,EAC7B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IAwG5B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAqC1B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,WAAW;CA6BpB"}

package/dist/search/ReflectionManager.js

@@ -34,18 +34,31 @@ export class ReflectionManager {
     }
     /**
      * Perform retrieval with reflection-based refinement.
+     *
+     * Phase 12 Sprint 4 enhancements:
+     * - Progressive limit increase per round
+     * - Focused query refinement based on missing information
+     * - Detailed refinement history tracking
      */
     async retrieveWithReflection(graph, query, options = {}) {
-        const { maxIterations = 3, adequacyThreshold = 0.7, minResults = 3, searchOptions = {}, } = options;
+        const { maxIterations = 3, adequacyThreshold = 0.7, minResults = 3, searchOptions = {}, limitIncreaseFactor = 1.5, initialLimit = 10, focusMissingTypes = true, } = options;
         const allResults = [];
         const refinements = [];
+        const refinementHistory = [];
         let currentQuery = query;
         let iteration = 0;
         let adequacyScore = 0;
+        let currentLimit = initialLimit;
+        // Get initial analysis for tracking
+        const analysis = this.analyzer.analyze(query);
         while (iteration < maxIterations) {
             iteration++;
-            // Execute search
-            const results = await this.hybridSearch.searchWithEntities(graph, currentQuery, searchOptions);
+            // Calculate current limit with progressive increase
+            currentLimit = Math.round(initialLimit * Math.pow(limitIncreaseFactor, iteration - 1));
+            // Execute search with current limit
+            const results = await this.hybridSearch.searchWithEntities(graph, currentQuery, { ...searchOptions, limit: currentLimit });
+            // Track results found this iteration (before deduplication)
+            const newResultsCount = results.filter(r => !allResults.some(existing => existing.entity.name === r.entity.name)).length;
             // Add new results (deduplicated)
             for (const result of results) {
                 if (!allResults.some(r => r.entity.name === result.entity.name)) {
@@ -53,17 +66,36 @@ export class ReflectionManager {
                 }
             }
             // Check adequacy
-            const analysis = this.analyzer.analyze(query);
-            adequacyScore = this.calculateAdequacy(allResults, analysis, minResults);
+            const iterAnalysis = this.analyzer.analyze(currentQuery);
+            adequacyScore = this.calculateAdequacy(allResults, iterAnalysis, minResults);
+            // Determine missing info types
+            const missingInfoTypes = this.findMissingInfoTypes(allResults, analysis);
+            // Record history entry
+            const historyEntry = {
+                iteration,
+                query: currentQuery,
+                limit: currentLimit,
+                resultsFound: newResultsCount,
+                adequacyScore,
+            };
             if (adequacyScore >= adequacyThreshold) {
+                refinementHistory.push(historyEntry);
                 break;
             }
             // Refine query if not adequate
-            const refinedQuery = this.refineQuery(currentQuery, allResults, analysis);
+            const refinedQuery = focusMissingTypes && missingInfoTypes.length > 0
+                ? this.refineQueryFocused(currentQuery, allResults, analysis, missingInfoTypes)
+                : this.refineQuery(currentQuery, allResults, analysis);
             if (refinedQuery === currentQuery) {
                 // No refinement possible
+                historyEntry.refinementReason = 'No further refinement possible';
+                refinementHistory.push(historyEntry);
                 break;
             }
+            // Record refinement details in history
+            historyEntry.refinementReason = this.getRefinementReason(currentQuery, refinedQuery, missingInfoTypes);
+            historyEntry.missingInfoTypes = missingInfoTypes;
+            refinementHistory.push(historyEntry);
             refinements.push(refinedQuery);
             currentQuery = refinedQuery;
         }
@@ -73,8 +105,83 @@ export class ReflectionManager {
             adequate: adequacyScore >= adequacyThreshold,
             refinements,
             adequacyScore,
+            refinementHistory,
+            finalLimit: currentLimit,
         };
     }
+    /**
+     * Find missing information types based on analysis requirements.
+     * @private
+     */
+    findMissingInfoTypes(results, analysis) {
+        const coveredTypes = new Set();
+        for (const result of results) {
+            const entityType = result.entity.entityType.toLowerCase();
+            coveredTypes.add(entityType);
+            // Map entity types to info types
+            if (['person', 'people', 'user', 'employee'].includes(entityType)) {
+                coveredTypes.add('person');
+            }
+            if (['location', 'place', 'city', 'country', 'address'].includes(entityType)) {
+                coveredTypes.add('location');
+            }
+            if (result.entity.createdAt || result.entity.lastModified) {
+                coveredTypes.add('temporal');
+            }
+            // Entity type covers 'entity' requirement
+            coveredTypes.add('entity');
+        }
+        // Find which required types are missing
+        return analysis.requiredInfoTypes.filter(type => !coveredTypes.has(type));
+    }
+    /**
+     * Refine query with focus on missing information types.
+     * @private
+     */
+    refineQueryFocused(query, results, analysis, missingInfoTypes) {
+        const additions = [];
+        for (const missingType of missingInfoTypes) {
+            switch (missingType) {
+                case 'person':
+                    additions.push('person people who');
+                    break;
+                case 'location':
+                    additions.push('location place where');
+                    break;
+                case 'temporal':
+                    additions.push('when date time');
+                    break;
+                case 'quantity':
+                    additions.push('count number how many');
+                    break;
+                case 'reason':
+                    additions.push('reason why because');
+                    break;
+            }
+        }
+        if (additions.length > 0) {
+            // Add relevant keywords to query
+            return `${query} ${additions.slice(0, 2).join(' ')}`;
+        }
+        // Fallback to standard refinement
+        return this.refineQuery(query, results, analysis);
+    }
+    /**
+     * Get human-readable reason for refinement.
+     * @private
+     */
+    getRefinementReason(_originalQuery, refinedQuery, missingInfoTypes) {
+        if (missingInfoTypes.length > 0) {
+            return `Added keywords for missing info types: ${missingInfoTypes.join(', ')}`;
+        }
+        if (refinedQuery.includes('person people')) {
+            return 'Expanded query to find person-related entities';
+        }
+        if (refinedQuery.includes('recent history timeline')) {
+            return 'Added temporal context to query';
+        }
+        return 'Broadened query by removing constraints';
+    }
     /**
      * Calculate result adequacy score.
      */

package/dist/search/index.d.ts

@@ -12,15 +12,24 @@ export { SearchSuggestions } from './SearchSuggestions.js';
 export { SavedSearchManager } from './SavedSearchManager.js';
 export { SearchManager } from './SearchManager.js';
 export { SearchFilterChain, type SearchFilters, type ValidatedPagination } from './SearchFilterChain.js';
-export { OpenAIEmbeddingService, LocalEmbeddingService, MockEmbeddingService, createEmbeddingService, } from './EmbeddingService.js';
+export { OpenAIEmbeddingService, LocalEmbeddingService, MockEmbeddingService, createEmbeddingService, l2Normalize, QUERY_PREFIX, DOCUMENT_PREFIX, type EmbeddingProgressCallback, } from './EmbeddingService.js';
+export { EmbeddingCache, DEFAULT_EMBEDDING_CACHE_OPTIONS, type EmbeddingCacheStats, type EmbeddingCacheOptions, } from './EmbeddingCache.js';
+export { IncrementalIndexer, DEFAULT_INDEXER_OPTIONS, type IndexOperationType, type IndexOperation, type IncrementalIndexerOptions, type FlushResult, } from './IncrementalIndexer.js';
 export { InMemoryVectorStore, SQLiteVectorStore, createVectorStore, cosineSimilarity, type SQLiteStorageWithEmbeddings, } from './VectorStore.js';
 export { SemanticSearch, entityToText, } from './SemanticSearch.js';
 export { TFIDFIndexManager } from './TFIDFIndexManager.js';
 export { TFIDFEventSync } from './TFIDFEventSync.js';
-export { QueryCostEstimator } from './QueryCostEstimator.js';
+export { QueryCostEstimator, type SearchLayer, type ExtendedQueryCostEstimate, type LayerRecommendationOptions, type TokenEstimationOptions, type AdaptiveDepthConfig, } from './QueryCostEstimator.js';
 export { SymbolicSearch, type SymbolicResult } from './SymbolicSearch.js';
 export { HybridSearchManager, DEFAULT_HYBRID_WEIGHTS } from './HybridSearchManager.js';
 export { QueryAnalyzer } from './QueryAnalyzer.js';
 export { QueryPlanner } from './QueryPlanner.js';
-export { ReflectionManager, type ReflectionOptions, type ReflectionResult, } from './ReflectionManager.js';
+export { ReflectionManager, type ReflectionOptions, type ReflectionResult, type RefinementHistoryEntry, } from './ReflectionManager.js';
+export { BM25Search, STOPWORDS, DEFAULT_BM25_CONFIG, type BM25DocumentEntry, type BM25Index, type BM25Config, } from './BM25Search.js';
+export { OptimizedInvertedIndex, type IndexMemoryUsage, type PostingListResult, } from './OptimizedInvertedIndex.js';
+export { HybridScorer, DEFAULT_SCORER_WEIGHTS, type SemanticSearchResult, type LexicalSearchResult, type SymbolicSearchResult, type ScoredResult, type HybridWeights, type HybridScorerOptions, } from './HybridScorer.js';
+export { ParallelSearchExecutor, type LayerTiming, type ParallelSearchResult, type ParallelSearchOptions, } from './ParallelSearchExecutor.js';
+export { EarlyTerminationManager, type AdequacyCheck, type EarlyTerminationOptions, type EarlyTerminationResult, } from './EarlyTerminationManager.js';
+export { QueryPlanCache, type CachedQueryEntry, type QueryPlanCacheStats, type QueryPlanCacheOptions, } from './QueryPlanCache.js';
+export { QuantizedVectorStore, type QuantizationParams, type QuantizedVectorStoreStats, type QuantizedSearchResult, type QuantizedVectorStoreOptions, } from './QuantizedVectorStore.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAGzG,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,2BAA2B,GACjC,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,YAAY,GACb,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAGvF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"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"}