@danielsimonjr/memory-mcp 11.0.1 → 11.1.1

package/dist/search/QueryPlanner.js

@@ -1,137 +0,0 @@
-/**
- * Query Planner
- *
- * Phase 11: Generates execution plans for queries based on analysis.
- *
- * @module search/QueryPlanner
- */
-/**
- * Query Planner generates execution plans from query analysis.
- *
- * Creates optimized plans that:
- * - Select appropriate search layers
- * - Determine execution strategy (parallel/sequential)
- * - Set up query dependencies
- * - Configure merge strategies
- *
- * @example
- * ```typescript
- * const analyzer = new QueryAnalyzer();
- * const planner = new QueryPlanner();
- *
- * const analysis = analyzer.analyze('Find projects by Alice');
- * const plan = planner.createPlan('Find projects by Alice', analysis);
- * // { originalQuery: '...', subQueries: [...], executionStrategy: 'iterative', ... }
- * ```
- */
-export class QueryPlanner {
-    /**
-     * Create an execution plan from query analysis.
-     */
-    createPlan(query, analysis) {
-        const subQueries = this.createSubQueries(query, analysis);
-        const executionStrategy = this.selectExecutionStrategy(subQueries);
-        const mergeStrategy = this.selectMergeStrategy(analysis);
-        return {
-            originalQuery: query,
-            subQueries,
-            executionStrategy,
-            mergeStrategy,
-            estimatedComplexity: this.calculateComplexity(subQueries),
-        };
-    }
-    /**
-     * Create sub-queries from analysis.
-     */
-    createSubQueries(query, analysis) {
-        const subQueries = [];
-        let id = 0;
-        // If query was decomposed, create sub-query for each part
-        if (analysis.subQueries && analysis.subQueries.length > 1) {
-            for (const sq of analysis.subQueries) {
-                subQueries.push({
-                    id: `sq_${id++}`,
-                    query: sq,
-                    targetLayer: this.selectLayer(analysis),
-                    priority: id === 1 ? 1 : 2,
-                    dependsOn: id > 1 ? [`sq_${id - 2}`] : undefined,
-                });
-            }
-        }
-        else {
-            // Single query
-            subQueries.push({
-                id: `sq_${id}`,
-                query,
-                targetLayer: this.selectLayer(analysis),
-                priority: 1,
-                filters: this.buildFilters(analysis),
-            });
-        }
-        return subQueries;
-    }
-    /**
-     * Select the most appropriate search layer.
-     */
-    selectLayer(analysis) {
-        // Use symbolic for tag/type/date filtered queries
-        if (analysis.temporalRange || analysis.requiredInfoTypes.includes('temporal')) {
-            return 'symbolic';
-        }
-        // Use semantic for complex concept queries
-        if (analysis.complexity === 'high' || analysis.questionType === 'comparative') {
-            return 'semantic';
-        }
-        // Use hybrid for balanced approach
-        return 'hybrid';
-    }
-    /**
-     * Select execution strategy based on sub-queries.
-     */
-    selectExecutionStrategy(subQueries) {
-        const hasDependencies = subQueries.some(sq => sq.dependsOn && sq.dependsOn.length > 0);
-        if (hasDependencies)
-            return 'sequential';
-        if (subQueries.length > 1)
-            return 'parallel';
-        return 'iterative';
-    }
-    /**
-     * Select merge strategy based on question type.
-     */
-    selectMergeStrategy(analysis) {
-        switch (analysis.questionType) {
-            case 'aggregation': return 'union';
-            case 'comparative': return 'intersection';
-            default: return 'weighted';
-        }
-    }
-    /**
-     * Build symbolic filters from analysis.
-     */
-    buildFilters(analysis) {
-        const filters = {};
-        let hasFilters = false;
-        if (analysis.temporalRange) {
-            filters.dateRange = {
-                start: analysis.temporalRange.start || '',
-                end: analysis.temporalRange.end || '',
-            };
-            hasFilters = true;
-        }
-        return hasFilters ? filters : undefined;
-    }
-    /**
-     * Calculate plan complexity score.
-     */
-    calculateComplexity(subQueries) {
-        let complexity = subQueries.length;
-        for (const sq of subQueries) {
-            if (sq.dependsOn)
-                complexity += sq.dependsOn.length * 0.5;
-            if (sq.filters)
-                complexity += 0.5;
-        }
-        return Math.min(complexity, 10);
-    }
-}

package/dist/search/ReflectionManager.d.ts

@@ -1,120 +0,0 @@
-/**
- * Reflection Manager
- *
- * Phase 11: Implements reflection-based iterative retrieval
- * that refines results until adequate.
- *
- * @module search/ReflectionManager
- */
-import type { ReadonlyKnowledgeGraph, HybridSearchResult, HybridSearchOptions } from '../types/index.js';
-import type { HybridSearchManager } from './HybridSearchManager.js';
-import type { QueryAnalyzer } from './QueryAnalyzer.js';
-/**
- * Options for reflection-based retrieval.
- */
-export interface ReflectionOptions {
-    /** Maximum number of reflection iterations (default: 3) */
-    maxIterations?: number;
-    /** Adequacy threshold 0-1 (default: 0.7) */
-    adequacyThreshold?: number;
-    /** Minimum results required (default: 3) */
-    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.
- */
-export interface ReflectionResult {
-    results: HybridSearchResult[];
-    iterations: number;
-    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.
- *
- * Implements the SimpleMem-inspired reflection loop:
- * 1. Execute initial search
- * 2. Check result adequacy
- * 3. If inadequate, refine query and repeat
- * 4. Combine results from all iterations
- *
- * @example
- * ```typescript
- * const reflection = new ReflectionManager(hybridSearch, analyzer);
- * const result = await reflection.retrieveWithReflection(
- *   graph,
- *   'What projects did Alice work on?',
- *   { maxIterations: 3 }
- * );
- * ```
- */
-export declare class ReflectionManager {
-    private hybridSearch;
-    private analyzer;
-    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.
-     */
-    private calculateAdequacy;
-    /**
-     * Refine query based on current results and analysis.
-     */
-    private refineQuery;
-}
-//# sourceMappingURL=ReflectionManager.d.ts.map

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

@@ -1 +0,0 @@
-{"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

@@ -1,231 +0,0 @@
-/**
- * Reflection Manager
- *
- * Phase 11: Implements reflection-based iterative retrieval
- * that refines results until adequate.
- *
- * @module search/ReflectionManager
- */
-/**
- * Reflection Manager for iterative retrieval refinement.
- *
- * Implements the SimpleMem-inspired reflection loop:
- * 1. Execute initial search
- * 2. Check result adequacy
- * 3. If inadequate, refine query and repeat
- * 4. Combine results from all iterations
- *
- * @example
- * ```typescript
- * const reflection = new ReflectionManager(hybridSearch, analyzer);
- * const result = await reflection.retrieveWithReflection(
- *   graph,
- *   'What projects did Alice work on?',
- *   { maxIterations: 3 }
- * );
- * ```
- */
-export class ReflectionManager {
-    hybridSearch;
-    analyzer;
-    constructor(hybridSearch, analyzer) {
-        this.hybridSearch = hybridSearch;
-        this.analyzer = analyzer;
-    }
-    /**
-     * 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 = {}, 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++;
-            // 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)) {
-                    allResults.push(result);
-                }
-            }
-            // Check adequacy
-            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 = 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;
-        }
-        return {
-            results: allResults.sort((a, b) => b.scores.combined - a.scores.combined),
-            iterations: iteration,
-            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.
-     */
-    calculateAdequacy(results, analysis, minResults) {
-        let score = 0;
-        const weights = { quantity: 0.4, diversity: 0.3, relevance: 0.3 };
-        // Quantity: Do we have enough results?
-        const quantityScore = Math.min(results.length / minResults, 1);
-        score += quantityScore * weights.quantity;
-        // Diversity: Do results cover different entity types?
-        const types = new Set(results.map(r => r.entity.entityType));
-        const diversityScore = Math.min(types.size / 3, 1);
-        score += diversityScore * weights.diversity;
-        // Relevance: Average combined score
-        const avgScore = results.length > 0
-            ? results.reduce((sum, r) => sum + r.scores.combined, 0) / results.length
-            : 0;
-        score += avgScore * weights.relevance;
-        // Suppress unused parameter warning - analysis reserved for future enhancements
-        void analysis;
-        return score;
-    }
-    /**
-     * Refine query based on current results and analysis.
-     */
-    refineQuery(query, results, analysis) {
-        // Check what information types are missing
-        const coveredTypes = new Set();
-        for (const result of results) {
-            coveredTypes.add(result.entity.entityType.toLowerCase());
-        }
-        // If looking for persons but no person results, refine
-        if (analysis.requiredInfoTypes.includes('person') && !coveredTypes.has('person')) {
-            return `${query} person people`;
-        }
-        // If temporal query but no temporal context, add time hint
-        if (analysis.temporalRange && results.length < 3) {
-            return `${query} recent history timeline`;
-        }
-        // Broaden query by removing constraints
-        const broader = query.replace(/\b(only|just|exactly|specific)\b/gi, '');
-        if (broader !== query) {
-            return broader.trim();
-        }
-        return query;
-    }
-}

package/dist/search/SymbolicSearch.d.ts

@@ -1,61 +0,0 @@
-/**
- * Symbolic Search Layer
- *
- * Phase 11: Provides metadata-based filtering using structured predicates.
- * Part of the three-layer hybrid search architecture.
- *
- * @module search/SymbolicSearch
- */
-import type { Entity, SymbolicFilters } from '../types/index.js';
-/**
- * Result from symbolic search with match score.
- */
-export interface SymbolicResult {
-    entity: Entity;
-    score: number;
-    matchedFilters: string[];
-}
-/**
- * Symbolic Search provides metadata-based filtering.
- *
- * Filters entities using structured predicates on tags, types,
- * dates, importance, and hierarchy.
- *
- * @example
- * ```typescript
- * const symbolic = new SymbolicSearch();
- * const results = symbolic.search(entities, {
- *   tags: ['important'],
- *   entityTypes: ['person'],
- *   importance: { min: 5 }
- * });
- * ```
- */
-export declare class SymbolicSearch {
-    /**
-     * Filter entities using structured metadata predicates.
-     * All filters are AND-combined.
-     *
-     * @param entities - Entities to filter
-     * @param filters - Symbolic filter criteria
-     * @returns Filtered entities with match scores
-     */
-    search(entities: readonly Entity[], filters: SymbolicFilters): SymbolicResult[];
-    /**
-     * Evaluate all filters against an entity.
-     */
-    private evaluateFilters;
-    /**
-     * Get entities matching a specific tag.
-     */
-    byTag(entities: readonly Entity[], tag: string): Entity[];
-    /**
-     * Get entities of a specific type.
-     */
-    byType(entities: readonly Entity[], entityType: string): Entity[];
-    /**
-     * Get entities within importance range.
-     */
-    byImportance(entities: readonly Entity[], min: number, max: number): Entity[];
-}
-//# sourceMappingURL=SymbolicSearch.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"SymbolicSearch.d.ts","sourceRoot":"","sources":["../../src/search/SymbolicSearch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,EAAE;IAc/E;;OAEG;IACH,OAAO,CAAC,eAAe;IAyGvB;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAMzD;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAMjE;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;CAM9E"}