@danielsimonjr/memoryjs 1.0.0

package/dist/search/SymbolicSearch.js

@@ -0,0 +1,164 @@
+/**
+ * Symbolic Search Layer
+ *
+ * Phase 11: Provides metadata-based filtering using structured predicates.
+ * Part of the three-layer hybrid search architecture.
+ *
+ * @module search/SymbolicSearch
+ */
+/**
+ * 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 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, filters) {
+        const results = [];
+        for (const entity of entities) {
+            const { matches, score, matchedFilters } = this.evaluateFilters(entity, filters);
+            if (matches) {
+                results.push({ entity, score, matchedFilters });
+            }
+        }
+        // Sort by score descending
+        return results.sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Evaluate all filters against an entity.
+     */
+    evaluateFilters(entity, filters) {
+        const matchedFilters = [];
+        let totalFilters = 0;
+        let matchedCount = 0;
+        // Tag filter
+        if (filters.tags && filters.tags.length > 0) {
+            totalFilters++;
+            const entityTags = entity.tags ?? [];
+            const matchingTags = filters.tags.filter((t) => entityTags.some((et) => et.toLowerCase() === t.toLowerCase()));
+            if (matchingTags.length > 0) {
+                matchedCount++;
+                matchedFilters.push(`tags:${matchingTags.join(',')}`);
+            }
+            else {
+                return { matches: false, score: 0, matchedFilters: [] };
+            }
+        }
+        // Entity type filter
+        if (filters.entityTypes && filters.entityTypes.length > 0) {
+            totalFilters++;
+            if (filters.entityTypes.some((t) => t.toLowerCase() === entity.entityType.toLowerCase())) {
+                matchedCount++;
+                matchedFilters.push(`type:${entity.entityType}`);
+            }
+            else {
+                return { matches: false, score: 0, matchedFilters: [] };
+            }
+        }
+        // Date range filter
+        if (filters.dateRange) {
+            totalFilters++;
+            const entityDate = entity.createdAt || entity.lastModified;
+            if (!entityDate) {
+                // Entities without dates are excluded when date filter is applied
+                return { matches: false, score: 0, matchedFilters: [] };
+            }
+            const date = new Date(entityDate);
+            const start = filters.dateRange.start ? new Date(filters.dateRange.start) : null;
+            const end = filters.dateRange.end ? new Date(filters.dateRange.end) : null;
+            const inRange = (!start || date >= start) && (!end || date <= end);
+            if (inRange) {
+                matchedCount++;
+                matchedFilters.push('dateRange');
+            }
+            else {
+                return { matches: false, score: 0, matchedFilters: [] };
+            }
+        }
+        // Importance filter
+        if (filters.importance) {
+            totalFilters++;
+            const importance = entity.importance ?? 5;
+            const { min, max } = filters.importance;
+            const inRange = (min === undefined || importance >= min) &&
+                (max === undefined || importance <= max);
+            if (inRange) {
+                matchedCount++;
+                matchedFilters.push(`importance:${importance}`);
+            }
+            else {
+                return { matches: false, score: 0, matchedFilters: [] };
+            }
+        }
+        // Parent filter
+        if (filters.parentId !== undefined) {
+            totalFilters++;
+            if (entity.parentId === filters.parentId) {
+                matchedCount++;
+                matchedFilters.push(`parent:${filters.parentId}`);
+            }
+            else {
+                return { matches: false, score: 0, matchedFilters: [] };
+            }
+        }
+        // Has observations filter
+        if (filters.hasObservations !== undefined) {
+            totalFilters++;
+            const hasObs = entity.observations.length > 0;
+            if (hasObs === filters.hasObservations) {
+                matchedCount++;
+                matchedFilters.push('hasObservations');
+            }
+            else {
+                return { matches: false, score: 0, matchedFilters: [] };
+            }
+        }
+        // If no filters specified, match all with base score
+        if (totalFilters === 0) {
+            return { matches: true, score: 0.5, matchedFilters: [] };
+        }
+        // Score based on proportion of filters matched
+        const score = matchedCount / totalFilters;
+        return { matches: true, score, matchedFilters };
+    }
+    /**
+     * Get entities matching a specific tag.
+     */
+    byTag(entities, tag) {
+        return entities.filter(e => e.tags?.some(t => t.toLowerCase() === tag.toLowerCase()));
+    }
+    /**
+     * Get entities of a specific type.
+     */
+    byType(entities, entityType) {
+        return entities.filter(e => e.entityType.toLowerCase() === entityType.toLowerCase());
+    }
+    /**
+     * Get entities within importance range.
+     */
+    byImportance(entities, min, max) {
+        return entities.filter(e => {
+            const imp = e.importance ?? 5;
+            return imp >= min && imp <= max;
+        });
+    }
+}
+//# sourceMappingURL=SymbolicSearch.js.map

package/dist/search/SymbolicSearch.js.map

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

package/dist/search/TFIDFEventSync.d.ts

@@ -0,0 +1,85 @@
+/**
+ * TF-IDF Event Sync
+ *
+ * Phase 10 Sprint 3: Hooks TFIDFIndexManager to graph events for automatic
+ * incremental index updates when entities change.
+ *
+ * @module search/TFIDFEventSync
+ */
+import type { GraphEventEmitter } from '../core/GraphEventEmitter.js';
+import type { TFIDFIndexManager } from './TFIDFIndexManager.js';
+import type { IGraphStorage } from '../types/index.js';
+/**
+ * Phase 10 Sprint 3: Synchronizes TF-IDF index with graph changes via events.
+ *
+ * Listens to graph events and triggers incremental index updates automatically.
+ * More efficient than rebuilding the entire index on every change.
+ *
+ * @example
+ * ```typescript
+ * const storage = new GraphStorage('/data/memory.jsonl');
+ * const indexManager = new TFIDFIndexManager('/data');
+ *
+ * // Load or build index
+ * await indexManager.loadIndex();
+ *
+ * // Enable automatic sync
+ * const sync = new TFIDFEventSync(indexManager, storage.events, storage);
+ * sync.enable();
+ *
+ * // Now entities added to storage will automatically update the index
+ * await storage.appendEntity({ name: 'New', entityType: 'test', observations: [] });
+ *
+ * // Disable when done
+ * sync.disable();
+ * ```
+ */
+export declare class TFIDFEventSync {
+    private indexManager;
+    private eventEmitter;
+    private storage;
+    private unsubscribers;
+    private enabled;
+    /**
+     * Create a new TFIDFEventSync instance.
+     *
+     * @param indexManager - TFIDFIndexManager to sync
+     * @param eventEmitter - GraphEventEmitter to listen to
+     * @param storage - Storage to fetch entity data from (for updates)
+     */
+    constructor(indexManager: TFIDFIndexManager, eventEmitter: GraphEventEmitter, storage: IGraphStorage);
+    /**
+     * Enable automatic index synchronization.
+     *
+     * Subscribes to entity:created, entity:updated, and entity:deleted events.
+     */
+    enable(): void;
+    /**
+     * Disable automatic index synchronization.
+     *
+     * Unsubscribes from all events.
+     */
+    disable(): void;
+    /**
+     * Check if synchronization is enabled.
+     *
+     * @returns True if enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Handle entity:created event.
+     * @private
+     */
+    private handleEntityCreated;
+    /**
+     * Handle entity:updated event.
+     * @private
+     */
+    private handleEntityUpdated;
+    /**
+     * Handle entity:deleted event.
+     * @private
+     */
+    private handleEntityDeleted;
+}
+//# sourceMappingURL=TFIDFEventSync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TFIDFEventSync.d.ts","sourceRoot":"","sources":["../../src/search/TFIDFEventSync.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,OAAO,CAAkB;IAEjC;;;;;;OAMG;gBAED,YAAY,EAAE,iBAAiB,EAC/B,YAAY,EAAE,iBAAiB,EAC/B,OAAO,EAAE,aAAa;IAOxB;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAqBd;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAYf;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;OAGG;YACW,mBAAmB;IAkBjC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAO5B"}

package/dist/search/TFIDFEventSync.js

@@ -0,0 +1,134 @@
+/**
+ * TF-IDF Event Sync
+ *
+ * Phase 10 Sprint 3: Hooks TFIDFIndexManager to graph events for automatic
+ * incremental index updates when entities change.
+ *
+ * @module search/TFIDFEventSync
+ */
+/**
+ * Phase 10 Sprint 3: Synchronizes TF-IDF index with graph changes via events.
+ *
+ * Listens to graph events and triggers incremental index updates automatically.
+ * More efficient than rebuilding the entire index on every change.
+ *
+ * @example
+ * ```typescript
+ * const storage = new GraphStorage('/data/memory.jsonl');
+ * const indexManager = new TFIDFIndexManager('/data');
+ *
+ * // Load or build index
+ * await indexManager.loadIndex();
+ *
+ * // Enable automatic sync
+ * const sync = new TFIDFEventSync(indexManager, storage.events, storage);
+ * sync.enable();
+ *
+ * // Now entities added to storage will automatically update the index
+ * await storage.appendEntity({ name: 'New', entityType: 'test', observations: [] });
+ *
+ * // Disable when done
+ * sync.disable();
+ * ```
+ */
+export class TFIDFEventSync {
+    indexManager;
+    eventEmitter;
+    storage;
+    unsubscribers = [];
+    enabled = false;
+    /**
+     * Create a new TFIDFEventSync instance.
+     *
+     * @param indexManager - TFIDFIndexManager to sync
+     * @param eventEmitter - GraphEventEmitter to listen to
+     * @param storage - Storage to fetch entity data from (for updates)
+     */
+    constructor(indexManager, eventEmitter, storage) {
+        this.indexManager = indexManager;
+        this.eventEmitter = eventEmitter;
+        this.storage = storage;
+    }
+    /**
+     * Enable automatic index synchronization.
+     *
+     * Subscribes to entity:created, entity:updated, and entity:deleted events.
+     */
+    enable() {
+        if (this.enabled) {
+            return;
+        }
+        // Subscribe to entity events
+        this.unsubscribers.push(this.eventEmitter.on('entity:created', this.handleEntityCreated.bind(this)));
+        this.unsubscribers.push(this.eventEmitter.on('entity:updated', this.handleEntityUpdated.bind(this)));
+        this.unsubscribers.push(this.eventEmitter.on('entity:deleted', this.handleEntityDeleted.bind(this)));
+        this.enabled = true;
+    }
+    /**
+     * Disable automatic index synchronization.
+     *
+     * Unsubscribes from all events.
+     */
+    disable() {
+        if (!this.enabled) {
+            return;
+        }
+        for (const unsubscribe of this.unsubscribers) {
+            unsubscribe();
+        }
+        this.unsubscribers = [];
+        this.enabled = false;
+    }
+    /**
+     * Check if synchronization is enabled.
+     *
+     * @returns True if enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Handle entity:created event.
+     * @private
+     */
+    handleEntityCreated(event) {
+        if (!this.indexManager.isInitialized()) {
+            return;
+        }
+        this.indexManager.addDocument({
+            name: event.entity.name,
+            entityType: event.entity.entityType,
+            observations: event.entity.observations,
+        });
+    }
+    /**
+     * Handle entity:updated event.
+     * @private
+     */
+    async handleEntityUpdated(event) {
+        if (!this.indexManager.isInitialized()) {
+            return;
+        }
+        // Fetch the current entity state
+        const graph = await this.storage.loadGraph();
+        const entity = graph.entities.find(e => e.name === event.entityName);
+        if (entity) {
+            this.indexManager.updateDocument({
+                name: entity.name,
+                entityType: entity.entityType,
+                observations: entity.observations,
+            });
+        }
+    }
+    /**
+     * Handle entity:deleted event.
+     * @private
+     */
+    handleEntityDeleted(event) {
+        if (!this.indexManager.isInitialized()) {
+            return;
+        }
+        this.indexManager.removeDocument(event.entityName);
+    }
+}
+//# sourceMappingURL=TFIDFEventSync.js.map

package/dist/search/TFIDFEventSync.js.map

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

package/dist/search/TFIDFIndexManager.d.ts

@@ -0,0 +1,151 @@
+/**
+ * TF-IDF Index Manager
+ *
+ * Manages pre-calculated TF-IDF indexes for fast ranked search.
+ * Handles index building, incremental updates, and persistence.
+ *
+ * @module search/TFIDFIndexManager
+ */
+import type { TFIDFIndex, KnowledgeGraph, ReadonlyKnowledgeGraph } from '../types/index.js';
+/**
+ * Manages TF-IDF index lifecycle: building, updating, and persistence.
+ */
+export declare class TFIDFIndexManager {
+    private indexPath;
+    private index;
+    constructor(storageDir: string);
+    /**
+     * Build a complete TF-IDF index from a knowledge graph.
+     *
+     * @param graph - Knowledge graph to index
+     * @returns Newly built TF-IDF index
+     */
+    buildIndex(graph: ReadonlyKnowledgeGraph): Promise<TFIDFIndex>;
+    /**
+     * Update the index incrementally when entities change.
+     *
+     * More efficient than rebuilding the entire index.
+     *
+     * @param graph - Updated knowledge graph
+     * @param changedEntityNames - Names of entities that changed
+     */
+    updateIndex(graph: ReadonlyKnowledgeGraph, changedEntityNames: Set<string>): Promise<TFIDFIndex>;
+    /**
+     * Load index from disk.
+     *
+     * @returns Loaded index or null if not found
+     */
+    loadIndex(): Promise<TFIDFIndex | null>;
+    /**
+     * Save index to disk.
+     *
+     * @param index - Index to save (uses cached index if not provided)
+     */
+    saveIndex(index?: TFIDFIndex): Promise<void>;
+    /**
+     * Get the current cached index.
+     *
+     * @returns Cached index or null if not loaded
+     */
+    getIndex(): TFIDFIndex | null;
+    /**
+     * Clear the cached index and delete from disk.
+     */
+    clearIndex(): Promise<void>;
+    /**
+     * Check if the index needs rebuilding based on graph state.
+     *
+     * @param graph - Current knowledge graph
+     * @returns True if index should be rebuilt
+     */
+    needsRebuild(graph: KnowledgeGraph): boolean;
+    /**
+     * Phase 10 Sprint 3: Add a single document to the index incrementally.
+     *
+     * More efficient than rebuilding the entire index for single entity additions.
+     * Updates TF for the new document and recalculates IDF for affected terms.
+     *
+     * @param entity - The entity to add
+     *
+     * @example
+     * ```typescript
+     * const indexManager = new TFIDFIndexManager('/data');
+     * await indexManager.loadIndex();
+     *
+     * // Add new entity
+     * indexManager.addDocument({
+     *   name: 'NewEntity',
+     *   entityType: 'person',
+     *   observations: ['Software engineer']
+     * });
+     * ```
+     */
+    addDocument(entity: {
+        name: string;
+        entityType: string;
+        observations: string[];
+    }): void;
+    /**
+     * Phase 10 Sprint 3: Remove a single document from the index incrementally.
+     *
+     * More efficient than rebuilding the entire index for single entity deletions.
+     * Recalculates IDF for terms that were in the removed document.
+     *
+     * @param entityName - Name of the entity to remove
+     *
+     * @example
+     * ```typescript
+     * indexManager.removeDocument('DeletedEntity');
+     * ```
+     */
+    removeDocument(entityName: string): void;
+    /**
+     * Phase 10 Sprint 3: Update a single document in the index incrementally.
+     *
+     * More efficient than rebuilding the entire index for single entity updates.
+     * Handles both term changes and observation updates.
+     *
+     * @param entity - The updated entity
+     *
+     * @example
+     * ```typescript
+     * indexManager.updateDocument({
+     *   name: 'ExistingEntity',
+     *   entityType: 'person',
+     *   observations: ['Updated observations']
+     * });
+     * ```
+     */
+    updateDocument(entity: {
+        name: string;
+        entityType: string;
+        observations: string[];
+    }): void;
+    /**
+     * Phase 10 Sprint 3: Recalculate IDF scores for a set of terms.
+     *
+     * @param terms - Set of terms to recalculate IDF for
+     * @private
+     */
+    private recalculateIDFForTerms;
+    /**
+     * Phase 10 Sprint 3: Recalculate IDF scores for ALL terms in the index.
+     *
+     * Called when the total document count changes (add/remove document).
+     * @private
+     */
+    private recalculateAllIDF;
+    /**
+     * Phase 10 Sprint 3: Check if the index is loaded/initialized.
+     *
+     * @returns True if index is available
+     */
+    isInitialized(): boolean;
+    /**
+     * Phase 10 Sprint 3: Get the number of documents in the index.
+     *
+     * @returns Document count or 0 if not initialized
+     */
+    getDocumentCount(): number;
+}
+//# sourceMappingURL=TFIDFIndexManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TFIDFIndexManager.d.ts","sourceRoot":"","sources":["../../src/search/TFIDFIndexManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAkB,cAAc,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAgB5G;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAA2B;gBAE5B,UAAU,EAAE,MAAM;IAI9B;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAgDpE;;;;;;;OAOG;IACG,WAAW,CAAC,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAgEtG;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAmB7C;;;;OAIG;IACG,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBlD;;;;OAIG;IACH,QAAQ,IAAI,UAAU,GAAG,IAAI;IAI7B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;IAsB5C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IA+BvF;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAqBxC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IAgD1F;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAkC9B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IA8BzB;;;;OAIG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;OAIG;IACH,gBAAgB,IAAI,MAAM;CAG3B"}