@danielsimonjr/memoryjs 1.0.0

package/dist/search/HybridScorer.js

@@ -0,0 +1,258 @@
+/**
+ * Hybrid Scorer
+ *
+ * Combines semantic, lexical, and symbolic search scores with
+ * min-max normalization and configurable weights.
+ *
+ * Phase 12 Sprint 3: Search Algorithm Optimization
+ *
+ * @module search/HybridScorer
+ */
+/**
+ * Default weights for hybrid search.
+ */
+export const DEFAULT_SCORER_WEIGHTS = {
+    semantic: 0.4,
+    lexical: 0.4,
+    symbolic: 0.2,
+};
+/**
+ * HybridScorer combines multiple search signals using min-max normalization.
+ *
+ * Features:
+ * 1. Min-max normalization brings all scores to 0-1 range
+ * 2. Configurable weights for each layer
+ * 3. Handles missing layers gracefully (redistributes weights)
+ * 4. Tracks which layers contributed to each result
+ *
+ * @example
+ * ```typescript
+ * const scorer = new HybridScorer({
+ *   weights: { semantic: 0.5, lexical: 0.3, symbolic: 0.2 }
+ * });
+ *
+ * const results = scorer.combine(
+ *   semanticResults,
+ *   lexicalResults,
+ *   symbolicResults,
+ *   entityMap
+ * );
+ * ```
+ */
+export class HybridScorer {
+    weights;
+    minScore;
+    normalizeWeights;
+    constructor(options = {}) {
+        this.weights = {
+            ...DEFAULT_SCORER_WEIGHTS,
+            ...options.weights,
+        };
+        this.minScore = options.minScore ?? 0;
+        this.normalizeWeights = options.normalizeWeights ?? true;
+    }
+    /**
+     * Get current weights configuration.
+     */
+    getWeights() {
+        return { ...this.weights };
+    }
+    /**
+     * Update weights configuration.
+     */
+    setWeights(weights) {
+        this.weights = { ...this.weights, ...weights };
+    }
+    /**
+     * Perform min-max normalization on scores.
+     *
+     * Formula: normalized = (x - min) / (max - min)
+     *
+     * @param scores - Map of entity name to raw score
+     * @returns Map of entity name to normalized score (0-1)
+     */
+    minMaxNormalize(scores) {
+        if (scores.size === 0) {
+            return new Map();
+        }
+        // Find min and max
+        let min = Infinity;
+        let max = -Infinity;
+        for (const score of scores.values()) {
+            if (score < min)
+                min = score;
+            if (score > max)
+                max = score;
+        }
+        // Handle edge case where all scores are the same
+        if (max === min) {
+            const normalized = new Map();
+            for (const name of scores.keys()) {
+                // If all scores are zero, keep them zero; otherwise normalize to 1
+                normalized.set(name, max === 0 ? 0 : 1);
+            }
+            return normalized;
+        }
+        // Normalize
+        const range = max - min;
+        const normalized = new Map();
+        for (const [name, score] of scores) {
+            normalized.set(name, (score - min) / range);
+        }
+        return normalized;
+    }
+    /**
+     * Combine results from all three search layers.
+     *
+     * @param semanticResults - Results from semantic search
+     * @param lexicalResults - Results from lexical search
+     * @param symbolicResults - Results from symbolic search
+     * @param entityMap - Map of entity names to Entity objects
+     * @returns Array of combined results sorted by score
+     */
+    combine(semanticResults, lexicalResults, symbolicResults, entityMap) {
+        // Build score maps
+        const semanticScores = new Map();
+        for (const result of semanticResults) {
+            semanticScores.set(result.entityName, result.similarity);
+        }
+        const lexicalScores = new Map();
+        for (const result of lexicalResults) {
+            lexicalScores.set(result.entityName, result.score);
+        }
+        const symbolicScores = new Map();
+        for (const result of symbolicResults) {
+            symbolicScores.set(result.entityName, result.score);
+        }
+        // Normalize scores
+        const normalizedSemantic = this.minMaxNormalize(semanticScores);
+        const normalizedLexical = this.minMaxNormalize(lexicalScores);
+        const normalizedSymbolic = this.minMaxNormalize(symbolicScores);
+        // Calculate effective weights
+        let effectiveWeights = { ...this.weights };
+        if (this.normalizeWeights) {
+            effectiveWeights = this.getNormalizedWeights(semanticResults.length > 0, lexicalResults.length > 0, symbolicResults.length > 0);
+        }
+        // Collect all unique entity names
+        const allNames = new Set([
+            ...normalizedSemantic.keys(),
+            ...normalizedLexical.keys(),
+            ...normalizedSymbolic.keys(),
+        ]);
+        // Calculate combined scores
+        const results = [];
+        for (const entityName of allNames) {
+            const entity = entityMap.get(entityName);
+            if (!entity)
+                continue;
+            const semanticScore = normalizedSemantic.get(entityName) ?? 0;
+            const lexicalScore = normalizedLexical.get(entityName) ?? 0;
+            const symbolicScore = normalizedSymbolic.get(entityName) ?? 0;
+            // Calculate weighted combination
+            const combined = semanticScore * effectiveWeights.semantic +
+                lexicalScore * effectiveWeights.lexical +
+                symbolicScore * effectiveWeights.symbolic;
+            // Track matched layers
+            const matchedLayers = [];
+            const rawScores = {};
+            if (semanticScores.has(entityName)) {
+                matchedLayers.push('semantic');
+                rawScores.semantic = semanticScores.get(entityName);
+            }
+            if (lexicalScores.has(entityName)) {
+                matchedLayers.push('lexical');
+                rawScores.lexical = lexicalScores.get(entityName);
+            }
+            if (symbolicScores.has(entityName)) {
+                matchedLayers.push('symbolic');
+                rawScores.symbolic = symbolicScores.get(entityName);
+            }
+            // Skip if below minimum score or no layers matched
+            if (combined < this.minScore || matchedLayers.length === 0) {
+                continue;
+            }
+            results.push({
+                entityName,
+                entity,
+                scores: {
+                    semantic: semanticScore,
+                    lexical: lexicalScore,
+                    symbolic: symbolicScore,
+                    combined,
+                },
+                matchedLayers,
+                rawScores,
+            });
+        }
+        // Sort by combined score descending
+        return results.sort((a, b) => b.scores.combined - a.scores.combined);
+    }
+    /**
+     * Get weights normalized to sum to 1, redistributing for missing layers.
+     *
+     * @param hasSemantic - Whether semantic results are available
+     * @param hasLexical - Whether lexical results are available
+     * @param hasSymbolic - Whether symbolic results are available
+     * @returns Normalized weights
+     */
+    getNormalizedWeights(hasSemantic, hasLexical, hasSymbolic) {
+        let totalActiveWeight = 0;
+        if (hasSemantic)
+            totalActiveWeight += this.weights.semantic;
+        if (hasLexical)
+            totalActiveWeight += this.weights.lexical;
+        if (hasSymbolic)
+            totalActiveWeight += this.weights.symbolic;
+        // If no layers are active, return zero weights
+        if (totalActiveWeight === 0) {
+            return { semantic: 0, lexical: 0, symbolic: 0 };
+        }
+        // Normalize active weights to sum to 1
+        return {
+            semantic: hasSemantic ? this.weights.semantic / totalActiveWeight : 0,
+            lexical: hasLexical ? this.weights.lexical / totalActiveWeight : 0,
+            symbolic: hasSymbolic ? this.weights.symbolic / totalActiveWeight : 0,
+        };
+    }
+    /**
+     * Combine scores from maps directly (alternative interface).
+     *
+     * @param semanticScores - Map of entity name to semantic score
+     * @param lexicalScores - Map of entity name to lexical score
+     * @param symbolicScores - Map of entity name to symbolic score
+     * @param entityMap - Map of entity names to Entity objects
+     * @returns Array of combined results sorted by score
+     */
+    combineFromMaps(semanticScores, lexicalScores, symbolicScores, entityMap) {
+        // Convert maps to result arrays
+        const semanticResults = [];
+        for (const [entityName, similarity] of semanticScores) {
+            semanticResults.push({ entityName, similarity });
+        }
+        const lexicalResults = [];
+        for (const [entityName, score] of lexicalScores) {
+            lexicalResults.push({ entityName, score });
+        }
+        const symbolicResults = [];
+        for (const [entityName, score] of symbolicScores) {
+            symbolicResults.push({ entityName, score });
+        }
+        return this.combine(semanticResults, lexicalResults, symbolicResults, entityMap);
+    }
+    /**
+     * Calculate combined score for a single entity.
+     *
+     * Useful for scoring individual results without full normalization.
+     *
+     * @param semanticScore - Normalized semantic score (0-1)
+     * @param lexicalScore - Normalized lexical score (0-1)
+     * @param symbolicScore - Normalized symbolic score (0-1)
+     * @returns Combined weighted score
+     */
+    calculateScore(semanticScore, lexicalScore, symbolicScore) {
+        return (semanticScore * this.weights.semantic +
+            lexicalScore * this.weights.lexical +
+            symbolicScore * this.weights.symbolic);
+    }
+}
+//# sourceMappingURL=HybridScorer.js.map

package/dist/search/HybridScorer.js.map

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

package/dist/search/HybridSearchManager.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Hybrid Search Manager
+ *
+ * Phase 11: Orchestrates three-layer hybrid search combining
+ * semantic, lexical, and symbolic signals.
+ *
+ * @module search/HybridSearchManager
+ */
+import type { HybridSearchOptions, HybridSearchResult, ReadonlyKnowledgeGraph } from '../types/index.js';
+import type { SemanticSearch } from './SemanticSearch.js';
+import type { RankedSearch } from './RankedSearch.js';
+import { SymbolicSearch } from './SymbolicSearch.js';
+/**
+ * Default weights for hybrid search layers.
+ */
+export declare const DEFAULT_HYBRID_WEIGHTS: {
+    semantic: number;
+    lexical: number;
+    symbolic: number;
+};
+/**
+ * Hybrid Search Manager
+ *
+ * Combines three search layers:
+ * 1. Semantic: Vector similarity via embeddings
+ * 2. Lexical: Keyword matching via TF-IDF/BM25
+ * 3. Symbolic: Structured metadata filtering
+ *
+ * @example
+ * ```typescript
+ * const hybrid = new HybridSearchManager(semanticSearch, rankedSearch);
+ * const results = await hybrid.search(graph, 'machine learning', {
+ *   semanticWeight: 0.5,
+ *   lexicalWeight: 0.3,
+ *   symbolicWeight: 0.2,
+ *   symbolic: { tags: ['ai'] }
+ * });
+ * ```
+ */
+export declare class HybridSearchManager {
+    private semanticSearch;
+    private rankedSearch;
+    private symbolicSearch;
+    constructor(semanticSearch: SemanticSearch | null, rankedSearch: RankedSearch);
+    /**
+     * Perform hybrid search combining all three layers.
+     *
+     * @param graph - Knowledge graph to search
+     * @param query - Search query text
+     * @param options - Hybrid search options with weights
+     * @returns Combined and ranked results
+     */
+    search(graph: ReadonlyKnowledgeGraph, query: string, options?: Partial<HybridSearchOptions>): Promise<HybridSearchResult[]>;
+    /**
+     * Execute semantic search layer.
+     */
+    private executeSemanticSearch;
+    /**
+     * Execute lexical search layer (TF-IDF/BM25).
+     */
+    private executeLexicalSearch;
+    /**
+     * Execute symbolic search layer.
+     */
+    private executeSymbolicSearch;
+    /**
+     * Merge results from all three layers.
+     */
+    private mergeResults;
+    /**
+     * Search with full entity resolution.
+     * Alias for search() since we now always resolve entities.
+     */
+    searchWithEntities(graph: ReadonlyKnowledgeGraph, query: string, options?: Partial<HybridSearchOptions>): Promise<HybridSearchResult[]>;
+    /**
+     * Get the symbolic search instance for direct access.
+     */
+    getSymbolicSearch(): SymbolicSearch;
+}
+//# sourceMappingURL=HybridSearchManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HybridSearchManager.d.ts","sourceRoot":"","sources":["../../src/search/HybridSearchManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EAEvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;CAIlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAmB;IAI5B,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,YAAY;IAJtB,OAAO,CAAC,cAAc,CAAiB;gBAG7B,cAAc,EAAE,cAAc,GAAG,IAAI,EACrC,YAAY,EAAE,YAAY;IAKpC;;;;;;;OAOG;IACG,MAAM,CACV,KAAK,EAAE,sBAAsB,EAC7B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,OAAO,CAAC,mBAAmB,CAAM,GACzC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAuChC;;OAEG;YACW,qBAAqB;IA8BnC;;OAEG;YACW,oBAAoB;IA4BlC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAsB7B;;OAEG;IACH,OAAO,CAAC,YAAY;IAkDpB;;;OAGG;IACG,kBAAkB,CACtB,KAAK,EAAE,sBAAsB,EAC7B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,OAAO,CAAC,mBAAmB,CAAM,GACzC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAIhC;;OAEG;IACH,iBAAiB,IAAI,cAAc;CAGpC"}

package/dist/search/HybridSearchManager.js

@@ -0,0 +1,188 @@
+/**
+ * Hybrid Search Manager
+ *
+ * Phase 11: Orchestrates three-layer hybrid search combining
+ * semantic, lexical, and symbolic signals.
+ *
+ * @module search/HybridSearchManager
+ */
+import { SymbolicSearch } from './SymbolicSearch.js';
+import { SEMANTIC_SEARCH_LIMITS } from '../utils/constants.js';
+/**
+ * Default weights for hybrid search layers.
+ */
+export const DEFAULT_HYBRID_WEIGHTS = {
+    semantic: 0.5,
+    lexical: 0.3,
+    symbolic: 0.2,
+};
+/**
+ * Hybrid Search Manager
+ *
+ * Combines three search layers:
+ * 1. Semantic: Vector similarity via embeddings
+ * 2. Lexical: Keyword matching via TF-IDF/BM25
+ * 3. Symbolic: Structured metadata filtering
+ *
+ * @example
+ * ```typescript
+ * const hybrid = new HybridSearchManager(semanticSearch, rankedSearch);
+ * const results = await hybrid.search(graph, 'machine learning', {
+ *   semanticWeight: 0.5,
+ *   lexicalWeight: 0.3,
+ *   symbolicWeight: 0.2,
+ *   symbolic: { tags: ['ai'] }
+ * });
+ * ```
+ */
+export class HybridSearchManager {
+    semanticSearch;
+    rankedSearch;
+    symbolicSearch;
+    constructor(semanticSearch, rankedSearch) {
+        this.semanticSearch = semanticSearch;
+        this.rankedSearch = rankedSearch;
+        this.symbolicSearch = new SymbolicSearch();
+    }
+    /**
+     * Perform hybrid search combining all three layers.
+     *
+     * @param graph - Knowledge graph to search
+     * @param query - Search query text
+     * @param options - Hybrid search options with weights
+     * @returns Combined and ranked results
+     */
+    async search(graph, query, options = {}) {
+        const { semanticWeight = DEFAULT_HYBRID_WEIGHTS.semantic, lexicalWeight = DEFAULT_HYBRID_WEIGHTS.lexical, symbolicWeight = DEFAULT_HYBRID_WEIGHTS.symbolic, semantic = {}, lexical = {}, symbolic = {}, limit = SEMANTIC_SEARCH_LIMITS.DEFAULT_LIMIT, } = options;
+        // Normalize weights
+        const totalWeight = semanticWeight + lexicalWeight + symbolicWeight;
+        const normSemantic = semanticWeight / totalWeight;
+        const normLexical = lexicalWeight / totalWeight;
+        const normSymbolic = symbolicWeight / totalWeight;
+        // Execute searches in parallel
+        const [semanticResults, lexicalResults, symbolicResults] = await Promise.all([
+            this.executeSemanticSearch(graph, query, semantic, limit * 2),
+            this.executeLexicalSearch(query, lexical, limit * 2),
+            this.executeSymbolicSearch(graph.entities, symbolic),
+        ]);
+        // Merge results
+        const merged = this.mergeResults(graph.entities, semanticResults, lexicalResults, symbolicResults, { semantic: normSemantic, lexical: normLexical, symbolic: normSymbolic });
+        // Sort by combined score and limit
+        return merged
+            .sort((a, b) => b.scores.combined - a.scores.combined)
+            .slice(0, limit);
+    }
+    /**
+     * Execute semantic search layer.
+     */
+    async executeSemanticSearch(graph, query, options, limit) {
+        const results = new Map();
+        if (!this.semanticSearch) {
+            return results; // Semantic search not available
+        }
+        try {
+            const semanticResults = await this.semanticSearch.search(graph, query, options.topK ?? limit, options.minSimilarity ?? 0);
+            for (const result of semanticResults) {
+                results.set(result.entity.name, result.similarity);
+            }
+        }
+        catch {
+            // Semantic search may fail if not indexed
+        }
+        return results;
+    }
+    /**
+     * Execute lexical search layer (TF-IDF/BM25).
+     */
+    async executeLexicalSearch(query, _options, limit) {
+        const results = new Map();
+        try {
+            const lexicalResults = await this.rankedSearch.searchNodesRanked(query, undefined, // tags
+            undefined, // minImportance
+            undefined, // maxImportance
+            limit);
+            // Normalize scores to 0-1 range
+            const maxScore = Math.max(...lexicalResults.map(r => r.score), 1);
+            for (const result of lexicalResults) {
+                results.set(result.entity.name, result.score / maxScore);
+            }
+        }
+        catch {
+            // Lexical search may fail
+        }
+        return results;
+    }
+    /**
+     * Execute symbolic search layer.
+     */
+    executeSymbolicSearch(entities, filters) {
+        const results = new Map();
+        if (!filters || Object.keys(filters).length === 0) {
+            // No symbolic filters, give all entities base score
+            for (const entity of entities) {
+                results.set(entity.name, 0.5);
+            }
+            return results;
+        }
+        const symbolicResults = this.symbolicSearch.search(entities, filters);
+        for (const result of symbolicResults) {
+            results.set(result.entity.name, result.score);
+        }
+        return results;
+    }
+    /**
+     * Merge results from all three layers.
+     */
+    mergeResults(entities, semanticScores, lexicalScores, symbolicScores, weights) {
+        // Collect all unique entity names that have at least one non-zero score
+        const allNames = new Set([
+            ...semanticScores.keys(),
+            ...lexicalScores.keys(),
+            ...symbolicScores.keys(),
+        ]);
+        // Create entity lookup map
+        const entityMap = new Map(entities.map(e => [e.name, e]));
+        const results = [];
+        for (const name of allNames) {
+            const entity = entityMap.get(name);
+            if (!entity)
+                continue;
+            const semantic = semanticScores.get(name) ?? 0;
+            const lexical = lexicalScores.get(name) ?? 0;
+            const symbolic = symbolicScores.get(name) ?? 0;
+            const combined = semantic * weights.semantic +
+                lexical * weights.lexical +
+                symbolic * weights.symbolic;
+            const matchedLayers = [];
+            if (semantic > 0)
+                matchedLayers.push('semantic');
+            if (lexical > 0)
+                matchedLayers.push('lexical');
+            if (symbolic > 0)
+                matchedLayers.push('symbolic');
+            // Skip if no layers matched meaningfully
+            if (matchedLayers.length === 0)
+                continue;
+            results.push({
+                entity,
+                scores: { semantic, lexical, symbolic, combined },
+                matchedLayers,
+            });
+        }
+        return results;
+    }
+    /**
+     * Search with full entity resolution.
+     * Alias for search() since we now always resolve entities.
+     */
+    async searchWithEntities(graph, query, options = {}) {
+        return this.search(graph, query, options);
+    }
+    /**
+     * Get the symbolic search instance for direct access.
+     */
+    getSymbolicSearch() {
+        return this.symbolicSearch;
+    }
+}
+//# sourceMappingURL=HybridSearchManager.js.map

package/dist/search/HybridSearchManager.js.map

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