@danielsimonjr/memory-mcp 0.48.0 → 9.8.0

package/dist/__tests__/file-path.test.js

@@ -38,14 +38,10 @@ describe('ensureMemoryFilePath', () => {
     });
     describe('with MEMORY_FILE_PATH environment variable', () => {
         it('should return absolute path when MEMORY_FILE_PATH is absolute', async () => {
-            // Use platform-appropriate absolute path
-            const absolutePath = process.platform === 'win32'
-                ? 'C:\\tmp\\custom-memory.jsonl'
-                : '/tmp/custom-memory.jsonl';
+            const absolutePath = '/tmp/custom-memory.jsonl';
             process.env.MEMORY_FILE_PATH = absolutePath;
             const result = await ensureMemoryFilePath();
-            // Path may be normalized (backslashes on Windows)
-            expect(path.normalize(result)).toBe(path.normalize(absolutePath));
+            expect(result).toBe(absolutePath);
         });
         it('should convert relative path to absolute when MEMORY_FILE_PATH is relative', async () => {
             const relativePath = 'custom-memory.jsonl';
@@ -75,7 +71,7 @@ describe('ensureMemoryFilePath', () => {
         it('should migrate from memory.json to memory.jsonl when only old file exists', async () => {
             // Create old memory.json file
             await fs.writeFile(oldMemoryPath, '{"test":"data"}');
-            const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+            const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
             const result = await ensureMemoryFilePath();
             expect(result).toBe(defaultMemoryPath);
             // Verify migration happened
@@ -83,10 +79,10 @@ describe('ensureMemoryFilePath', () => {
             const oldFileExists = await fs.access(oldMemoryPath).then(() => true).catch(() => false);
             expect(newFileExists).toBe(true);
             expect(oldFileExists).toBe(false);
-            // Verify console messages (now using console.log instead of console.error)
-            expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('[INFO] Found legacy memory.json file'));
-            expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('[INFO] Successfully migrated'));
-            consoleLogSpy.mockRestore();
+            // Verify console messages
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('DETECTED: Found legacy memory.json file'));
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('COMPLETED: Successfully migrated'));
+            consoleErrorSpy.mockRestore();
         });
         it('should use new file when both old and new files exist', async () => {
             // Create both files

package/dist/__tests__/knowledge-graph.test.js

@@ -28,9 +28,7 @@ describe('KnowledgeGraphManager', () => {
             ];
             const newEntities = await manager.createEntities(entities);
             expect(newEntities).toHaveLength(2);
-            // Entities now have timestamps, so check core fields
-            expect(newEntities[0].name).toBe(entities[0].name);
-            expect(newEntities[1].name).toBe(entities[1].name);
+            expect(newEntities).toEqual(entities);
             const graph = await manager.readGraph();
             expect(graph.entities).toHaveLength(2);
         });
@@ -60,10 +58,7 @@ describe('KnowledgeGraphManager', () => {
             ];
             const newRelations = await manager.createRelations(relations);
             expect(newRelations).toHaveLength(1);
-            // Relations now have timestamps, so check core fields
-            expect(newRelations[0].from).toBe(relations[0].from);
-            expect(newRelations[0].to).toBe(relations[0].to);
-            expect(newRelations[0].relationType).toBe(relations[0].relationType);
+            expect(newRelations).toEqual(relations);
             const graph = await manager.readGraph();
             expect(graph.relations).toHaveLength(1);
         });
@@ -120,7 +115,7 @@ describe('KnowledgeGraphManager', () => {
         it('should throw error for non-existent entity', async () => {
             await expect(manager.addObservations([
                 { entityName: 'NonExistent', contents: ['some observation'] },
-            ])).rejects.toThrow('Entity "NonExistent" not found');
+            ])).rejects.toThrow('Entity with name NonExistent not found');
         });
     });
     describe('deleteEntities', () => {

package/dist/core/EntityManager.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Entity Manager
+ *
+ * Handles CRUD operations for entities in the knowledge graph.
+ * Focused on core entity and tag operations only (Phase 4: Consolidate God Objects).
+ *
+ * @module core/EntityManager
+ */
+import type { Entity, LongRunningOperationOptions } from '../types/index.js';
+import type { GraphStorage } from './GraphStorage.js';
+/**
+ * Manages entity operations with automatic timestamp handling.
+ */
+export declare class EntityManager {
+    private storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Create multiple entities in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Filters out entities that already exist (duplicate names)
+     * - Automatically adds createdAt and lastModified timestamps
+     * - Normalizes all tags to lowercase for consistent searching
+     * - Validates importance values (must be between 0-10)
+     *
+     * Phase 9B: Supports progress tracking and cancellation via LongRunningOperationOptions.
+     *
+     * @param entities - Array of entities to create. Each entity must have a unique name.
+     * @param options - Optional progress/cancellation options (Phase 9B)
+     * @returns Promise resolving to array of newly created entities (excludes duplicates)
+     * @throws {InvalidImportanceError} If any entity has importance outside the valid range [0-10]
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Create single entity
+     * const results = await manager.createEntities([{
+     *   name: 'Alice',
+     *   entityType: 'person',
+     *   observations: ['Works as engineer', 'Lives in Seattle'],
+     *   importance: 7,
+     *   tags: ['Team', 'Engineering']
+     * }]);
+     *
+     * // Create multiple entities at once
+     * const users = await manager.createEntities([
+     *   { name: 'Bob', entityType: 'person', observations: [] },
+     *   { name: 'Charlie', entityType: 'person', observations: [] }
+     * ]);
+     *
+     * // With progress tracking and cancellation (Phase 9B)
+     * const controller = new AbortController();
+     * const results = await manager.createEntities(largeEntityArray, {
+     *   signal: controller.signal,
+     *   onProgress: (p) => console.log(`${p.percentage}% complete`),
+     * });
+     * ```
+     */
+    createEntities(entities: Entity[], options?: LongRunningOperationOptions): Promise<Entity[]>;
+    /**
+     * Delete multiple entities by name in a single batch operation.
+     *
+     * This method performs cascading deletion:
+     * - Removes all specified entities from the graph
+     * - Automatically removes all relations where these entities are source or target
+     * - Silently ignores entity names that don't exist (no error thrown)
+     *
+     * @param entityNames - Array of entity names to delete
+     * @returns Promise that resolves when deletion is complete
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Delete single entity
+     * await manager.deleteEntities(['Alice']);
+     *
+     * // Delete multiple entities at once
+     * await manager.deleteEntities(['Bob', 'Charlie', 'Dave']);
+     *
+     * // Safe to delete non-existent entities (no error)
+     * await manager.deleteEntities(['NonExistent']); // No error thrown
+     * ```
+     */
+    deleteEntities(entityNames: string[]): Promise<void>;
+    /**
+     * Retrieve a single entity by its unique name.
+     *
+     * This is a read-only operation that does not modify the graph.
+     * Entity names are case-sensitive.
+     *
+     * @param name - The unique name of the entity to retrieve
+     * @returns Promise resolving to the Entity object if found, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Get an existing entity
+     * const alice = await manager.getEntity('Alice');
+     * if (alice) {
+     *   console.log(alice.observations);
+     *   console.log(alice.importance);
+     * }
+     *
+     * // Handle non-existent entity
+     * const missing = await manager.getEntity('NonExistent');
+     * console.log(missing); // null
+     * ```
+     */
+    getEntity(name: string): Promise<Entity | null>;
+    /**
+     * Update one or more fields of an existing entity.
+     *
+     * This method allows partial updates - only the fields specified in the updates
+     * object will be changed. All other fields remain unchanged.
+     * The lastModified timestamp is automatically updated.
+     *
+     * @param name - The unique name of the entity to update
+     * @param updates - Partial entity object containing only the fields to update
+     * @returns Promise resolving to the fully updated Entity object
+     * @throws {EntityNotFoundError} If no entity with the given name exists
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Update importance only
+     * const updated = await manager.updateEntity('Alice', {
+     *   importance: 9
+     * });
+     *
+     * // Update multiple fields
+     * await manager.updateEntity('Bob', {
+     *   entityType: 'senior_engineer',
+     *   tags: ['leadership', 'architecture'],
+     *   observations: ['Led project X', 'Designed system Y']
+     * });
+     *
+     * // Add observations (requires reading existing entity first)
+     * const entity = await manager.getEntity('Charlie');
+     * if (entity) {
+     *   await manager.updateEntity('Charlie', {
+     *     observations: [...entity.observations, 'New observation']
+     *   });
+     * }
+     * ```
+     */
+    updateEntity(name: string, updates: Partial<Entity>): Promise<Entity>;
+    /**
+     * Update multiple entities in a single batch operation.
+     *
+     * This method is more efficient than calling updateEntity multiple times
+     * as it loads and saves the graph only once. All updates are applied atomically.
+     * The lastModified timestamp is automatically updated for all entities.
+     *
+     * @param updates - Array of updates, each containing entity name and changes
+     * @returns Promise resolving to array of updated entities
+     * @throws {EntityNotFoundError} If any entity is not found
+     * @throws {ValidationError} If any update data is invalid
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Update multiple entities at once
+     * const updated = await manager.batchUpdate([
+     *   { name: 'Alice', updates: { importance: 9 } },
+     *   { name: 'Bob', updates: { importance: 8, tags: ['senior'] } },
+     *   { name: 'Charlie', updates: { entityType: 'lead_engineer' } }
+     * ]);
+     *
+     * console.log(`Updated ${updated.length} entities`);
+     *
+     * // Efficiently update many entities (single graph load/save)
+     * const massUpdate = employees.map(name => ({
+     *   name,
+     *   updates: { tags: ['team-2024'] }
+     * }));
+     * await manager.batchUpdate(massUpdate);
+     * ```
+     */
+    batchUpdate(updates: Array<{
+        name: string;
+        updates: Partial<Entity>;
+    }>): Promise<Entity[]>;
+    /**
+     * Add tags to an entity.
+     *
+     * Tags are normalized to lowercase and duplicates are filtered out.
+     *
+     * @param entityName - Name of the entity
+     * @param tags - Tags to add
+     * @returns Result with entity name and added tags
+     * @throws {EntityNotFoundError} If entity is not found
+     */
+    addTags(entityName: string, tags: string[]): Promise<{
+        entityName: string;
+        addedTags: string[];
+    }>;
+    /**
+     * Remove tags from an entity.
+     *
+     * @param entityName - Name of the entity
+     * @param tags - Tags to remove
+     * @returns Result with entity name and removed tags
+     * @throws {EntityNotFoundError} If entity is not found
+     */
+    removeTags(entityName: string, tags: string[]): Promise<{
+        entityName: string;
+        removedTags: string[];
+    }>;
+    /**
+     * Set importance level for an entity.
+     *
+     * @param entityName - Name of the entity
+     * @param importance - Importance level (0-10)
+     * @returns Result with entity name and importance
+     * @throws {EntityNotFoundError} If entity is not found
+     * @throws {Error} If importance is out of range
+     */
+    setImportance(entityName: string, importance: number): Promise<{
+        entityName: string;
+        importance: number;
+    }>;
+    /**
+     * Add tags to multiple entities in a single operation.
+     *
+     * @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
+     */
+    addTagsToMultipleEntities(entityNames: string[], tags: string[]): Promise<{
+        entityName: string;
+        addedTags: string[];
+    }[]>;
+    /**
+     * Replace a tag with a new tag across all entities (rename tag).
+     *
+     * @param oldTag - Tag to replace
+     * @param newTag - New tag value
+     * @returns Result with affected entities and count
+     */
+    replaceTag(oldTag: string, newTag: string): Promise<{
+        affectedEntities: string[];
+        count: number;
+    }>;
+    /**
+     * Merge two tags into one target tag across all entities.
+     *
+     * Combines tag1 and tag2 into targetTag. Any entity with either tag1 or tag2
+     * will have both removed and targetTag added (if not already present).
+     *
+     * @param tag1 - First tag to merge
+     * @param tag2 - Second tag to merge
+     * @param targetTag - Target tag to merge into
+     * @returns Object with affected entity names and count
+     */
+    mergeTags(tag1: string, tag2: string, targetTag: string): Promise<{
+        affectedEntities: string[];
+        count: number;
+    }>;
+}
+//# sourceMappingURL=EntityManager.d.ts.map

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

@@ -0,0 +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;AAwBtD;;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"}