@danielsimonjr/memory-mcp 0.47.1 → 9.8.0

package/dist/utils/indexes.js

@@ -0,0 +1,526 @@
+/**
+ * Search Indexes
+ *
+ * Provides O(1) lookup structures to avoid repeated linear scans.
+ * - NameIndex: O(1) entity lookup by name
+ * - TypeIndex: O(1) entities by type
+ * - LowercaseCache: Pre-computed lowercase strings to avoid repeated toLowerCase()
+ * - RelationIndex: O(1) relation lookup by entity name (from/to)
+ * - ObservationIndex: O(1) observation word lookup by entity
+ *
+ * @module utils/indexes
+ */
+/**
+ * NameIndex provides O(1) entity lookup by name.
+ *
+ * Uses a Map internally for constant-time access.
+ */
+export class NameIndex {
+    index = new Map();
+    /**
+     * Build the index from an array of entities.
+     * Clears any existing index data first.
+     */
+    build(entities) {
+        this.index.clear();
+        for (const entity of entities) {
+            this.index.set(entity.name, entity);
+        }
+    }
+    /**
+     * Get an entity by name in O(1) time.
+     */
+    get(name) {
+        return this.index.get(name);
+    }
+    /**
+     * Add a single entity to the index.
+     */
+    add(entity) {
+        this.index.set(entity.name, entity);
+    }
+    /**
+     * Remove an entity from the index by name.
+     */
+    remove(name) {
+        this.index.delete(name);
+    }
+    /**
+     * Check if an entity exists in the index.
+     */
+    has(name) {
+        return this.index.has(name);
+    }
+    /**
+     * Get the number of entities in the index.
+     */
+    get size() {
+        return this.index.size;
+    }
+    /**
+     * Clear all entries from the index.
+     */
+    clear() {
+        this.index.clear();
+    }
+}
+/**
+ * TypeIndex provides O(1) lookup of entities by type.
+ *
+ * Uses a Map<type, Set<entityName>> structure for efficient type queries.
+ * Type comparisons are case-insensitive.
+ */
+export class TypeIndex {
+    index = new Map();
+    /**
+     * Build the index from an array of entities.
+     * Clears any existing index data first.
+     */
+    build(entities) {
+        this.index.clear();
+        for (const entity of entities) {
+            this.addToIndex(entity.name, entity.entityType);
+        }
+    }
+    /**
+     * Get all entity names of a given type in O(1) time.
+     * Type comparison is case-insensitive.
+     */
+    getNames(entityType) {
+        const typeLower = entityType.toLowerCase();
+        return this.index.get(typeLower) ?? new Set();
+    }
+    /**
+     * Add an entity to the type index.
+     */
+    add(entity) {
+        this.addToIndex(entity.name, entity.entityType);
+    }
+    /**
+     * Remove an entity from the type index.
+     * Requires the entity type to know which bucket to remove from.
+     */
+    remove(entityName, entityType) {
+        const typeLower = entityType.toLowerCase();
+        const names = this.index.get(typeLower);
+        if (names) {
+            names.delete(entityName);
+            if (names.size === 0) {
+                this.index.delete(typeLower);
+            }
+        }
+    }
+    /**
+     * Update an entity's type in the index.
+     * Removes from old type and adds to new type.
+     */
+    updateType(entityName, oldType, newType) {
+        this.remove(entityName, oldType);
+        this.addToIndex(entityName, newType);
+    }
+    /**
+     * Get all unique types in the index.
+     */
+    getTypes() {
+        return Array.from(this.index.keys());
+    }
+    /**
+     * Clear all entries from the index.
+     */
+    clear() {
+        this.index.clear();
+    }
+    addToIndex(entityName, entityType) {
+        const typeLower = entityType.toLowerCase();
+        let names = this.index.get(typeLower);
+        if (!names) {
+            names = new Set();
+            this.index.set(typeLower, names);
+        }
+        names.add(entityName);
+    }
+}
+/**
+ * LowercaseCache pre-computes lowercase versions of all searchable fields.
+ *
+ * Eliminates the need for repeated toLowerCase() calls during search,
+ * which is expensive with many entities and observations.
+ */
+export class LowercaseCache {
+    cache = new Map();
+    /**
+     * Build the cache from an array of entities.
+     * Clears any existing cache data first.
+     */
+    build(entities) {
+        this.cache.clear();
+        for (const entity of entities) {
+            this.cache.set(entity.name, this.computeLowercase(entity));
+        }
+    }
+    /**
+     * Get pre-computed lowercase data for an entity.
+     */
+    get(entityName) {
+        return this.cache.get(entityName);
+    }
+    /**
+     * Add or update an entity in the cache.
+     */
+    set(entity) {
+        this.cache.set(entity.name, this.computeLowercase(entity));
+    }
+    /**
+     * Remove an entity from the cache.
+     */
+    remove(entityName) {
+        this.cache.delete(entityName);
+    }
+    /**
+     * Check if an entity exists in the cache.
+     */
+    has(entityName) {
+        return this.cache.has(entityName);
+    }
+    /**
+     * Clear all entries from the cache.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of entries in the cache.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    computeLowercase(entity) {
+        return {
+            name: entity.name.toLowerCase(),
+            entityType: entity.entityType.toLowerCase(),
+            observations: entity.observations.map(o => o.toLowerCase()),
+            tags: entity.tags?.map(t => t.toLowerCase()) ?? [],
+        };
+    }
+}
+/**
+ * RelationIndex provides O(1) lookup of relations by entity name.
+ *
+ * Maintains two separate indexes for efficient directional queries:
+ * - fromIndex: Map from source entity name to its outgoing relations
+ * - toIndex: Map from target entity name to its incoming relations
+ *
+ * This eliminates O(n) array scans when looking up relations for an entity.
+ */
+export class RelationIndex {
+    /** Index of relations by source (from) entity */
+    fromIndex = new Map();
+    /** Index of relations by target (to) entity */
+    toIndex = new Map();
+    /**
+     * Build the index from an array of relations.
+     * Clears any existing index data first.
+     */
+    build(relations) {
+        this.fromIndex.clear();
+        this.toIndex.clear();
+        for (const relation of relations) {
+            this.addToIndexes(relation);
+        }
+    }
+    /**
+     * Get all relations where the entity is the source (outgoing relations).
+     * Returns empty array if no relations found.
+     */
+    getRelationsFrom(entityName) {
+        const relations = this.fromIndex.get(entityName);
+        return relations ? Array.from(relations) : [];
+    }
+    /**
+     * Get all relations where the entity is the target (incoming relations).
+     * Returns empty array if no relations found.
+     */
+    getRelationsTo(entityName) {
+        const relations = this.toIndex.get(entityName);
+        return relations ? Array.from(relations) : [];
+    }
+    /**
+     * Get all relations involving the entity (both incoming and outgoing).
+     * Returns empty array if no relations found.
+     */
+    getRelationsFor(entityName) {
+        const fromRelations = this.fromIndex.get(entityName);
+        const toRelations = this.toIndex.get(entityName);
+        // Combine sets to handle self-referential relations correctly
+        const combined = new Set();
+        if (fromRelations) {
+            for (const r of fromRelations) {
+                combined.add(r);
+            }
+        }
+        if (toRelations) {
+            for (const r of toRelations) {
+                combined.add(r);
+            }
+        }
+        return Array.from(combined);
+    }
+    /**
+     * Add a single relation to the index.
+     */
+    add(relation) {
+        this.addToIndexes(relation);
+    }
+    /**
+     * Remove a relation from the index.
+     * Matches by from, to, and relationType.
+     */
+    remove(relation) {
+        // Remove from fromIndex
+        const fromRelations = this.fromIndex.get(relation.from);
+        if (fromRelations) {
+            for (const r of fromRelations) {
+                if (r.from === relation.from && r.to === relation.to && r.relationType === relation.relationType) {
+                    fromRelations.delete(r);
+                    break;
+                }
+            }
+            if (fromRelations.size === 0) {
+                this.fromIndex.delete(relation.from);
+            }
+        }
+        // Remove from toIndex
+        const toRelations = this.toIndex.get(relation.to);
+        if (toRelations) {
+            for (const r of toRelations) {
+                if (r.from === relation.from && r.to === relation.to && r.relationType === relation.relationType) {
+                    toRelations.delete(r);
+                    break;
+                }
+            }
+            if (toRelations.size === 0) {
+                this.toIndex.delete(relation.to);
+            }
+        }
+    }
+    /**
+     * Remove all relations involving a specific entity.
+     * Returns the relations that were removed.
+     */
+    removeAllForEntity(entityName) {
+        const removed = [];
+        // Remove outgoing relations
+        const fromRelations = this.fromIndex.get(entityName);
+        if (fromRelations) {
+            for (const r of fromRelations) {
+                removed.push(r);
+                // Also remove from toIndex
+                const toRels = this.toIndex.get(r.to);
+                if (toRels) {
+                    toRels.delete(r);
+                    if (toRels.size === 0) {
+                        this.toIndex.delete(r.to);
+                    }
+                }
+            }
+            this.fromIndex.delete(entityName);
+        }
+        // Remove incoming relations
+        const toRelations = this.toIndex.get(entityName);
+        if (toRelations) {
+            for (const r of toRelations) {
+                // Skip self-referential relations (already handled above)
+                if (r.from === entityName)
+                    continue;
+                removed.push(r);
+                // Also remove from fromIndex
+                const fromRels = this.fromIndex.get(r.from);
+                if (fromRels) {
+                    fromRels.delete(r);
+                    if (fromRels.size === 0) {
+                        this.fromIndex.delete(r.from);
+                    }
+                }
+            }
+            this.toIndex.delete(entityName);
+        }
+        return removed;
+    }
+    /**
+     * Check if any relations exist for an entity.
+     */
+    hasRelations(entityName) {
+        return this.fromIndex.has(entityName) || this.toIndex.has(entityName);
+    }
+    /**
+     * Get count of outgoing relations for an entity.
+     */
+    getOutgoingCount(entityName) {
+        return this.fromIndex.get(entityName)?.size ?? 0;
+    }
+    /**
+     * Get count of incoming relations for an entity.
+     */
+    getIncomingCount(entityName) {
+        return this.toIndex.get(entityName)?.size ?? 0;
+    }
+    /**
+     * Get total count of unique relations in the index.
+     */
+    get size() {
+        // Count all relations in fromIndex (each relation appears exactly once there)
+        let count = 0;
+        for (const relations of this.fromIndex.values()) {
+            count += relations.size;
+        }
+        return count;
+    }
+    /**
+     * Clear all entries from the index.
+     */
+    clear() {
+        this.fromIndex.clear();
+        this.toIndex.clear();
+    }
+    addToIndexes(relation) {
+        // Add to fromIndex
+        let fromSet = this.fromIndex.get(relation.from);
+        if (!fromSet) {
+            fromSet = new Set();
+            this.fromIndex.set(relation.from, fromSet);
+        }
+        fromSet.add(relation);
+        // Add to toIndex
+        let toSet = this.toIndex.get(relation.to);
+        if (!toSet) {
+            toSet = new Set();
+            this.toIndex.set(relation.to, toSet);
+        }
+        toSet.add(relation);
+    }
+}
+/**
+ * Inverted index mapping observation keywords to entity names.
+ * Enables O(1) lookup for 'which entities mention word X?' queries.
+ * Words are normalized to lowercase and split on whitespace/punctuation.
+ */
+export class ObservationIndex {
+    index = new Map();
+    entityObservations = new Map();
+    /**
+     * Add an entity's observations to the index.
+     * Tokenizes observations into words and creates reverse mapping.
+     *
+     * @param entityName - Name of the entity
+     * @param observations - Array of observation strings
+     */
+    add(entityName, observations) {
+        const entityWords = new Set();
+        for (const observation of observations) {
+            const words = this.tokenize(observation);
+            for (const word of words) {
+                entityWords.add(word);
+                if (!this.index.has(word)) {
+                    this.index.set(word, new Set());
+                }
+                this.index.get(word).add(entityName);
+            }
+        }
+        this.entityObservations.set(entityName, entityWords);
+    }
+    /**
+     * Remove an entity from the index.
+     * Cleans up all word mappings for this entity.
+     *
+     * @param entityName - Name of the entity to remove
+     */
+    remove(entityName) {
+        const words = this.entityObservations.get(entityName);
+        if (!words)
+            return;
+        for (const word of words) {
+            const entities = this.index.get(word);
+            if (entities) {
+                entities.delete(entityName);
+                if (entities.size === 0) {
+                    this.index.delete(word);
+                }
+            }
+        }
+        this.entityObservations.delete(entityName);
+    }
+    /**
+     * Get all entities that have observations containing the given word.
+     * Word matching is case-insensitive.
+     *
+     * @param word - Word to search for
+     * @returns Set of entity names containing this word
+     */
+    getEntitiesWithWord(word) {
+        return this.index.get(word.toLowerCase()) ?? new Set();
+    }
+    /**
+     * Get all entities that have observations containing ANY of the given words (union).
+     *
+     * @param words - Array of words to search for
+     * @returns Set of entity names containing any of the words
+     */
+    getEntitiesWithAnyWord(words) {
+        const result = new Set();
+        for (const word of words) {
+            const entities = this.getEntitiesWithWord(word);
+            for (const entity of entities) {
+                result.add(entity);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get all entities that have observations containing ALL of the given words (intersection).
+     *
+     * @param words - Array of words that must all be present
+     * @returns Set of entity names containing all of the words
+     */
+    getEntitiesWithAllWords(words) {
+        if (words.length === 0)
+            return new Set();
+        let result = new Set(this.getEntitiesWithWord(words[0]));
+        for (let i = 1; i < words.length && result.size > 0; i++) {
+            const wordEntities = this.getEntitiesWithWord(words[i]);
+            result = new Set([...result].filter(e => wordEntities.has(e)));
+        }
+        return result;
+    }
+    /**
+     * Clear all entries from the index.
+     */
+    clear() {
+        this.index.clear();
+        this.entityObservations.clear();
+    }
+    /**
+     * Get statistics about the index.
+     *
+     * @returns Object with wordCount and entityCount
+     */
+    getStats() {
+        return {
+            wordCount: this.index.size,
+            entityCount: this.entityObservations.size,
+        };
+    }
+    /**
+     * Tokenize text into searchable words.
+     * Normalizes to lowercase, splits on non-alphanumeric characters,
+     * and filters out words less than 2 characters.
+     *
+     * @param text - Text to tokenize
+     * @returns Array of normalized words
+     */
+    tokenize(text) {
+        return text
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter(word => word.length >= 2);
+    }
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Simple logging utility for the Memory MCP Server
+ *
+ * Provides consistent log formatting with levels: debug, info, warn, error
+ */
+export declare const logger: {
+    /**
+     * Debug level logging (verbose, for development)
+     */
+    debug: (msg: string, ...args: unknown[]) => void;
+    /**
+     * Info level logging (general informational messages)
+     */
+    info: (msg: string, ...args: unknown[]) => void;
+    /**
+     * Warning level logging (warnings that don't prevent operation)
+     */
+    warn: (msg: string, ...args: unknown[]) => void;
+    /**
+     * Error level logging (errors that affect functionality)
+     */
+    error: (msg: string, ...args: unknown[]) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,MAAM;IACjB;;OAEG;iBACU,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;IAM9C;;OAEG;gBACS,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;IAI7C;;OAEG;gBACS,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;IAI7C;;OAEG;iBACU,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;CAG/C,CAAC"}

package/dist/utils/operationUtils.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Operation Utilities
+ *
+ * Phase 9B: Utilities for long-running operations with progress tracking
+ * and cancellation support.
+ *
+ * @module utils/operationUtils
+ */
+import type { ProgressCallback } from './taskScheduler.js';
+/**
+ * Check if an operation has been cancelled via AbortSignal.
+ * Throws OperationCancelledError if the signal is aborted.
+ *
+ * @param signal - Optional AbortSignal to check
+ * @param operation - Optional operation name for error message
+ * @throws OperationCancelledError if signal is aborted
+ *
+ * @example
+ * ```typescript
+ * for (const item of items) {
+ *   checkCancellation(options?.signal, 'batch processing');
+ *   await processItem(item);
+ * }
+ * ```
+ */
+export declare function checkCancellation(signal?: AbortSignal, operation?: string): void;
+/**
+ * Create a throttled progress reporter to avoid excessive callback invocations.
+ * Returns undefined if no callback is provided.
+ *
+ * @param callback - Optional progress callback to throttle
+ * @param throttleMs - Minimum time between callbacks (default: 100ms)
+ * @returns Throttled callback or undefined
+ *
+ * @example
+ * ```typescript
+ * const reportProgress = createProgressReporter(options?.onProgress, 50);
+ * for (let i = 0; i < total; i++) {
+ *   reportProgress?.({ completed: i, total, percentage: (i / total) * 100 });
+ * }
+ * ```
+ */
+export declare function createProgressReporter(callback?: ProgressCallback, throttleMs?: number): ProgressCallback | undefined;
+/**
+ * Create a progress object for reporting.
+ *
+ * @param completed - Number of completed items
+ * @param total - Total number of items
+ * @param currentTaskId - Optional current task identifier
+ * @returns Progress object suitable for ProgressCallback
+ *
+ * @example
+ * ```typescript
+ * reportProgress?.(createProgress(50, 100, 'processing entities'));
+ * // { completed: 50, total: 100, percentage: 50, currentTaskId: 'processing entities' }
+ * ```
+ */
+export declare function createProgress(completed: number, total: number, currentTaskId?: string): {
+    completed: number;
+    total: number;
+    percentage: number;
+    currentTaskId?: string;
+};
+/**
+ * Phase definition for executeWithPhases.
+ */
+export interface PhaseDefinition<T> {
+    /** Phase name (used for progress reporting and cancellation error messages) */
+    name: string;
+    /** Weight of this phase relative to others (higher = more of total progress) */
+    weight: number;
+    /** Executor function that performs the phase work */
+    execute: (phaseProgress: (pct: number) => void) => Promise<T>;
+}
+/**
+ * Execute an operation with multiple distinct phases.
+ * Useful when an operation has multiple distinct phases with different weights.
+ *
+ * @param phases - Array of phase definitions with weight and executor
+ * @param onProgress - Optional progress callback
+ * @param signal - Optional abort signal
+ * @returns Array of results from each phase
+ * @throws OperationCancelledError if cancelled during any phase
+ *
+ * @example
+ * ```typescript
+ * const [parseResult, processResult, saveResult] = await executeWithPhases([
+ *   { name: 'parsing', weight: 20, execute: () => parseData() },
+ *   { name: 'processing', weight: 60, execute: () => processEntities() },
+ *   { name: 'saving', weight: 20, execute: () => saveResults() },
+ * ], options?.onProgress, options?.signal);
+ * ```
+ */
+export declare function executeWithPhases<T>(phases: PhaseDefinition<T>[], onProgress?: ProgressCallback, signal?: AbortSignal): Promise<T[]>;
+/**
+ * Execute an operation in batches with progress tracking and cancellation support.
+ *
+ * @param items - Array of items to process
+ * @param batchSize - Size of each batch
+ * @param processBatch - Function to process each batch
+ * @param onProgress - Optional progress callback
+ * @param signal - Optional abort signal
+ * @param operationName - Optional operation name for cancellation error
+ * @returns Array of results from all batches
+ *
+ * @example
+ * ```typescript
+ * const results = await processBatchesWithProgress(
+ *   entities,
+ *   100,
+ *   async (batch) => {
+ *     for (const entity of batch) {
+ *       await saveEntity(entity);
+ *     }
+ *     return batch.length;
+ *   },
+ *   options?.onProgress,
+ *   options?.signal,
+ *   'createEntities'
+ * );
+ * ```
+ */
+export declare function processBatchesWithProgress<T, R>(items: T[], batchSize: number, processBatch: (batch: T[], batchIndex: number) => Promise<R>, onProgress?: ProgressCallback, signal?: AbortSignal, operationName?: string): Promise<R[]>;
+//# sourceMappingURL=operationUtils.d.ts.map

package/dist/utils/operationUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operationUtils.d.ts","sourceRoot":"","sources":["../../src/utils/operationUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAIhF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,UAAU,GAAE,MAAY,GACvB,gBAAgB,GAAG,SAAS,CAa9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,GACrB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAOlF;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,EAC5B,UAAU,CAAC,EAAE,gBAAgB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,EAAE,CAAC,CAkCd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,EAAE,CAAC,EACnD,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC5D,UAAU,CAAC,EAAE,gBAAgB,EAC7B,MAAM,CAAC,EAAE,WAAW,EACpB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,CAAC,EAAE,CAAC,CAqBd"}