@danielsimonjr/memory-mcp 9.9.0 → 10.0.0

package/dist/core/EntityManager.d.ts

@@ -228,6 +228,8 @@ export declare class EntityManager {
     /**
      * Add tags to multiple entities in a single operation.
      *
+     * OPTIMIZED: Uses Map for O(1) entity lookups instead of O(n) find() per entity.
+     *
      * @param entityNames - Names of entities to tag
      * @param tags - Tags to add to each entity
      * @returns Array of results showing which tags were added to each entity

package/dist/core/EntityManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../src/core/EntityManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBtD;;GAEG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,EAAE,CAAC;IA+EpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,WAAW,CACf,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,GACzD,OAAO,CAAC,MAAM,EAAE,CAAC;IAuCpB;;;;;;;;;OASG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAsBvG;;;;;;;OAOG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAoC5G;;;;;;;;OAQG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBhH;;;;;;OAMG;IACG,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAiC9H;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAuBxG;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAmCvH"}
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../src/core/EntityManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBtD;;GAEG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,EAAE,CAAC;IA+EpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,WAAW,CACf,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,GACzD,OAAO,CAAC,MAAM,EAAE,CAAC;IAuCpB;;;;;;;;;OASG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAsBvG;;;;;;;OAOG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAgC5G;;;;;;;;OAQG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBhH;;;;;;;;OAQG;IACG,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAuC9H;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAuBxG;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAmCvH"}

package/dist/core/EntityManager.js

@@ -357,9 +357,8 @@ export class EntityManager {
      * @throws {EntityNotFoundError} If entity is not found
      */
     async removeTags(entityName, tags) {
-        const graph = await this.storage.getGraphForMutation();
-        const timestamp = new Date().toISOString();
-        const entity = graph.entities.find(e => e.name === entityName);
+        // OPTIMIZED: Use O(1) NameIndex lookup instead of loadGraph() + O(n) find()
+        const entity = this.storage.getEntityByName(entityName);
         if (!entity) {
             throw new EntityNotFoundError(entityName);
         }
@@ -372,14 +371,13 @@ export class EntityManager {
         // Capture existing tags (lowercase) BEFORE filtering to accurately track removals
         const existingTagsLower = entity.tags.map(t => t.toLowerCase());
         // Filter out the tags to remove
-        entity.tags = entity.tags.filter(tag => !normalizedTags.includes(tag.toLowerCase()));
+        const newTags = entity.tags.filter(tag => !normalizedTags.includes(tag.toLowerCase()));
         // A tag was removed if it existed in the original tags
         const removedTags = normalizedTags.filter(tag => existingTagsLower.includes(tag));
-        // Update lastModified timestamp if tags were removed
-        if (entity.tags.length < originalLength) {
-            entity.lastModified = timestamp;
+        // Update entity via storage if tags were removed
+        if (newTags.length < originalLength) {
+            await this.storage.updateEntity(entityName, { tags: newTags });
         }
-        await this.storage.saveGraph(graph);
         return { entityName, removedTags };
     }
     /**
@@ -408,6 +406,8 @@ export class EntityManager {
     /**
      * Add tags to multiple entities in a single operation.
      *
+     * OPTIMIZED: Uses Map for O(1) entity lookups instead of O(n) find() per entity.
+     *
      * @param entityNames - Names of entities to tag
      * @param tags - Tags to add to each entity
      * @returns Array of results showing which tags were added to each entity
@@ -417,8 +417,13 @@ export class EntityManager {
         const timestamp = new Date().toISOString();
         const normalizedTags = tags.map(tag => tag.toLowerCase());
         const results = [];
+        // OPTIMIZED: Build Map for O(1) lookups instead of O(n) find() per entity
+        const entityMap = new Map();
+        for (const e of graph.entities) {
+            entityMap.set(e.name, e);
+        }
         for (const entityName of entityNames) {
-            const entity = graph.entities.find(e => e.name === entityName);
+            const entity = entityMap.get(entityName);
             if (!entity) {
                 continue; // Skip non-existent entities
             }

package/dist/core/RelationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RelationManager.d.ts","sourceRoot":"","sources":["../../src/core/RelationManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAKtD;;GAEG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACG,eAAe,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAiEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,eAAe,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAK5D"}
+{"version":3,"file":"RelationManager.d.ts","sourceRoot":"","sources":["../../src/core/RelationManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAKtD;;GAEG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACG,eAAe,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAiEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,eAAe,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAK5D"}

package/dist/core/RelationManager.js

@@ -158,10 +158,11 @@ export class RelationManager {
             affectedEntityNames.add(rel.from);
             affectedEntityNames.add(rel.to);
         });
-        // Remove relations
-        graph.relations = graph.relations.filter(r => !relations.some(delRelation => r.from === delRelation.from &&
-            r.to === delRelation.to &&
-            r.relationType === delRelation.relationType));
+        // OPTIMIZED: Use Set<string> for O(1) lookup instead of O(n) array.some()
+        // Create composite keys for relations to delete
+        const relationsToDeleteSet = new Set(relations.map(r => `${r.from}|${r.to}|${r.relationType}`));
+        // Remove relations with O(1) Set lookup per relation instead of O(m) array scan
+        graph.relations = graph.relations.filter(r => !relationsToDeleteSet.has(`${r.from}|${r.to}|${r.relationType}`));
         // Update lastModified for affected entities
         graph.entities.forEach(entity => {
             if (affectedEntityNames.has(entity.name)) {

package/dist/features/CompressionManager.d.ts

@@ -18,8 +18,10 @@ export declare class CompressionManager {
      * Prepare an entity for efficient similarity comparisons.
      * Pre-computes all normalized data to avoid repeated computation.
      *
+     * Phase 12 Sprint 1: Added nameHash for fast bucketing.
+     *
      * @param entity - The entity to prepare
-     * @returns PreparedEntity with pre-computed data
+     * @returns PreparedEntity with pre-computed data including hash
      */
     private prepareEntity;
     /**

package/dist/features/CompressionManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompressionManager.d.ts","sourceRoot":"","sources":["../../src/features/CompressionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAY,iBAAiB,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC1H,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AA2B5D;;GAEG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;;;;;;OAWG;IACH,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM;IAwCzD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;;;;OAOG;IACH,OAAO,CAAC,2BAA2B;IAoCnC;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAClB,SAAS,GAAE,MAAoC,EAC/C,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IA0GtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EAAE,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,cAAc,CAAC;QACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACf,GACL,OAAO,CAAC,MAAM,CAAC;IA8FlB;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,SAAS,GAAE,MAAoC,EAC/C,MAAM,GAAE,OAAe,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,iBAAiB,CAAC;CA0G9B"}
+{"version":3,"file":"CompressionManager.d.ts","sourceRoot":"","sources":["../../src/features/CompressionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAY,iBAAiB,EAAE,cAAc,EAAE,2BAA2B,EAAkB,MAAM,mBAAmB,CAAC;AAC1I,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAW5D;;GAEG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAYrB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;;;;;;OAWG;IACH,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM;IAwCzD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;;;;OAOG;IACH,OAAO,CAAC,2BAA2B;IAoCnC;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAClB,SAAS,GAAE,MAAoC,EAC/C,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IA0GtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EAAE,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,cAAc,CAAC;QACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACf,GACL,OAAO,CAAC,MAAM,CAAC;IA8FlB;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,SAAS,GAAE,MAAoC,EAC/C,MAAM,GAAE,OAAe,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,iBAAiB,CAAC;CAgH9B"}

package/dist/features/CompressionManager.js

@@ -6,7 +6,7 @@
  *
  * @module features/CompressionManager
  */
-import { levenshteinDistance, checkCancellation, createProgressReporter, createProgress, } from '../utils/index.js';
+import { levenshteinDistance, checkCancellation, createProgressReporter, createProgress, fnv1aHash, } from '../utils/index.js';
 import { EntityNotFoundError, InsufficientEntitiesError } from '../utils/errors.js';
 import { SIMILARITY_WEIGHTS, DEFAULT_DUPLICATE_THRESHOLD } from '../utils/constants.js';
 /**
@@ -21,16 +21,20 @@ export class CompressionManager {
      * Prepare an entity for efficient similarity comparisons.
      * Pre-computes all normalized data to avoid repeated computation.
      *
+     * Phase 12 Sprint 1: Added nameHash for fast bucketing.
+     *
      * @param entity - The entity to prepare
-     * @returns PreparedEntity with pre-computed data
+     * @returns PreparedEntity with pre-computed data including hash
      */
     prepareEntity(entity) {
+        const nameLower = entity.name.toLowerCase();
         return {
             entity,
-            nameLower: entity.name.toLowerCase(),
+            nameLower,
             typeLower: entity.entityType.toLowerCase(),
             observationSet: new Set(entity.observations.map(o => o.toLowerCase())),
             tagSet: new Set((entity.tags ?? []).map(t => t.toLowerCase())),
+            nameHash: fnv1aHash(nameLower),
         };
     }
     /**
@@ -411,15 +415,20 @@ export class CompressionManager {
         // Phase 2: Merge duplicates (50-100% progress)
         const totalGroups = duplicateGroups.length;
         let mergedGroups = 0;
+        // OPTIMIZATION: Build entity lookup map for O(1) access during merges
+        const entityMap = new Map();
+        for (const entity of graph.entities) {
+            entityMap.set(entity.name, entity);
+        }
         // Merge all duplicates using the same graph instance
         for (const group of duplicateGroups) {
             // Check for cancellation between merges
             checkCancellation(options?.signal, 'compressGraph');
             try {
-                // Count observations before merge using loaded graph
+                // Count observations before merge using O(1) lookup
                 let totalObservationsBefore = 0;
                 for (const name of group) {
-                    const entity = graph.entities.find(e => e.name === name);
+                    const entity = entityMap.get(name);
                     if (entity) {
                         totalObservationsBefore += entity.observations.length;
                     }

package/dist/search/BM25Search.d.ts

@@ -0,0 +1,148 @@
+/**
+ * BM25 Search
+ *
+ * BM25 (Best Matching 25) relevance scoring algorithm for lexical search.
+ * Provides improved ranking over TF-IDF by incorporating document length normalization.
+ *
+ * Phase 12 Sprint 3: Search Algorithm Optimization
+ *
+ * @module search/BM25Search
+ */
+import type { SearchResult } from '../types/index.js';
+import type { GraphStorage } from '../core/GraphStorage.js';
+/**
+ * Common English stopwords to filter from queries and documents.
+ * These words are too common to provide meaningful ranking signal.
+ */
+export declare const STOPWORDS: Set<string>;
+/**
+ * BM25 index entry for a single document.
+ */
+export interface BM25DocumentEntry {
+    /** Entity name */
+    entityName: string;
+    /** Term frequencies in this document */
+    termFreqs: Map<string, number>;
+    /** Total number of tokens in document */
+    docLength: number;
+}
+/**
+ * BM25 index structure.
+ */
+export interface BM25Index {
+    /** Document entries keyed by entity name */
+    documents: Map<string, BM25DocumentEntry>;
+    /** Document frequency for each term (number of docs containing term) */
+    documentFrequency: Map<string, number>;
+    /** Average document length */
+    avgDocLength: number;
+    /** Total number of documents */
+    totalDocs: number;
+}
+/**
+ * BM25 configuration parameters.
+ */
+export interface BM25Config {
+    /** Term frequency saturation parameter (default: 1.2) */
+    k1: number;
+    /** Length normalization parameter (default: 0.75) */
+    b: number;
+}
+/**
+ * Default BM25 parameters based on research recommendations.
+ */
+export declare const DEFAULT_BM25_CONFIG: BM25Config;
+/**
+ * BM25 Search implementation.
+ *
+ * BM25 improves over TF-IDF by:
+ * 1. Saturating term frequency - prevents long documents from dominating
+ * 2. Document length normalization - accounts for varying document sizes
+ *
+ * Formula:
+ * score(D,Q) = sum_i( IDF(qi) * (f(qi,D) * (k1 + 1)) / (f(qi,D) + k1 * (1 - b + b * |D|/avgdl)) )
+ *
+ * Where:
+ * - f(qi,D) is the term frequency of qi in document D
+ * - |D| is the length of document D
+ * - avgdl is the average document length
+ * - k1 and b are free parameters
+ *
+ * @example
+ * ```typescript
+ * const bm25 = new BM25Search(storage);
+ * await bm25.buildIndex();
+ * const results = await bm25.search('machine learning');
+ * ```
+ */
+export declare class BM25Search {
+    private storage;
+    private index;
+    private config;
+    constructor(storage: GraphStorage, config?: Partial<BM25Config>);
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): BM25Config;
+    /**
+     * Update configuration parameters.
+     *
+     * @param config - New configuration values
+     */
+    setConfig(config: Partial<BM25Config>): void;
+    /**
+     * Tokenize text into lowercase terms with stopword filtering.
+     *
+     * @param text - Text to tokenize
+     * @param filterStopwords - Whether to filter stopwords (default: true)
+     * @returns Array of lowercase tokens
+     */
+    tokenize(text: string, filterStopwords?: boolean): string[];
+    /**
+     * Build the BM25 index from the current graph.
+     *
+     * Should be called after significant graph changes.
+     */
+    buildIndex(): Promise<void>;
+    /**
+     * Search using the BM25 algorithm.
+     *
+     * @param query - Search query
+     * @param limit - Maximum results to return
+     * @returns Array of search results sorted by BM25 score
+     */
+    search(query: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Update the index for changed entities.
+     *
+     * @param changedEntityNames - Names of entities that changed
+     */
+    update(changedEntityNames: Set<string>): Promise<void>;
+    /**
+     * Remove an entity from the index.
+     *
+     * @param entityName - Name of entity to remove
+     */
+    remove(entityName: string): boolean;
+    /**
+     * Clear the index.
+     */
+    clearIndex(): void;
+    /**
+     * Check if the index is built.
+     */
+    isIndexed(): boolean;
+    /**
+     * Get index statistics.
+     */
+    getIndexStats(): {
+        documents: number;
+        terms: number;
+        avgDocLength: number;
+    } | null;
+    /**
+     * Convert an entity to searchable text.
+     */
+    private entityToText;
+}
+//# sourceMappingURL=BM25Search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BM25Search.d.ts","sourceRoot":"","sources":["../../src/search/BM25Search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D;;;GAGG;AACH,eAAO,MAAM,SAAS,aAWpB,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1C,wEAAwE;IACxE,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAGjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,OAAO;IAJjB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,MAAM,CAAa;gBAGjB,OAAO,EAAE,YAAY,EAC7B,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM;IAKlC;;OAEG;IACH,SAAS,IAAI,UAAU;IAIvB;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAI5C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,GAAE,OAAc,GAAG,MAAM,EAAE;IAajE;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgDjC;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAA8B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA8E3F;;;;OAIG;IACG,MAAM,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkE5D;;;;OAIG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAmCnC;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,aAAa,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWlF;;OAEG;IACH,OAAO,CAAC,YAAY;CAGrB"}

package/dist/search/BM25Search.js

@@ -0,0 +1,339 @@
+/**
+ * BM25 Search
+ *
+ * BM25 (Best Matching 25) relevance scoring algorithm for lexical search.
+ * Provides improved ranking over TF-IDF by incorporating document length normalization.
+ *
+ * Phase 12 Sprint 3: Search Algorithm Optimization
+ *
+ * @module search/BM25Search
+ */
+import { SEARCH_LIMITS } from '../utils/constants.js';
+/**
+ * Common English stopwords to filter from queries and documents.
+ * These words are too common to provide meaningful ranking signal.
+ */
+export const STOPWORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from',
+    'has', 'he', 'in', 'is', 'it', 'its', 'of', 'on', 'or', 'that',
+    'the', 'to', 'was', 'were', 'will', 'with', 'you', 'your',
+    'this', 'but', 'they', 'have', 'had', 'what', 'when', 'where',
+    'who', 'which', 'why', 'how', 'all', 'each', 'every', 'both',
+    'few', 'more', 'most', 'other', 'some', 'such', 'no', 'not',
+    'only', 'own', 'same', 'so', 'than', 'too', 'very', 'can',
+    'just', 'should', 'now', 'also', 'being', 'been', 'would',
+    'could', 'into', 'over', 'after', 'before', 'between', 'under',
+    'again', 'then', 'once', 'here', 'there', 'any', 'about',
+]);
+/**
+ * Default BM25 parameters based on research recommendations.
+ */
+export const DEFAULT_BM25_CONFIG = {
+    k1: 1.2,
+    b: 0.75,
+};
+/**
+ * BM25 Search implementation.
+ *
+ * BM25 improves over TF-IDF by:
+ * 1. Saturating term frequency - prevents long documents from dominating
+ * 2. Document length normalization - accounts for varying document sizes
+ *
+ * Formula:
+ * score(D,Q) = sum_i( IDF(qi) * (f(qi,D) * (k1 + 1)) / (f(qi,D) + k1 * (1 - b + b * |D|/avgdl)) )
+ *
+ * Where:
+ * - f(qi,D) is the term frequency of qi in document D
+ * - |D| is the length of document D
+ * - avgdl is the average document length
+ * - k1 and b are free parameters
+ *
+ * @example
+ * ```typescript
+ * const bm25 = new BM25Search(storage);
+ * await bm25.buildIndex();
+ * const results = await bm25.search('machine learning');
+ * ```
+ */
+export class BM25Search {
+    storage;
+    index = null;
+    config;
+    constructor(storage, config = {}) {
+        this.storage = storage;
+        this.config = { ...DEFAULT_BM25_CONFIG, ...config };
+    }
+    /**
+     * Get the current configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration parameters.
+     *
+     * @param config - New configuration values
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Tokenize text into lowercase terms with stopword filtering.
+     *
+     * @param text - Text to tokenize
+     * @param filterStopwords - Whether to filter stopwords (default: true)
+     * @returns Array of lowercase tokens
+     */
+    tokenize(text, filterStopwords = true) {
+        const tokens = text
+            .toLowerCase()
+            .replace(/[^\w\s]/g, ' ')
+            .split(/\s+/)
+            .filter(token => token.length > 0);
+        if (filterStopwords) {
+            return tokens.filter(token => !STOPWORDS.has(token));
+        }
+        return tokens;
+    }
+    /**
+     * Build the BM25 index from the current graph.
+     *
+     * Should be called after significant graph changes.
+     */
+    async buildIndex() {
+        const graph = await this.storage.loadGraph();
+        const documents = new Map();
+        const documentFrequency = new Map();
+        const termsSeen = new Set();
+        let totalDocLength = 0;
+        // First pass: tokenize all documents and count term frequencies
+        for (const entity of graph.entities) {
+            const text = this.entityToText(entity);
+            const tokens = this.tokenize(text);
+            const termFreqs = new Map();
+            // Count term frequencies for this document
+            for (const token of tokens) {
+                termFreqs.set(token, (termFreqs.get(token) || 0) + 1);
+            }
+            // Track which terms appear in this document (for IDF calculation)
+            termsSeen.clear();
+            for (const token of tokens) {
+                if (!termsSeen.has(token)) {
+                    termsSeen.add(token);
+                    documentFrequency.set(token, (documentFrequency.get(token) || 0) + 1);
+                }
+            }
+            const entry = {
+                entityName: entity.name,
+                termFreqs,
+                docLength: tokens.length,
+            };
+            documents.set(entity.name, entry);
+            totalDocLength += tokens.length;
+        }
+        const totalDocs = documents.size;
+        const avgDocLength = totalDocs > 0 ? totalDocLength / totalDocs : 0;
+        this.index = {
+            documents,
+            documentFrequency,
+            avgDocLength,
+            totalDocs,
+        };
+    }
+    /**
+     * Search using the BM25 algorithm.
+     *
+     * @param query - Search query
+     * @param limit - Maximum results to return
+     * @returns Array of search results sorted by BM25 score
+     */
+    async search(query, limit = SEARCH_LIMITS.DEFAULT) {
+        const effectiveLimit = Math.min(limit, SEARCH_LIMITS.MAX);
+        // Ensure index is built
+        if (!this.index) {
+            await this.buildIndex();
+        }
+        if (!this.index || this.index.documents.size === 0) {
+            return [];
+        }
+        const graph = await this.storage.loadGraph();
+        const entityMap = new Map(graph.entities.map(e => [e.name, e]));
+        // Tokenize query
+        const queryTerms = this.tokenize(query);
+        if (queryTerms.length === 0) {
+            return [];
+        }
+        const { k1, b } = this.config;
+        const { documents, documentFrequency, avgDocLength, totalDocs } = this.index;
+        const results = [];
+        // Calculate BM25 score for each document
+        for (const [entityName, docEntry] of documents) {
+            const entity = entityMap.get(entityName);
+            if (!entity)
+                continue;
+            let score = 0;
+            const matchedFields = {};
+            for (const term of queryTerms) {
+                const tf = docEntry.termFreqs.get(term) || 0;
+                if (tf === 0)
+                    continue;
+                // Calculate IDF
+                const df = documentFrequency.get(term) || 0;
+                const idf = df > 0 ? Math.log((totalDocs - df + 0.5) / (df + 0.5) + 1) : 0;
+                // Calculate BM25 score component
+                const numerator = tf * (k1 + 1);
+                const denominator = tf + k1 * (1 - b + b * (docEntry.docLength / avgDocLength));
+                const termScore = idf * (numerator / denominator);
+                score += termScore;
+                // 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;
+                }
+            }
+            if (score > 0) {
+                results.push({
+                    entity,
+                    score,
+                    matchedFields,
+                });
+            }
+        }
+        // Sort by score descending and limit
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, effectiveLimit);
+    }
+    /**
+     * Update the index for changed entities.
+     *
+     * @param changedEntityNames - Names of entities that changed
+     */
+    async update(changedEntityNames) {
+        if (!this.index) {
+            await this.buildIndex();
+            return;
+        }
+        const graph = await this.storage.loadGraph();
+        const entityMap = new Map(graph.entities.map(e => [e.name, e]));
+        // Process each changed entity
+        for (const entityName of changedEntityNames) {
+            const entity = entityMap.get(entityName);
+            const existingEntry = this.index.documents.get(entityName);
+            if (existingEntry) {
+                // Remove old term frequencies from document frequency counts
+                for (const [term] of existingEntry.termFreqs) {
+                    const df = this.index.documentFrequency.get(term) || 0;
+                    if (df <= 1) {
+                        this.index.documentFrequency.delete(term);
+                    }
+                    else {
+                        this.index.documentFrequency.set(term, df - 1);
+                    }
+                }
+                this.index.documents.delete(entityName);
+            }
+            if (entity) {
+                // Add new entry
+                const text = this.entityToText(entity);
+                const tokens = this.tokenize(text);
+                const termFreqs = new Map();
+                const termsSeen = new Set();
+                for (const token of tokens) {
+                    termFreqs.set(token, (termFreqs.get(token) || 0) + 1);
+                    if (!termsSeen.has(token)) {
+                        termsSeen.add(token);
+                        this.index.documentFrequency.set(token, (this.index.documentFrequency.get(token) || 0) + 1);
+                    }
+                }
+                const entry = {
+                    entityName: entity.name,
+                    termFreqs,
+                    docLength: tokens.length,
+                };
+                this.index.documents.set(entityName, entry);
+            }
+        }
+        // Recalculate average document length
+        this.index.totalDocs = this.index.documents.size;
+        let totalLength = 0;
+        for (const doc of this.index.documents.values()) {
+            totalLength += doc.docLength;
+        }
+        this.index.avgDocLength = this.index.totalDocs > 0
+            ? totalLength / this.index.totalDocs
+            : 0;
+    }
+    /**
+     * Remove an entity from the index.
+     *
+     * @param entityName - Name of entity to remove
+     */
+    remove(entityName) {
+        if (!this.index) {
+            return false;
+        }
+        const entry = this.index.documents.get(entityName);
+        if (!entry) {
+            return false;
+        }
+        // Update document frequency counts
+        for (const [term] of entry.termFreqs) {
+            const df = this.index.documentFrequency.get(term) || 0;
+            if (df <= 1) {
+                this.index.documentFrequency.delete(term);
+            }
+            else {
+                this.index.documentFrequency.set(term, df - 1);
+            }
+        }
+        this.index.documents.delete(entityName);
+        // Update totals
+        this.index.totalDocs = this.index.documents.size;
+        let totalLength = 0;
+        for (const doc of this.index.documents.values()) {
+            totalLength += doc.docLength;
+        }
+        this.index.avgDocLength = this.index.totalDocs > 0
+            ? totalLength / this.index.totalDocs
+            : 0;
+        return true;
+    }
+    /**
+     * Clear the index.
+     */
+    clearIndex() {
+        this.index = null;
+    }
+    /**
+     * Check if the index is built.
+     */
+    isIndexed() {
+        return this.index !== null;
+    }
+    /**
+     * Get index statistics.
+     */
+    getIndexStats() {
+        if (!this.index) {
+            return null;
+        }
+        return {
+            documents: this.index.documents.size,
+            terms: this.index.documentFrequency.size,
+            avgDocLength: this.index.avgDocLength,
+        };
+    }
+    /**
+     * Convert an entity to searchable text.
+     */
+    entityToText(entity) {
+        return [entity.name, entity.entityType, ...entity.observations].join(' ');
+    }
+}