@danielsimonjr/memory-mcp 0.7.2 → 0.41.0

package/dist/core/RelationManager.js

@@ -0,0 +1,186 @@
+/**
+ * Relation Manager
+ *
+ * Handles CRUD operations for relations in the knowledge graph.
+ *
+ * @module core/RelationManager
+ */
+import { ValidationError } from '../utils/errors.js';
+import { BatchCreateRelationsSchema, DeleteRelationsSchema } from '../utils/index.js';
+import { GRAPH_LIMITS } from '../utils/constants.js';
+/**
+ * Manages relation operations with automatic timestamp handling.
+ */
+export class RelationManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Create multiple relations in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Filters out duplicate relations (same from, to, and relationType)
+     * - Automatically adds createdAt and lastModified timestamps
+     * - Validates that entities referenced in relations exist (should be done by caller)
+     *
+     * 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)
+     *
+     * @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
+     * ]);
+     * ```
+     */
+    async createRelations(relations) {
+        // Validate input
+        const validation = BatchCreateRelationsSchema.safeParse(relations);
+        if (!validation.success) {
+            const errors = validation.error.issues.map((e) => `${e.path.join('.')}: ${e.message}`);
+            throw new ValidationError('Invalid relation data', errors);
+        }
+        const graph = await this.storage.loadGraph();
+        const timestamp = new Date().toISOString();
+        // Check graph size limits
+        const relationsToAdd = relations.filter(r => !graph.relations.some(existing => existing.from === r.from &&
+            existing.to === r.to &&
+            existing.relationType === r.relationType));
+        if (graph.relations.length + relationsToAdd.length > GRAPH_LIMITS.MAX_RELATIONS) {
+            throw new ValidationError('Graph size limit exceeded', [`Adding ${relationsToAdd.length} relations would exceed maximum of ${GRAPH_LIMITS.MAX_RELATIONS} relations`]);
+        }
+        const newRelations = relationsToAdd
+            .map(r => ({
+            ...r,
+            createdAt: r.createdAt || timestamp,
+            lastModified: r.lastModified || timestamp,
+        }));
+        graph.relations.push(...newRelations);
+        await this.storage.saveGraph(graph);
+        return newRelations;
+    }
+    /**
+     * 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
+     * ]);
+     * ```
+     */
+    async deleteRelations(relations) {
+        // Validate input
+        const validation = DeleteRelationsSchema.safeParse(relations);
+        if (!validation.success) {
+            const errors = validation.error.issues.map((e) => `${e.path.join('.')}: ${e.message}`);
+            throw new ValidationError('Invalid relation data', errors);
+        }
+        const graph = await this.storage.loadGraph();
+        const timestamp = new Date().toISOString();
+        // Track affected entities
+        const affectedEntityNames = new Set();
+        relations.forEach(rel => {
+            affectedEntityNames.add(rel.from);
+            affectedEntityNames.add(rel.to);
+        });
+        // Remove relations
+        graph.relations = graph.relations.filter(r => !relations.some(delRelation => r.from === delRelation.from &&
+            r.to === delRelation.to &&
+            r.relationType === delRelation.relationType));
+        // Update lastModified for affected entities
+        graph.entities.forEach(entity => {
+            if (affectedEntityNames.has(entity.name)) {
+                entity.lastModified = timestamp;
+            }
+        });
+        await this.storage.saveGraph(graph);
+    }
+    /**
+     * 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); // []
+     * ```
+     */
+    async getRelations(entityName) {
+        const graph = await this.storage.loadGraph();
+        return graph.relations.filter(r => r.from === entityName || r.to === entityName);
+    }
+}

package/dist/core/TransactionManager.js

@@ -0,0 +1,389 @@
+/**
+ * Transaction Manager
+ *
+ * Provides atomic transaction support for knowledge graph operations.
+ * Ensures data consistency by allowing multiple operations to be
+ * grouped together and committed atomically, with automatic rollback on failure.
+ *
+ * @module core/TransactionManager
+ */
+import { BackupManager } from '../features/BackupManager.js';
+import { KnowledgeGraphError } from '../utils/errors.js';
+/**
+ * Types of operations that can be performed in a transaction.
+ */
+export var OperationType;
+(function (OperationType) {
+    OperationType["CREATE_ENTITY"] = "CREATE_ENTITY";
+    OperationType["UPDATE_ENTITY"] = "UPDATE_ENTITY";
+    OperationType["DELETE_ENTITY"] = "DELETE_ENTITY";
+    OperationType["CREATE_RELATION"] = "CREATE_RELATION";
+    OperationType["DELETE_RELATION"] = "DELETE_RELATION";
+})(OperationType || (OperationType = {}));
+/**
+ * Manages atomic transactions for knowledge graph operations.
+ *
+ * Provides ACID-like guarantees:
+ * - Atomicity: All operations succeed or all fail
+ * - Consistency: Graph is always in a valid state
+ * - Isolation: Each transaction operates on a snapshot
+ * - Durability: Changes are persisted to disk
+ *
+ * @example
+ * ```typescript
+ * const storage = new GraphStorage('/data/memory.jsonl');
+ * const txManager = new TransactionManager(storage);
+ *
+ * // Begin transaction
+ * txManager.begin();
+ *
+ * // Stage operations
+ * txManager.createEntity({ name: 'Alice', entityType: 'person', observations: [] });
+ * txManager.createRelation({ from: 'Alice', to: 'Bob', relationType: 'knows' });
+ *
+ * // Commit atomically (or rollback on error)
+ * const result = await txManager.commit();
+ * if (result.success) {
+ *   console.log(`Transaction completed: ${result.operationsExecuted} operations`);
+ * }
+ * ```
+ */
+export class TransactionManager {
+    storage;
+    operations = [];
+    inTransaction = false;
+    backupManager;
+    transactionBackup;
+    constructor(storage) {
+        this.storage = storage;
+        this.backupManager = new BackupManager(storage);
+    }
+    /**
+     * Begin a new transaction.
+     *
+     * Creates a backup of the current state for rollback purposes.
+     * Only one transaction can be active at a time.
+     *
+     * @throws {KnowledgeGraphError} If a transaction is already in progress
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * // ... stage operations ...
+     * await txManager.commit();
+     * ```
+     */
+    begin() {
+        if (this.inTransaction) {
+            throw new KnowledgeGraphError('Transaction already in progress', 'TRANSACTION_ACTIVE');
+        }
+        this.operations = [];
+        this.inTransaction = true;
+    }
+    /**
+     * Stage a create entity operation.
+     *
+     * @param entity - Entity to create (without timestamps)
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * txManager.createEntity({
+     *   name: 'Alice',
+     *   entityType: 'person',
+     *   observations: ['Software engineer'],
+     *   importance: 8
+     * });
+     * ```
+     */
+    createEntity(entity) {
+        this.ensureInTransaction();
+        this.operations.push({
+            type: OperationType.CREATE_ENTITY,
+            data: entity,
+        });
+    }
+    /**
+     * Stage an update entity operation.
+     *
+     * @param name - Name of entity to update
+     * @param updates - Partial entity updates
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * txManager.updateEntity('Alice', {
+     *   importance: 9,
+     *   observations: ['Lead software engineer']
+     * });
+     * ```
+     */
+    updateEntity(name, updates) {
+        this.ensureInTransaction();
+        this.operations.push({
+            type: OperationType.UPDATE_ENTITY,
+            data: { name, updates },
+        });
+    }
+    /**
+     * Stage a delete entity operation.
+     *
+     * @param name - Name of entity to delete
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * txManager.deleteEntity('OldEntity');
+     * ```
+     */
+    deleteEntity(name) {
+        this.ensureInTransaction();
+        this.operations.push({
+            type: OperationType.DELETE_ENTITY,
+            data: { name },
+        });
+    }
+    /**
+     * Stage a create relation operation.
+     *
+     * @param relation - Relation to create (without timestamps)
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * txManager.createRelation({
+     *   from: 'Alice',
+     *   to: 'Bob',
+     *   relationType: 'mentors'
+     * });
+     * ```
+     */
+    createRelation(relation) {
+        this.ensureInTransaction();
+        this.operations.push({
+            type: OperationType.CREATE_RELATION,
+            data: relation,
+        });
+    }
+    /**
+     * Stage a delete relation operation.
+     *
+     * @param from - Source entity name
+     * @param to - Target entity name
+     * @param relationType - Type of relation
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * txManager.deleteRelation('Alice', 'Bob', 'mentors');
+     * ```
+     */
+    deleteRelation(from, to, relationType) {
+        this.ensureInTransaction();
+        this.operations.push({
+            type: OperationType.DELETE_RELATION,
+            data: { from, to, relationType },
+        });
+    }
+    /**
+     * Commit the transaction, applying all staged operations atomically.
+     *
+     * Creates a backup before applying changes. If any operation fails,
+     * automatically rolls back to the pre-transaction state.
+     *
+     * @returns Promise resolving to transaction result
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * txManager.createEntity({ name: 'Alice', entityType: 'person', observations: [] });
+     * txManager.createRelation({ from: 'Alice', to: 'Bob', relationType: 'knows' });
+     *
+     * const result = await txManager.commit();
+     * if (result.success) {
+     *   console.log(`Committed ${result.operationsExecuted} operations`);
+     * } else {
+     *   console.error(`Transaction failed: ${result.error}`);
+     * }
+     * ```
+     */
+    async commit() {
+        this.ensureInTransaction();
+        try {
+            // Create backup for rollback
+            this.transactionBackup = await this.backupManager.createBackup('Transaction backup (auto-created)');
+            // Load current graph
+            const graph = await this.storage.loadGraph();
+            const timestamp = new Date().toISOString();
+            // Apply all operations
+            let operationsExecuted = 0;
+            for (const operation of this.operations) {
+                this.applyOperation(graph, operation, timestamp);
+                operationsExecuted++;
+            }
+            // Save the modified graph
+            await this.storage.saveGraph(graph);
+            // Clean up transaction state
+            this.inTransaction = false;
+            this.operations = [];
+            // Delete the transaction backup (no longer needed)
+            if (this.transactionBackup) {
+                await this.backupManager.deleteBackup(this.transactionBackup);
+                this.transactionBackup = undefined;
+            }
+            return {
+                success: true,
+                operationsExecuted,
+            };
+        }
+        catch (error) {
+            // Rollback on error
+            const rollbackResult = await this.rollback();
+            return {
+                success: false,
+                operationsExecuted: 0,
+                error: error instanceof Error ? error.message : String(error),
+                rollbackBackup: rollbackResult.backupUsed,
+            };
+        }
+    }
+    /**
+     * Rollback the current transaction.
+     *
+     * Restores the graph to the pre-transaction state using the backup.
+     * Automatically called by commit() on failure.
+     *
+     * @returns Promise resolving to rollback result
+     *
+     * @example
+     * ```typescript
+     * txManager.begin();
+     * txManager.createEntity({ name: 'Test', entityType: 'temp', observations: [] });
+     *
+     * // Explicit rollback (e.g., user cancellation)
+     * const result = await txManager.rollback();
+     * console.log(`Rolled back, restored from: ${result.backupUsed}`);
+     * ```
+     */
+    async rollback() {
+        if (!this.transactionBackup) {
+            this.inTransaction = false;
+            this.operations = [];
+            return { success: false };
+        }
+        try {
+            // Restore from backup
+            await this.backupManager.restoreFromBackup(this.transactionBackup);
+            // Clean up
+            const backupUsed = this.transactionBackup;
+            await this.backupManager.deleteBackup(this.transactionBackup);
+            this.inTransaction = false;
+            this.operations = [];
+            this.transactionBackup = undefined;
+            return { success: true, backupUsed };
+        }
+        catch (error) {
+            // Rollback failed - keep backup for manual recovery
+            this.inTransaction = false;
+            this.operations = [];
+            return { success: false, backupUsed: this.transactionBackup };
+        }
+    }
+    /**
+     * Check if a transaction is currently in progress.
+     *
+     * @returns True if transaction is active
+     */
+    isInTransaction() {
+        return this.inTransaction;
+    }
+    /**
+     * Get the number of staged operations in the current transaction.
+     *
+     * @returns Number of operations staged
+     */
+    getOperationCount() {
+        return this.operations.length;
+    }
+    /**
+     * Ensure a transaction is in progress, or throw an error.
+     *
+     * @private
+     */
+    ensureInTransaction() {
+        if (!this.inTransaction) {
+            throw new KnowledgeGraphError('No transaction in progress. Call begin() first.', 'NO_TRANSACTION');
+        }
+    }
+    /**
+     * Apply a single operation to the graph.
+     *
+     * @private
+     */
+    applyOperation(graph, operation, timestamp) {
+        switch (operation.type) {
+            case OperationType.CREATE_ENTITY: {
+                const entity = {
+                    ...operation.data,
+                    createdAt: timestamp,
+                    lastModified: timestamp,
+                };
+                // Check for duplicates
+                if (graph.entities.some(e => e.name === entity.name)) {
+                    throw new KnowledgeGraphError(`Entity "${entity.name}" already exists`, 'DUPLICATE_ENTITY');
+                }
+                graph.entities.push(entity);
+                break;
+            }
+            case OperationType.UPDATE_ENTITY: {
+                const { name, updates } = operation.data;
+                const entity = graph.entities.find(e => e.name === name);
+                if (!entity) {
+                    throw new KnowledgeGraphError(`Entity "${name}" not found`, 'ENTITY_NOT_FOUND');
+                }
+                Object.assign(entity, updates);
+                entity.lastModified = timestamp;
+                break;
+            }
+            case OperationType.DELETE_ENTITY: {
+                const { name } = operation.data;
+                const index = graph.entities.findIndex(e => e.name === name);
+                if (index === -1) {
+                    throw new KnowledgeGraphError(`Entity "${name}" not found`, 'ENTITY_NOT_FOUND');
+                }
+                graph.entities.splice(index, 1);
+                // Delete related relations
+                graph.relations = graph.relations.filter(r => r.from !== name && r.to !== name);
+                break;
+            }
+            case OperationType.CREATE_RELATION: {
+                const relation = {
+                    ...operation.data,
+                    createdAt: timestamp,
+                    lastModified: timestamp,
+                };
+                // Check for duplicates
+                const exists = graph.relations.some(r => r.from === relation.from && r.to === relation.to && r.relationType === relation.relationType);
+                if (exists) {
+                    throw new KnowledgeGraphError(`Relation "${relation.from}" -> "${relation.to}" (${relation.relationType}) already exists`, 'DUPLICATE_RELATION');
+                }
+                graph.relations.push(relation);
+                break;
+            }
+            case OperationType.DELETE_RELATION: {
+                const { from, to, relationType } = operation.data;
+                const index = graph.relations.findIndex(r => r.from === from && r.to === to && r.relationType === relationType);
+                if (index === -1) {
+                    throw new KnowledgeGraphError(`Relation "${from}" -> "${to}" (${relationType}) not found`, 'RELATION_NOT_FOUND');
+                }
+                graph.relations.splice(index, 1);
+                break;
+            }
+            default: {
+                // Exhaustiveness check - TypeScript will error if we miss a case
+                const _exhaustiveCheck = operation;
+                throw new KnowledgeGraphError(`Unknown operation type: ${_exhaustiveCheck.type}`, 'UNKNOWN_OPERATION');
+            }
+        }
+    }
+}

package/dist/core/index.js

@@ -0,0 +1,9 @@
+/**
+ * Core Module Barrel Export
+ */
+export { GraphStorage } from './GraphStorage.js';
+export { EntityManager } from './EntityManager.js';
+export { RelationManager } from './RelationManager.js';
+export { ObservationManager } from './ObservationManager.js';
+export { KnowledgeGraphManager } from './KnowledgeGraphManager.js';
+export { TransactionManager, OperationType, } from './TransactionManager.js';