@danielsimonjr/memory-mcp 0.48.0 → 9.8.0

package/dist/{features → core}/HierarchyManager.js

@@ -1,13 +1,14 @@
 /**
  * Hierarchy Manager
  *
- * Manages entity parent-child relationships and hierarchical operations.
+ * Handles entity hierarchy operations (parent-child relationships).
+ * Extracted from EntityManager (Phase 4: Consolidate God Objects).
  *
- * @module features/HierarchyManager
+ * @module core/HierarchyManager
  */
 import { EntityNotFoundError, CycleDetectedError } from '../utils/errors.js';
 /**
- * Manages hierarchical entity relationships.
+ * Manages hierarchical relationships between entities.
  */
 export class HierarchyManager {
     storage;
@@ -28,22 +29,26 @@ export class HierarchyManager {
      * @throws {CycleDetectedError} If setting parent would create a cycle
      */
     async setEntityParent(entityName, parentName) {
-        const graph = await this.storage.loadGraph();
-        const entity = graph.entities.find(e => e.name === entityName);
-        if (!entity) {
+        // Use read-only graph for validation checks
+        const readGraph = await this.storage.loadGraph();
+        const entityExists = readGraph.entities.find(e => e.name === entityName);
+        if (!entityExists) {
             throw new EntityNotFoundError(entityName);
         }
         // If setting a parent, validate it exists and doesn't create a cycle
         if (parentName !== null) {
-            const parent = graph.entities.find(e => e.name === parentName);
+            const parent = readGraph.entities.find(e => e.name === parentName);
             if (!parent) {
                 throw new EntityNotFoundError(parentName);
             }
             // Check for cycles
-            if (this.wouldCreateCycle(graph, entityName, parentName)) {
+            if (this.wouldCreateCycle(readGraph, entityName, parentName)) {
                 throw new CycleDetectedError(entityName, parentName);
             }
         }
+        // Get mutable copy for write operation
+        const graph = await this.storage.getGraphForMutation();
+        const entity = graph.entities.find(e => e.name === entityName);
         entity.parentId = parentName || undefined;
         entity.lastModified = new Date().toISOString();
         await this.storage.saveGraph(graph);
@@ -198,7 +203,7 @@ export class HierarchyManager {
      *
      * @param entityName - Entity name
      * @returns Depth (number of ancestors)
-     * @throws Error if entity not found
+     * @throws {EntityNotFoundError} If entity not found
      */
     async getEntityDepth(entityName) {
         const ancestors = await this.getAncestors(entityName);

package/dist/core/ManagerContext.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Manager Context
+ *
+ * Central context holding all manager instances with lazy initialization.
+ * Provides direct manager access for toolHandlers.
+ * Phase 4: Removed convenience methods - use managers directly.
+ *
+ * @module core/ManagerContext
+ */
+import { GraphStorage } from './GraphStorage.js';
+import { EntityManager } from './EntityManager.js';
+import { RelationManager } from './RelationManager.js';
+import { ObservationManager } from './ObservationManager.js';
+import { HierarchyManager } from './HierarchyManager.js';
+import { GraphTraversal } from './GraphTraversal.js';
+import { SearchManager } from '../search/SearchManager.js';
+import { SemanticSearch } from '../search/index.js';
+import { IOManager } from '../features/IOManager.js';
+import { TagManager } from '../features/TagManager.js';
+import { AnalyticsManager } from '../features/AnalyticsManager.js';
+import { CompressionManager } from '../features/CompressionManager.js';
+import { ArchiveManager } from '../features/ArchiveManager.js';
+/**
+ * Context holding all manager instances with lazy initialization.
+ * Provides direct manager access for toolHandlers.
+ */
+export declare class ManagerContext {
+    readonly storage: GraphStorage;
+    private readonly savedSearchesFilePath;
+    private readonly tagAliasesFilePath;
+    private _entityManager?;
+    private _relationManager?;
+    private _observationManager?;
+    private _hierarchyManager?;
+    private _graphTraversal?;
+    private _searchManager?;
+    private _semanticSearch?;
+    private _ioManager?;
+    private _tagManager?;
+    private _analyticsManager?;
+    private _compressionManager?;
+    private _archiveManager?;
+    constructor(memoryFilePath: string);
+    /** EntityManager - Entity CRUD and tag operations */
+    get entityManager(): EntityManager;
+    /** RelationManager - Relation CRUD */
+    get relationManager(): RelationManager;
+    /** ObservationManager - Observation CRUD */
+    get observationManager(): ObservationManager;
+    /** HierarchyManager - Entity hierarchy operations */
+    get hierarchyManager(): HierarchyManager;
+    /** GraphTraversal - Phase 4 Sprint 6-8: Graph traversal algorithms */
+    get graphTraversal(): GraphTraversal;
+    /** SearchManager - All search operations */
+    get searchManager(): SearchManager;
+    /**
+     * SemanticSearch - Phase 4 Sprint 12: Semantic similarity search.
+     * Returns null if no embedding provider is configured.
+     */
+    get semanticSearch(): SemanticSearch | null;
+    /** IOManager - Import, export, and backup operations */
+    get ioManager(): IOManager;
+    /** TagManager - Tag alias management */
+    get tagManager(): TagManager;
+    /** AnalyticsManager - Graph statistics and validation */
+    get analyticsManager(): AnalyticsManager;
+    /** CompressionManager - Duplicate detection and entity merging */
+    get compressionManager(): CompressionManager;
+    /** ArchiveManager - Entity archival operations */
+    get archiveManager(): ArchiveManager;
+}
+//# sourceMappingURL=ManagerContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ManagerContext.d.ts","sourceRoot":"","sources":["../../src/core/ManagerContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAA6C,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG/D;;;GAGG;AACH,qBAAa,cAAc;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAG5C,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,gBAAgB,CAAC,CAAkB;IAC3C,OAAO,CAAC,mBAAmB,CAAC,CAAqB;IACjD,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAC7C,OAAO,CAAC,eAAe,CAAC,CAAiB;IACzC,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,eAAe,CAAC,CAAwB;IAChD,OAAO,CAAC,UAAU,CAAC,CAAY;IAC/B,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAC7C,OAAO,CAAC,mBAAmB,CAAC,CAAqB;IACjD,OAAO,CAAC,eAAe,CAAC,CAAiB;gBAE7B,cAAc,EAAE,MAAM;IAYlC,qDAAqD;IACrD,IAAI,aAAa,IAAI,aAAa,CAEjC;IAED,sCAAsC;IACtC,IAAI,eAAe,IAAI,eAAe,CAErC;IAED,4CAA4C;IAC5C,IAAI,kBAAkB,IAAI,kBAAkB,CAE3C;IAED,qDAAqD;IACrD,IAAI,gBAAgB,IAAI,gBAAgB,CAEvC;IAED,sEAAsE;IACtE,IAAI,cAAc,IAAI,cAAc,CAEnC;IAED,4CAA4C;IAC5C,IAAI,aAAa,IAAI,aAAa,CAEjC;IAED;;;OAGG;IACH,IAAI,cAAc,IAAI,cAAc,GAAG,IAAI,CAa1C;IAED,wDAAwD;IACxD,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED,wCAAwC;IACxC,IAAI,UAAU,IAAI,UAAU,CAE3B;IAED,yDAAyD;IACzD,IAAI,gBAAgB,IAAI,gBAAgB,CAEvC;IAED,kEAAkE;IAClE,IAAI,kBAAkB,IAAI,kBAAkB,CAE3C;IAED,kDAAkD;IAClD,IAAI,cAAc,IAAI,cAAc,CAEnC;CACF"}

package/dist/core/ManagerContext.js

@@ -0,0 +1,118 @@
+/**
+ * Manager Context
+ *
+ * Central context holding all manager instances with lazy initialization.
+ * Provides direct manager access for toolHandlers.
+ * Phase 4: Removed convenience methods - use managers directly.
+ *
+ * @module core/ManagerContext
+ */
+import path from 'path';
+import { GraphStorage } from './GraphStorage.js';
+import { EntityManager } from './EntityManager.js';
+import { RelationManager } from './RelationManager.js';
+import { ObservationManager } from './ObservationManager.js';
+import { HierarchyManager } from './HierarchyManager.js';
+import { GraphTraversal } from './GraphTraversal.js';
+import { SearchManager } from '../search/SearchManager.js';
+import { SemanticSearch, createEmbeddingService, createVectorStore } from '../search/index.js';
+import { IOManager } from '../features/IOManager.js';
+import { TagManager } from '../features/TagManager.js';
+import { AnalyticsManager } from '../features/AnalyticsManager.js';
+import { CompressionManager } from '../features/CompressionManager.js';
+import { ArchiveManager } from '../features/ArchiveManager.js';
+import { getEmbeddingConfig } from '../utils/constants.js';
+/**
+ * Context holding all manager instances with lazy initialization.
+ * Provides direct manager access for toolHandlers.
+ */
+export class ManagerContext {
+    storage;
+    savedSearchesFilePath;
+    tagAliasesFilePath;
+    // Lazy-initialized managers
+    _entityManager;
+    _relationManager;
+    _observationManager;
+    _hierarchyManager;
+    _graphTraversal;
+    _searchManager;
+    _semanticSearch;
+    _ioManager;
+    _tagManager;
+    _analyticsManager;
+    _compressionManager;
+    _archiveManager;
+    constructor(memoryFilePath) {
+        // Derive paths for saved searches and tag aliases
+        const dir = path.dirname(memoryFilePath);
+        const basename = path.basename(memoryFilePath, path.extname(memoryFilePath));
+        this.savedSearchesFilePath = path.join(dir, `${basename}-saved-searches.jsonl`);
+        this.tagAliasesFilePath = path.join(dir, `${basename}-tag-aliases.jsonl`);
+        this.storage = new GraphStorage(memoryFilePath);
+    }
+    // ==================== MANAGER ACCESSORS ====================
+    // Use these for direct manager access in toolHandlers
+    /** EntityManager - Entity CRUD and tag operations */
+    get entityManager() {
+        return (this._entityManager ??= new EntityManager(this.storage));
+    }
+    /** RelationManager - Relation CRUD */
+    get relationManager() {
+        return (this._relationManager ??= new RelationManager(this.storage));
+    }
+    /** ObservationManager - Observation CRUD */
+    get observationManager() {
+        return (this._observationManager ??= new ObservationManager(this.storage));
+    }
+    /** HierarchyManager - Entity hierarchy operations */
+    get hierarchyManager() {
+        return (this._hierarchyManager ??= new HierarchyManager(this.storage));
+    }
+    /** GraphTraversal - Phase 4 Sprint 6-8: Graph traversal algorithms */
+    get graphTraversal() {
+        return (this._graphTraversal ??= new GraphTraversal(this.storage));
+    }
+    /** SearchManager - All search operations */
+    get searchManager() {
+        return (this._searchManager ??= new SearchManager(this.storage, this.savedSearchesFilePath));
+    }
+    /**
+     * SemanticSearch - Phase 4 Sprint 12: Semantic similarity search.
+     * Returns null if no embedding provider is configured.
+     */
+    get semanticSearch() {
+        if (this._semanticSearch === undefined) {
+            const config = getEmbeddingConfig();
+            const embeddingService = createEmbeddingService(config);
+            if (embeddingService) {
+                const vectorStore = createVectorStore('jsonl'); // Use in-memory for now
+                this._semanticSearch = new SemanticSearch(embeddingService, vectorStore);
+            }
+            else {
+                this._semanticSearch = null;
+            }
+        }
+        return this._semanticSearch;
+    }
+    /** IOManager - Import, export, and backup operations */
+    get ioManager() {
+        return (this._ioManager ??= new IOManager(this.storage));
+    }
+    /** TagManager - Tag alias management */
+    get tagManager() {
+        return (this._tagManager ??= new TagManager(this.tagAliasesFilePath));
+    }
+    /** AnalyticsManager - Graph statistics and validation */
+    get analyticsManager() {
+        return (this._analyticsManager ??= new AnalyticsManager(this.storage));
+    }
+    /** CompressionManager - Duplicate detection and entity merging */
+    get compressionManager() {
+        return (this._compressionManager ??= new CompressionManager(this.storage));
+    }
+    /** ArchiveManager - Entity archival operations */
+    get archiveManager() {
+        return (this._archiveManager ??= new ArchiveManager(this.storage));
+    }
+}

package/dist/core/ObservationManager.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Observation Manager
+ *
+ * Handles observation CRUD operations for entities.
+ * Extracted from EntityManager (Phase 4: Consolidate God Objects).
+ *
+ * @module core/ObservationManager
+ */
+import type { GraphStorage } from './GraphStorage.js';
+/**
+ * Manages observation operations for entities in the knowledge graph.
+ */
+export declare class ObservationManager {
+    private storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Add observations to multiple entities in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Adds new observations to specified entities
+     * - Filters out duplicate observations (already present)
+     * - Updates lastModified timestamp only if new observations were added
+     * - ATOMIC: All updates are saved in a single operation
+     *
+     * @param observations - Array of entity names and observations to add
+     * @returns Promise resolving to array of results showing which observations were added
+     * @throws {EntityNotFoundError} If any entity is not found
+     *
+     * @example
+     * ```typescript
+     * const manager = new ObservationManager(storage);
+     *
+     * // Add observations to multiple entities
+     * const results = await manager.addObservations([
+     *   { entityName: 'Alice', contents: ['Completed project X', 'Started project Y'] },
+     *   { entityName: 'Bob', contents: ['Joined team meeting'] }
+     * ]);
+     *
+     * // Check what was added (duplicates are filtered out)
+     * results.forEach(r => {
+     *   console.log(`${r.entityName}: added ${r.addedObservations.length} new observations`);
+     * });
+     * ```
+     */
+    addObservations(observations: {
+        entityName: string;
+        contents: string[];
+    }[]): Promise<{
+        entityName: string;
+        addedObservations: string[];
+    }[]>;
+    /**
+     * Delete observations from multiple entities in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Removes specified observations from entities
+     * - Updates lastModified timestamp only if observations were deleted
+     * - Silently ignores entities that don't exist (no error thrown)
+     * - ATOMIC: All deletions are saved in a single operation
+     *
+     * @param deletions - Array of entity names and observations to delete
+     * @returns Promise that resolves when deletion is complete
+     *
+     * @example
+     * ```typescript
+     * const manager = new ObservationManager(storage);
+     *
+     * // Delete observations from multiple entities
+     * await manager.deleteObservations([
+     *   { entityName: 'Alice', observations: ['Old observation 1', 'Old observation 2'] },
+     *   { entityName: 'Bob', observations: ['Outdated info'] }
+     * ]);
+     *
+     * // Safe to delete from non-existent entities (no error)
+     * await manager.deleteObservations([
+     *   { entityName: 'NonExistent', observations: ['Some text'] }
+     * ]); // No error thrown
+     * ```
+     */
+    deleteObservations(deletions: {
+        entityName: string;
+        observations: string[];
+    }[]): Promise<void>;
+}
+//# sourceMappingURL=ObservationManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ObservationManager.d.ts","sourceRoot":"","sources":["../../src/core/ObservationManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;;GAEG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,eAAe,CACnB,YAAY,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,GACzD,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAiCjE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,kBAAkB,CACtB,SAAS,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,GAC1D,OAAO,CAAC,IAAI,CAAC;CAyBjB"}

package/dist/core/ObservationManager.js

@@ -1,13 +1,14 @@
 /**
  * Observation Manager
  *
- * Handles CRUD operations for observations within entities.
+ * Handles observation CRUD operations for entities.
+ * Extracted from EntityManager (Phase 4: Consolidate God Objects).
  *
  * @module core/ObservationManager
  */
 import { EntityNotFoundError } from '../utils/errors.js';
 /**
- * Manages observation operations with automatic timestamp handling.
+ * Manages observation operations for entities in the knowledge graph.
  */
 export class ObservationManager {
     storage;
@@ -18,112 +19,105 @@ export class ObservationManager {
      * Add observations to multiple entities in a single batch operation.
      *
      * This method performs the following operations:
-     * - Validates that all specified entities exist
-     * - Filters out duplicate observations (observations already present)
-     * - Adds new observations to each entity
-     * - Automatically updates lastModified timestamp for modified entities
+     * - Adds new observations to specified entities
+     * - Filters out duplicate observations (already present)
+     * - Updates lastModified timestamp only if new observations were added
+     * - ATOMIC: All updates are saved in a single operation
      *
-     * @param observations - Array of objects, each containing entityName and array of observation contents
-     * @returns Promise resolving to array of results showing added observations per entity
-     * @throws {EntityNotFoundError} If any specified entity does not exist
+     * @param observations - Array of entity names and observations to add
+     * @returns Promise resolving to array of results showing which observations were added
+     * @throws {EntityNotFoundError} If any entity is not found
      *
      * @example
      * ```typescript
      * const manager = new ObservationManager(storage);
      *
-     * // Add observations to single entity
+     * // Add observations to multiple entities
      * const results = await manager.addObservations([
-     *   {
-     *     entityName: 'Alice',
-     *     contents: ['Works on frontend', 'Expertise in React']
-     *   }
+     *   { entityName: 'Alice', contents: ['Completed project X', 'Started project Y'] },
+     *   { entityName: 'Bob', contents: ['Joined team meeting'] }
      * ]);
-     * console.log(results[0].addedObservations); // ['Works on frontend', 'Expertise in React']
      *
-     * // Add observations to multiple entities at once
-     * await manager.addObservations([
-     *   { entityName: 'Bob', contents: ['Team lead', 'Experienced in Node.js'] },
-     *   { entityName: 'Charlie', contents: ['New hire', 'Learning the codebase'] }
-     * ]);
-     *
-     * // Duplicate observations are filtered out
-     * await manager.addObservations([
-     *   { entityName: 'Alice', contents: ['Works on frontend'] } // Already exists, won't be added
-     * ]);
+     * // Check what was added (duplicates are filtered out)
+     * results.forEach(r => {
+     *   console.log(`${r.entityName}: added ${r.addedObservations.length} new observations`);
+     * });
      * ```
      */
     async addObservations(observations) {
-        const graph = await this.storage.loadGraph();
+        // Get mutable graph for atomic update
+        const graph = await this.storage.getGraphForMutation();
         const timestamp = new Date().toISOString();
-        const results = observations.map(o => {
+        const results = [];
+        let hasChanges = false;
+        for (const o of observations) {
             const entity = graph.entities.find(e => e.name === o.entityName);
             if (!entity) {
                 throw new EntityNotFoundError(o.entityName);
             }
             const newObservations = o.contents.filter(content => !entity.observations.includes(content));
-            entity.observations.push(...newObservations);
-            // Update lastModified if observations were added
             if (newObservations.length > 0) {
+                // Add new observations directly to the entity
+                entity.observations.push(...newObservations);
                 entity.lastModified = timestamp;
+                hasChanges = true;
             }
-            return {
-                entityName: o.entityName,
-                addedObservations: newObservations,
-            };
-        });
-        await this.storage.saveGraph(graph);
+            results.push({ entityName: o.entityName, addedObservations: newObservations });
+        }
+        // Save all changes in a single atomic operation
+        if (hasChanges) {
+            await this.storage.saveGraph(graph);
+        }
         return results;
     }
     /**
-     * Delete specific observations from multiple entities in a single batch operation.
+     * Delete observations from multiple entities in a single batch operation.
      *
      * This method performs the following operations:
-     * - Removes specified observations from each entity
+     * - Removes specified observations from entities
+     * - Updates lastModified timestamp only if observations were deleted
      * - Silently ignores entities that don't exist (no error thrown)
-     * - Silently ignores observations that don't exist in the entity
-     * - Automatically updates lastModified timestamp for modified entities
+     * - ATOMIC: All deletions are saved in a single operation
      *
-     * @param deletions - Array of objects, each containing entityName and array of observations to delete
+     * @param deletions - Array of entity names and observations to delete
      * @returns Promise that resolves when deletion is complete
      *
      * @example
      * ```typescript
      * const manager = new ObservationManager(storage);
      *
-     * // Delete specific observations from single entity
+     * // Delete observations from multiple entities
      * await manager.deleteObservations([
-     *   {
-     *     entityName: 'Alice',
-     *     observations: ['Works on frontend', 'Expertise in React']
-     *   }
+     *   { entityName: 'Alice', observations: ['Old observation 1', 'Old observation 2'] },
+     *   { entityName: 'Bob', observations: ['Outdated info'] }
      * ]);
      *
-     * // Delete observations from multiple entities at once
+     * // Safe to delete from non-existent entities (no error)
      * await manager.deleteObservations([
-     *   { entityName: 'Bob', observations: ['Team lead'] },
-     *   { entityName: 'Charlie', observations: ['New hire', 'Learning the codebase'] }
-     * ]);
-     *
-     * // Safe to delete non-existent observations or from non-existent entities
-     * await manager.deleteObservations([
-     *   { entityName: 'NonExistent', observations: ['Some observation'] } // No error
-     * ]);
+     *   { entityName: 'NonExistent', observations: ['Some text'] }
+     * ]); // No error thrown
      * ```
      */
     async deleteObservations(deletions) {
-        const graph = await this.storage.loadGraph();
+        // Get mutable graph for atomic update
+        const graph = await this.storage.getGraphForMutation();
         const timestamp = new Date().toISOString();
+        let hasChanges = false;
         deletions.forEach(d => {
             const entity = graph.entities.find(e => e.name === d.entityName);
             if (entity) {
                 const originalLength = entity.observations.length;
                 entity.observations = entity.observations.filter(o => !d.observations.includes(o));
-                // Update lastModified if observations were deleted
+                // Update lastModified timestamp if observations were deleted
                 if (entity.observations.length < originalLength) {
                     entity.lastModified = timestamp;
+                    hasChanges = true;
                 }
             }
         });
-        await this.storage.saveGraph(graph);
+        // Save all changes in a single atomic operation
+        if (hasChanges) {
+            await this.storage.saveGraph(graph);
+        }
     }
 }

package/dist/core/RelationManager.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Relation Manager
+ *
+ * Handles CRUD operations for relations in the knowledge graph.
+ *
+ * @module core/RelationManager
+ */
+import type { Relation } from '../types/index.js';
+import type { GraphStorage } from './GraphStorage.js';
+/**
+ * Manages relation operations with automatic timestamp handling.
+ */
+export declare class RelationManager {
+    private storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Create multiple relations in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Validates that all referenced entities exist (prevents dangling relations)
+     * - Filters out duplicate relations (same from, to, and relationType)
+     * - Automatically adds createdAt and lastModified timestamps
+     *
+     * A relation is considered duplicate if another relation exists with the same:
+     * - from entity name
+     * - to entity name
+     * - relationType
+     *
+     * @param relations - Array of relations to create
+     * @returns Promise resolving to array of newly created relations (excludes duplicates)
+     * @throws {ValidationError} If any relation references non-existent entities
+     *
+     * @example
+     * ```typescript
+     * const manager = new RelationManager(storage);
+     *
+     * // Create single relation
+     * const results = await manager.createRelations([{
+     *   from: 'Alice',
+     *   to: 'Bob',
+     *   relationType: 'works_with'
+     * }]);
+     *
+     * // Create multiple relations at once
+     * await manager.createRelations([
+     *   { from: 'Alice', to: 'Project_X', relationType: 'contributes_to' },
+     *   { from: 'Bob', to: 'Project_X', relationType: 'leads' },
+     *   { from: 'Charlie', to: 'Alice', relationType: 'reports_to' }
+     * ]);
+     *
+     * // Duplicate relations are filtered out
+     * await manager.createRelations([
+     *   { from: 'Alice', to: 'Bob', relationType: 'works_with' } // Already exists, won't be added
+     * ]);
+     * ```
+     */
+    createRelations(relations: Relation[]): Promise<Relation[]>;
+    /**
+     * Delete multiple relations in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Removes all specified relations from the graph
+     * - Automatically updates lastModified timestamp for all affected entities
+     * - Silently ignores relations that don't exist (no error thrown)
+     *
+     * An entity is considered "affected" if it appears as either the source (from)
+     * or target (to) of any deleted relation.
+     *
+     * @param relations - Array of relations to delete. Each relation is matched by from, to, and relationType.
+     * @returns Promise that resolves when deletion is complete
+     *
+     * @example
+     * ```typescript
+     * const manager = new RelationManager(storage);
+     *
+     * // Delete single relation
+     * await manager.deleteRelations([{
+     *   from: 'Alice',
+     *   to: 'Bob',
+     *   relationType: 'works_with'
+     * }]);
+     *
+     * // Delete multiple relations at once
+     * await manager.deleteRelations([
+     *   { from: 'Alice', to: 'Project_X', relationType: 'contributes_to' },
+     *   { from: 'Bob', to: 'Project_X', relationType: 'leads' }
+     * ]);
+     * // Note: Alice, Bob, and Project_X will all have their lastModified timestamp updated
+     *
+     * // Safe to delete non-existent relations
+     * await manager.deleteRelations([
+     *   { from: 'NonExistent', to: 'AlsoNonExistent', relationType: 'fake' } // No error
+     * ]);
+     * ```
+     */
+    deleteRelations(relations: Relation[]): Promise<void>;
+    /**
+     * Retrieve all relations involving a specific entity.
+     *
+     * This is a read-only operation that returns all relations where the specified
+     * entity appears as either the source (from) or target (to) of the relation.
+     * Entity names are case-sensitive.
+     *
+     * @param entityName - The unique name of the entity to find relations for
+     * @returns Promise resolving to array of Relation objects (empty array if no relations found)
+     *
+     * @example
+     * ```typescript
+     * const manager = new RelationManager(storage);
+     *
+     * // Get all relations for an entity
+     * const aliceRelations = await manager.getRelations('Alice');
+     * // Returns: [
+     * //   { from: 'Alice', to: 'Bob', relationType: 'works_with' },
+     * //   { from: 'Alice', to: 'Project_X', relationType: 'contributes_to' },
+     * //   { from: 'Charlie', to: 'Alice', relationType: 'reports_to' }
+     * // ]
+     *
+     * // Process relations by type
+     * const relations = await manager.getRelations('Alice');
+     * const outgoing = relations.filter(r => r.from === 'Alice');
+     * const incoming = relations.filter(r => r.to === 'Alice');
+     *
+     * // Handle entity with no relations
+     * const noRelations = await manager.getRelations('IsolatedEntity');
+     * console.log(noRelations); // []
+     * ```
+     */
+    getRelations(entityName: string): Promise<Relation[]>;
+}
+//# sourceMappingURL=RelationManager.d.ts.map

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

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