@danielsimonjr/memory-mcp 0.48.0 → 9.8.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"SearchSuggestions.d.ts","sourceRoot":"","sources":["../../src/search/SearchSuggestions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAW5D;;GAEG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;;OASG;IACG,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,GAAE,MAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAoCzF"}

package/dist/search/SearchSuggestions.js

@@ -5,7 +5,7 @@
  *
  * @module search/SearchSuggestions
  */
-import { levenshteinDistance } from '../utils/levenshtein.js';
+import { levenshteinDistance } from '../utils/index.js';
 /**
  * Generates search suggestions based on entity names and types.
  */

package/dist/search/SemanticSearch.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Semantic Search Manager
+ *
+ * Phase 4 Sprint 12: Orchestrates embedding service and vector store
+ * to provide semantic similarity search capabilities.
+ *
+ * @module search/SemanticSearch
+ */
+import type { Entity, EmbeddingService, IVectorStore, SemanticSearchResult, SemanticIndexOptions, ReadonlyKnowledgeGraph } from '../types/index.js';
+/**
+ * Convert an entity to a text representation for embedding.
+ *
+ * Creates a structured text that captures the entity's key information
+ * for generating meaningful embeddings.
+ *
+ * @param entity - Entity to convert
+ * @returns Text representation suitable for embedding
+ */
+export declare function entityToText(entity: Entity): string;
+/**
+ * Semantic Search Manager
+ *
+ * Provides semantic similarity search by converting entities to embeddings
+ * and storing them in a vector store. Supports search by query text and
+ * finding similar entities.
+ *
+ * @example
+ * ```typescript
+ * const semanticSearch = new SemanticSearch(embeddingService, vectorStore);
+ * await semanticSearch.indexAll(graph);
+ * const results = await semanticSearch.search(graph, "machine learning");
+ * ```
+ */
+export declare class SemanticSearch {
+    /** Embedding service for generating vectors */
+    private embeddingService;
+    /** Vector store for storing and searching embeddings */
+    private vectorStore;
+    /** Whether embeddings have been indexed */
+    private indexed;
+    /** Number of entities currently indexed */
+    private indexedCount;
+    /**
+     * Create a semantic search manager.
+     *
+     * @param embeddingService - Service for generating embeddings
+     * @param vectorStore - Store for vector storage and search
+     */
+    constructor(embeddingService: EmbeddingService, vectorStore?: IVectorStore);
+    /**
+     * Index all entities in the knowledge graph.
+     *
+     * Generates embeddings for all entities and stores them in the vector store.
+     * Can be called incrementally - only indexes entities that aren't already indexed.
+     *
+     * Phase 9B: Supports cancellation via AbortSignal in options.
+     *
+     * @param graph - Knowledge graph to index
+     * @param options - Indexing options (includes signal for cancellation)
+     * @returns Index statistics
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     */
+    indexAll(graph: ReadonlyKnowledgeGraph, options?: SemanticIndexOptions): Promise<{
+        indexed: number;
+        skipped: number;
+        errors: number;
+    }>;
+    /**
+     * Index a single entity.
+     *
+     * @param entity - Entity to index
+     * @returns True if indexed successfully
+     */
+    indexEntity(entity: Entity): Promise<boolean>;
+    /**
+     * Remove an entity from the index.
+     *
+     * @param entityName - Name of entity to remove
+     * @returns True if found and removed
+     */
+    removeEntity(entityName: string): boolean;
+    /**
+     * Search for entities semantically similar to a query.
+     *
+     * @param graph - Knowledge graph to search in
+     * @param query - Search query text
+     * @param limit - Maximum number of results (default: 10)
+     * @param minSimilarity - Minimum similarity threshold (default: 0)
+     * @returns Array of search results with similarity scores
+     */
+    search(graph: ReadonlyKnowledgeGraph, query: string, limit?: number, minSimilarity?: number): Promise<SemanticSearchResult[]>;
+    /**
+     * Find entities similar to a given entity.
+     *
+     * @param graph - Knowledge graph to search in
+     * @param entityName - Name of entity to find similar entities for
+     * @param limit - Maximum number of results (default: 10)
+     * @param minSimilarity - Minimum similarity threshold (default: 0)
+     * @returns Array of search results with similarity scores
+     */
+    findSimilar(graph: ReadonlyKnowledgeGraph, entityName: string, limit?: number, minSimilarity?: number): Promise<SemanticSearchResult[]>;
+    /**
+     * Get the embedding service.
+     *
+     * @returns Embedding service instance
+     */
+    getEmbeddingService(): EmbeddingService;
+    /**
+     * Get the vector store.
+     *
+     * @returns Vector store instance
+     */
+    getVectorStore(): IVectorStore;
+    /**
+     * Check if the index has been built.
+     *
+     * @returns True if indexAll has been called
+     */
+    isIndexed(): boolean;
+    /**
+     * Get the number of indexed entities.
+     *
+     * @returns Number of entities in the vector store
+     */
+    getIndexedCount(): number;
+    /**
+     * Clear all indexed embeddings.
+     */
+    clearIndex(): void;
+    /**
+     * Check if semantic search is available.
+     *
+     * @returns True if embedding service is ready
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get semantic search statistics.
+     *
+     * @returns Statistics about the semantic search index
+     */
+    getStats(): {
+        indexed: boolean;
+        indexedCount: number;
+        provider: string;
+        model: string;
+        dimensions: number;
+    };
+}
+//# sourceMappingURL=SemanticSearch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticSearch.d.ts","sourceRoot":"","sources":["../../src/search/SemanticSearch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAkBnD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB,+CAA+C;IAC/C,OAAO,CAAC,gBAAgB,CAAmB;IAE3C,wDAAwD;IACxD,OAAO,CAAC,WAAW,CAAe;IAElC,2CAA2C;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB,2CAA2C;IAC3C,OAAO,CAAC,YAAY,CAAK;IAEzB;;;;;OAKG;gBACS,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,CAAC,EAAE,YAAY;IAK1E;;;;;;;;;;;;OAYG;IACG,QAAQ,CACZ,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAwEhE;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYnD;;;;;OAKG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAQzC;;;;;;;;OAQG;IACG,MAAM,CACV,KAAK,EAAE,sBAAsB,EAC7B,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAA6C,EACpD,aAAa,GAAE,MAA8C,GAC5D,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAsClC;;;;;;;;OAQG;IACG,WAAW,CACf,KAAK,EAAE,sBAAsB,EAC7B,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAA6C,EACpD,aAAa,GAAE,MAA8C,GAC5D,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAoDlC;;;;OAIG;IACH,mBAAmB,IAAI,gBAAgB;IAIvC;;;;OAIG;IACH,cAAc,IAAI,YAAY;IAI9B;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;;;OAIG;IACH,QAAQ,IAAI;QACV,OAAO,EAAE,OAAO,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB;CASF"}

package/dist/search/SemanticSearch.js

@@ -0,0 +1,323 @@
+/**
+ * Semantic Search Manager
+ *
+ * Phase 4 Sprint 12: Orchestrates embedding service and vector store
+ * to provide semantic similarity search capabilities.
+ *
+ * @module search/SemanticSearch
+ */
+import { InMemoryVectorStore } from './VectorStore.js';
+import { EMBEDDING_DEFAULTS, SEMANTIC_SEARCH_LIMITS } from '../utils/constants.js';
+import { checkCancellation } from '../utils/index.js';
+/**
+ * Convert an entity to a text representation for embedding.
+ *
+ * Creates a structured text that captures the entity's key information
+ * for generating meaningful embeddings.
+ *
+ * @param entity - Entity to convert
+ * @returns Text representation suitable for embedding
+ */
+export function entityToText(entity) {
+    const parts = [];
+    // Name and type are most important
+    parts.push(`${entity.name} (${entity.entityType})`);
+    // Add observations (limited to prevent overly long text)
+    if (entity.observations.length > 0) {
+        const observationText = entity.observations.slice(0, 10).join('. ');
+        parts.push(observationText);
+    }
+    // Add tags if present
+    if (entity.tags && entity.tags.length > 0) {
+        parts.push(`Tags: ${entity.tags.join(', ')}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Semantic Search Manager
+ *
+ * Provides semantic similarity search by converting entities to embeddings
+ * and storing them in a vector store. Supports search by query text and
+ * finding similar entities.
+ *
+ * @example
+ * ```typescript
+ * const semanticSearch = new SemanticSearch(embeddingService, vectorStore);
+ * await semanticSearch.indexAll(graph);
+ * const results = await semanticSearch.search(graph, "machine learning");
+ * ```
+ */
+export class SemanticSearch {
+    /** Embedding service for generating vectors */
+    embeddingService;
+    /** Vector store for storing and searching embeddings */
+    vectorStore;
+    /** Whether embeddings have been indexed */
+    indexed = false;
+    /** Number of entities currently indexed */
+    indexedCount = 0;
+    /**
+     * Create a semantic search manager.
+     *
+     * @param embeddingService - Service for generating embeddings
+     * @param vectorStore - Store for vector storage and search
+     */
+    constructor(embeddingService, vectorStore) {
+        this.embeddingService = embeddingService;
+        this.vectorStore = vectorStore || new InMemoryVectorStore();
+    }
+    /**
+     * Index all entities in the knowledge graph.
+     *
+     * Generates embeddings for all entities and stores them in the vector store.
+     * Can be called incrementally - only indexes entities that aren't already indexed.
+     *
+     * Phase 9B: Supports cancellation via AbortSignal in options.
+     *
+     * @param graph - Knowledge graph to index
+     * @param options - Indexing options (includes signal for cancellation)
+     * @returns Index statistics
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     */
+    async indexAll(graph, options = {}) {
+        const { forceReindex = false, onProgress, batchSize = EMBEDDING_DEFAULTS.DEFAULT_BATCH_SIZE, signal, } = options;
+        // Check for early cancellation
+        checkCancellation(signal, 'indexAll');
+        let indexed = 0;
+        let skipped = 0;
+        let errors = 0;
+        const entities = graph.entities;
+        const total = entities.length;
+        // Collect entities to index
+        const toIndex = [];
+        for (const entity of entities) {
+            if (forceReindex || !this.vectorStore.has(entity.name)) {
+                toIndex.push(entity);
+            }
+            else {
+                skipped++;
+            }
+        }
+        // Process in batches
+        for (let i = 0; i < toIndex.length; i += batchSize) {
+            // Check for cancellation between batches
+            checkCancellation(signal, 'indexAll');
+            const batch = toIndex.slice(i, i + batchSize);
+            const texts = batch.map(entityToText);
+            try {
+                const embeddings = await this.embeddingService.embedBatch(texts);
+                for (let j = 0; j < batch.length; j++) {
+                    this.vectorStore.add(batch[j].name, embeddings[j]);
+                    indexed++;
+                }
+            }
+            catch (error) {
+                // Try individual embeddings on batch failure
+                for (const entity of batch) {
+                    // Check for cancellation during fallback
+                    checkCancellation(signal, 'indexAll');
+                    try {
+                        const text = entityToText(entity);
+                        const embedding = await this.embeddingService.embed(text);
+                        this.vectorStore.add(entity.name, embedding);
+                        indexed++;
+                    }
+                    catch {
+                        errors++;
+                    }
+                }
+            }
+            // Report progress
+            if (onProgress) {
+                onProgress(indexed + skipped + errors, total);
+            }
+        }
+        this.indexed = true;
+        this.indexedCount = this.vectorStore.size();
+        return { indexed, skipped, errors };
+    }
+    /**
+     * Index a single entity.
+     *
+     * @param entity - Entity to index
+     * @returns True if indexed successfully
+     */
+    async indexEntity(entity) {
+        try {
+            const text = entityToText(entity);
+            const embedding = await this.embeddingService.embed(text);
+            this.vectorStore.add(entity.name, embedding);
+            this.indexedCount = this.vectorStore.size();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Remove an entity from the index.
+     *
+     * @param entityName - Name of entity to remove
+     * @returns True if found and removed
+     */
+    removeEntity(entityName) {
+        const removed = this.vectorStore.remove(entityName);
+        if (removed) {
+            this.indexedCount = this.vectorStore.size();
+        }
+        return removed;
+    }
+    /**
+     * Search for entities semantically similar to a query.
+     *
+     * @param graph - Knowledge graph to search in
+     * @param query - Search query text
+     * @param limit - Maximum number of results (default: 10)
+     * @param minSimilarity - Minimum similarity threshold (default: 0)
+     * @returns Array of search results with similarity scores
+     */
+    async search(graph, query, limit = SEMANTIC_SEARCH_LIMITS.DEFAULT_LIMIT, minSimilarity = SEMANTIC_SEARCH_LIMITS.MIN_SIMILARITY) {
+        // Ensure limit is within bounds
+        const effectiveLimit = Math.min(limit, SEMANTIC_SEARCH_LIMITS.MAX_LIMIT);
+        // Generate embedding for query
+        const queryEmbedding = await this.embeddingService.embed(query);
+        // Search vector store
+        const vectorResults = this.vectorStore.search(queryEmbedding, effectiveLimit * 2); // Get extra for filtering
+        // Convert to SemanticSearchResult with entity lookup
+        const entityMap = new Map();
+        for (const entity of graph.entities) {
+            entityMap.set(entity.name, entity);
+        }
+        const results = [];
+        for (const result of vectorResults) {
+            if (result.score < minSimilarity) {
+                continue;
+            }
+            const entity = entityMap.get(result.name);
+            if (entity) {
+                results.push({
+                    entity,
+                    similarity: result.score,
+                });
+            }
+            if (results.length >= effectiveLimit) {
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+     * Find entities similar to a given entity.
+     *
+     * @param graph - Knowledge graph to search in
+     * @param entityName - Name of entity to find similar entities for
+     * @param limit - Maximum number of results (default: 10)
+     * @param minSimilarity - Minimum similarity threshold (default: 0)
+     * @returns Array of search results with similarity scores
+     */
+    async findSimilar(graph, entityName, limit = SEMANTIC_SEARCH_LIMITS.DEFAULT_LIMIT, minSimilarity = SEMANTIC_SEARCH_LIMITS.MIN_SIMILARITY) {
+        // Get the entity's embedding
+        const embedding = this.vectorStore.get(entityName);
+        if (!embedding) {
+            // Try to find and index the entity
+            const entity = graph.entities.find(e => e.name === entityName);
+            if (entity) {
+                await this.indexEntity(entity);
+                return this.findSimilar(graph, entityName, limit, minSimilarity);
+            }
+            return [];
+        }
+        // Ensure limit is within bounds
+        const effectiveLimit = Math.min(limit, SEMANTIC_SEARCH_LIMITS.MAX_LIMIT);
+        // Search vector store (request extra to filter out self)
+        const vectorResults = this.vectorStore.search(embedding, effectiveLimit + 1);
+        // Convert to SemanticSearchResult with entity lookup
+        const entityMap = new Map();
+        for (const entity of graph.entities) {
+            entityMap.set(entity.name, entity);
+        }
+        const results = [];
+        for (const result of vectorResults) {
+            // Skip self
+            if (result.name === entityName) {
+                continue;
+            }
+            if (result.score < minSimilarity) {
+                continue;
+            }
+            const entity = entityMap.get(result.name);
+            if (entity) {
+                results.push({
+                    entity,
+                    similarity: result.score,
+                });
+            }
+            if (results.length >= effectiveLimit) {
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+     * Get the embedding service.
+     *
+     * @returns Embedding service instance
+     */
+    getEmbeddingService() {
+        return this.embeddingService;
+    }
+    /**
+     * Get the vector store.
+     *
+     * @returns Vector store instance
+     */
+    getVectorStore() {
+        return this.vectorStore;
+    }
+    /**
+     * Check if the index has been built.
+     *
+     * @returns True if indexAll has been called
+     */
+    isIndexed() {
+        return this.indexed;
+    }
+    /**
+     * Get the number of indexed entities.
+     *
+     * @returns Number of entities in the vector store
+     */
+    getIndexedCount() {
+        return this.indexedCount;
+    }
+    /**
+     * Clear all indexed embeddings.
+     */
+    clearIndex() {
+        this.vectorStore.clear();
+        this.indexed = false;
+        this.indexedCount = 0;
+    }
+    /**
+     * Check if semantic search is available.
+     *
+     * @returns True if embedding service is ready
+     */
+    async isAvailable() {
+        return this.embeddingService.isReady();
+    }
+    /**
+     * Get semantic search statistics.
+     *
+     * @returns Statistics about the semantic search index
+     */
+    getStats() {
+        return {
+            indexed: this.indexed,
+            indexedCount: this.indexedCount,
+            provider: this.embeddingService.provider,
+            model: this.embeddingService.model,
+            dimensions: this.embeddingService.dimensions,
+        };
+    }
+}

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"}