@danielsimonjr/memory-mcp 0.7.2 → 0.41.0

package/dist/features/AnalyticsManager.js

@@ -0,0 +1,222 @@
+/**
+ * Analytics Manager
+ *
+ * Provides graph validation and analytics capabilities.
+ *
+ * @module features/AnalyticsManager
+ */
+/**
+ * Performs validation and analytics on the knowledge graph.
+ */
+export class AnalyticsManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Validate the knowledge graph structure and data integrity.
+     *
+     * Checks for:
+     * - Orphaned relations (pointing to non-existent entities)
+     * - Duplicate entity names
+     * - Invalid entity data (missing name/type, invalid observations)
+     * - Isolated entities (no relations)
+     * - Empty observations
+     * - Missing metadata (createdAt, lastModified)
+     *
+     * @returns Validation report with errors, warnings, and summary
+     */
+    async validateGraph() {
+        const graph = await this.storage.loadGraph();
+        const errors = [];
+        const warnings = [];
+        // Create a set of all entity names for fast lookup
+        const entityNames = new Set(graph.entities.map(e => e.name));
+        // Check for orphaned relations (relations pointing to non-existent entities)
+        for (const relation of graph.relations) {
+            if (!entityNames.has(relation.from)) {
+                errors.push({
+                    type: 'orphaned_relation',
+                    message: `Relation has non-existent source entity: "${relation.from}"`,
+                    details: { relation, missingEntity: relation.from },
+                });
+            }
+            if (!entityNames.has(relation.to)) {
+                errors.push({
+                    type: 'orphaned_relation',
+                    message: `Relation has non-existent target entity: "${relation.to}"`,
+                    details: { relation, missingEntity: relation.to },
+                });
+            }
+        }
+        // Check for duplicate entity names
+        const entityNameCounts = new Map();
+        for (const entity of graph.entities) {
+            const count = entityNameCounts.get(entity.name) || 0;
+            entityNameCounts.set(entity.name, count + 1);
+        }
+        for (const [name, count] of entityNameCounts.entries()) {
+            if (count > 1) {
+                errors.push({
+                    type: 'duplicate_entity',
+                    message: `Duplicate entity name found: "${name}" (${count} instances)`,
+                    details: { entityName: name, count },
+                });
+            }
+        }
+        // Check for entities with invalid data
+        for (const entity of graph.entities) {
+            if (!entity.name || entity.name.trim() === '') {
+                errors.push({
+                    type: 'invalid_data',
+                    message: 'Entity has empty or missing name',
+                    details: { entity },
+                });
+            }
+            if (!entity.entityType || entity.entityType.trim() === '') {
+                errors.push({
+                    type: 'invalid_data',
+                    message: `Entity "${entity.name}" has empty or missing entityType`,
+                    details: { entity },
+                });
+            }
+            if (!Array.isArray(entity.observations)) {
+                errors.push({
+                    type: 'invalid_data',
+                    message: `Entity "${entity.name}" has invalid observations (not an array)`,
+                    details: { entity },
+                });
+            }
+        }
+        // Warnings: Check for isolated entities (no relations)
+        const entitiesInRelations = new Set();
+        for (const relation of graph.relations) {
+            entitiesInRelations.add(relation.from);
+            entitiesInRelations.add(relation.to);
+        }
+        for (const entity of graph.entities) {
+            if (!entitiesInRelations.has(entity.name) && graph.relations.length > 0) {
+                warnings.push({
+                    type: 'isolated_entity',
+                    message: `Entity "${entity.name}" has no relations to other entities`,
+                    details: { entityName: entity.name },
+                });
+            }
+        }
+        // Warnings: Check for entities with empty observations
+        for (const entity of graph.entities) {
+            if (entity.observations.length === 0) {
+                warnings.push({
+                    type: 'empty_observations',
+                    message: `Entity "${entity.name}" has no observations`,
+                    details: { entityName: entity.name },
+                });
+            }
+        }
+        // Warnings: Check for missing metadata (createdAt, lastModified)
+        for (const entity of graph.entities) {
+            if (!entity.createdAt) {
+                warnings.push({
+                    type: 'missing_metadata',
+                    message: `Entity "${entity.name}" is missing createdAt timestamp`,
+                    details: { entityName: entity.name, field: 'createdAt' },
+                });
+            }
+            if (!entity.lastModified) {
+                warnings.push({
+                    type: 'missing_metadata',
+                    message: `Entity "${entity.name}" is missing lastModified timestamp`,
+                    details: { entityName: entity.name, field: 'lastModified' },
+                });
+            }
+        }
+        // Count specific issues
+        const orphanedRelationsCount = errors.filter(e => e.type === 'orphaned_relation').length;
+        const entitiesWithoutRelationsCount = warnings.filter(w => w.type === 'isolated_entity').length;
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings,
+            summary: {
+                totalErrors: errors.length,
+                totalWarnings: warnings.length,
+                orphanedRelationsCount,
+                entitiesWithoutRelationsCount,
+            },
+        };
+    }
+    /**
+     * Get comprehensive statistics about the knowledge graph.
+     *
+     * Provides metrics including:
+     * - Total counts of entities and relations
+     * - Entity and relation type distributions
+     * - Oldest and newest entities/relations
+     * - Date ranges for entities and relations
+     *
+     * @returns Graph statistics object
+     */
+    async getGraphStats() {
+        const graph = await this.storage.loadGraph();
+        // Calculate entity type counts
+        const entityTypesCounts = {};
+        graph.entities.forEach(e => {
+            entityTypesCounts[e.entityType] = (entityTypesCounts[e.entityType] || 0) + 1;
+        });
+        // Calculate relation type counts
+        const relationTypesCounts = {};
+        graph.relations.forEach(r => {
+            relationTypesCounts[r.relationType] = (relationTypesCounts[r.relationType] || 0) + 1;
+        });
+        // Find oldest and newest entities
+        let oldestEntity;
+        let newestEntity;
+        let earliestEntityDate = null;
+        let latestEntityDate = null;
+        graph.entities.forEach(e => {
+            const date = new Date(e.createdAt || '');
+            if (!earliestEntityDate || date < earliestEntityDate) {
+                earliestEntityDate = date;
+                oldestEntity = { name: e.name, date: e.createdAt || '' };
+            }
+            if (!latestEntityDate || date > latestEntityDate) {
+                latestEntityDate = date;
+                newestEntity = { name: e.name, date: e.createdAt || '' };
+            }
+        });
+        // Find oldest and newest relations
+        let oldestRelation;
+        let newestRelation;
+        let earliestRelationDate = null;
+        let latestRelationDate = null;
+        graph.relations.forEach(r => {
+            const date = new Date(r.createdAt || '');
+            if (!earliestRelationDate || date < earliestRelationDate) {
+                earliestRelationDate = date;
+                oldestRelation = { from: r.from, to: r.to, relationType: r.relationType, date: r.createdAt || '' };
+            }
+            if (!latestRelationDate || date > latestRelationDate) {
+                latestRelationDate = date;
+                newestRelation = { from: r.from, to: r.to, relationType: r.relationType, date: r.createdAt || '' };
+            }
+        });
+        return {
+            totalEntities: graph.entities.length,
+            totalRelations: graph.relations.length,
+            entityTypesCounts,
+            relationTypesCounts,
+            oldestEntity,
+            newestEntity,
+            oldestRelation,
+            newestRelation,
+            entityDateRange: earliestEntityDate && latestEntityDate ? {
+                earliest: earliestEntityDate.toISOString(),
+                latest: latestEntityDate.toISOString()
+            } : undefined,
+            relationDateRange: earliestRelationDate && latestRelationDate ? {
+                earliest: earliestRelationDate.toISOString(),
+                latest: latestRelationDate.toISOString()
+            } : undefined,
+        };
+    }
+}

package/dist/features/ArchiveManager.js

@@ -0,0 +1,74 @@
+/**
+ * Archive Manager
+ *
+ * Archives old or low-importance entities to reduce active graph size.
+ *
+ * @module features/ArchiveManager
+ */
+/**
+ * Manages entity archival based on age, importance, and tags.
+ */
+export class ArchiveManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Archive old or low-importance entities.
+     *
+     * Entities matching ANY of the criteria are archived:
+     * - lastModified older than olderThan date
+     * - importance less than importanceLessThan
+     * - has at least one tag from tags array
+     *
+     * Archived entities and their relations are removed from the graph.
+     *
+     * @param criteria - Archiving criteria
+     * @param dryRun - If true, preview what would be archived without making changes
+     * @returns Archive result with count and entity names
+     */
+    async archiveEntities(criteria, dryRun = false) {
+        const graph = await this.storage.loadGraph();
+        const toArchive = [];
+        for (const entity of graph.entities) {
+            let shouldArchive = false;
+            // Check age criteria
+            if (criteria.olderThan && entity.lastModified) {
+                const entityDate = new Date(entity.lastModified);
+                const cutoffDate = new Date(criteria.olderThan);
+                if (entityDate < cutoffDate) {
+                    shouldArchive = true;
+                }
+            }
+            // Check importance criteria
+            if (criteria.importanceLessThan !== undefined) {
+                if (entity.importance === undefined || entity.importance < criteria.importanceLessThan) {
+                    shouldArchive = true;
+                }
+            }
+            // Check tag criteria (must have at least one matching tag)
+            if (criteria.tags && criteria.tags.length > 0) {
+                const normalizedCriteriaTags = criteria.tags.map(t => t.toLowerCase());
+                const entityTags = (entity.tags || []).map(t => t.toLowerCase());
+                const hasMatchingTag = normalizedCriteriaTags.some(tag => entityTags.includes(tag));
+                if (hasMatchingTag) {
+                    shouldArchive = true;
+                }
+            }
+            if (shouldArchive) {
+                toArchive.push(entity);
+            }
+        }
+        if (!dryRun && toArchive.length > 0) {
+            // Remove archived entities from main graph
+            const archiveNames = new Set(toArchive.map(e => e.name));
+            graph.entities = graph.entities.filter(e => !archiveNames.has(e.name));
+            graph.relations = graph.relations.filter(r => !archiveNames.has(r.from) && !archiveNames.has(r.to));
+            await this.storage.saveGraph(graph);
+        }
+        return {
+            archived: toArchive.length,
+            entityNames: toArchive.map(e => e.name),
+        };
+    }
+}

package/dist/features/BackupManager.js

@@ -0,0 +1,311 @@
+/**
+ * Backup Manager
+ *
+ * Manages backup and restore operations for the knowledge graph.
+ * Provides point-in-time recovery and data protection.
+ *
+ * @module features/BackupManager
+ */
+import { promises as fs } from 'fs';
+import { dirname, join } from 'path';
+import { FileOperationError } from '../utils/errors.js';
+/**
+ * Manages backup and restore operations for the knowledge graph.
+ *
+ * Backup files are stored in a `.backups` directory next to the main graph file.
+ * Each backup includes the graph data and metadata about the backup.
+ *
+ * @example
+ * ```typescript
+ * const storage = new GraphStorage('/data/memory.jsonl');
+ * const backup = new BackupManager(storage);
+ *
+ * // Create a backup
+ * const backupPath = await backup.createBackup('Before compression');
+ *
+ * // List available backups
+ * const backups = await backup.listBackups();
+ *
+ * // Restore from backup
+ * await backup.restoreFromBackup(backupPath);
+ *
+ * // Clean old backups (keep last 10)
+ * await backup.cleanOldBackups(10);
+ * ```
+ */
+export class BackupManager {
+    storage;
+    backupDir;
+    constructor(storage) {
+        this.storage = storage;
+        const filePath = this.storage.getFilePath();
+        const dir = dirname(filePath);
+        this.backupDir = join(dir, '.backups');
+    }
+    /**
+     * Ensure backup directory exists.
+     *
+     * @private
+     */
+    async ensureBackupDir() {
+        try {
+            await fs.mkdir(this.backupDir, { recursive: true });
+        }
+        catch (error) {
+            throw new FileOperationError('create backup directory', this.backupDir, error);
+        }
+    }
+    /**
+     * Generate backup file name with timestamp.
+     *
+     * Format: backup_YYYY-MM-DD_HH-MM-SS-mmm.jsonl
+     *
+     * @private
+     */
+    generateBackupFileName() {
+        const now = new Date();
+        const timestamp = now.toISOString()
+            .replace(/:/g, '-')
+            .replace(/\./g, '-')
+            .replace('T', '_')
+            .replace('Z', '');
+        return `backup_${timestamp}.jsonl`;
+    }
+    /**
+     * Create a backup of the current knowledge graph.
+     *
+     * Backup includes:
+     * - Complete graph data (entities and relations)
+     * - Metadata (timestamp, counts, file size, description)
+     *
+     * @param description - Optional description for this backup
+     * @returns Promise resolving to the backup file path
+     * @throws {FileOperationError} If backup creation fails
+     *
+     * @example
+     * ```typescript
+     * // Create backup with description
+     * const backupPath = await manager.createBackup('Before merging duplicates');
+     *
+     * // Create backup without description
+     * const backupPath = await manager.createBackup();
+     * ```
+     */
+    async createBackup(description) {
+        await this.ensureBackupDir();
+        // Load current graph
+        const graph = await this.storage.loadGraph();
+        const fileName = this.generateBackupFileName();
+        const backupPath = join(this.backupDir, fileName);
+        try {
+            // Read the current file content to preserve exact formatting
+            const originalPath = this.storage.getFilePath();
+            let fileContent;
+            try {
+                fileContent = await fs.readFile(originalPath, 'utf-8');
+            }
+            catch (error) {
+                // File doesn't exist yet - generate content from graph
+                const lines = [
+                    ...graph.entities.map(e => JSON.stringify({ type: 'entity', ...e })),
+                    ...graph.relations.map(r => JSON.stringify({ type: 'relation', ...r })),
+                ];
+                fileContent = lines.join('\n');
+            }
+            // Write backup file
+            await fs.writeFile(backupPath, fileContent);
+            // Get file stats
+            const stats = await fs.stat(backupPath);
+            // Create metadata
+            const metadata = {
+                timestamp: new Date().toISOString(),
+                entityCount: graph.entities.length,
+                relationCount: graph.relations.length,
+                fileSize: stats.size,
+                description,
+            };
+            // Write metadata file
+            const metadataPath = `${backupPath}.meta.json`;
+            await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+            return backupPath;
+        }
+        catch (error) {
+            throw new FileOperationError('create backup', backupPath, error);
+        }
+    }
+    /**
+     * List all available backups, sorted by timestamp (newest first).
+     *
+     * @returns Promise resolving to array of backup information
+     * @throws {FileOperationError} If listing fails
+     *
+     * @example
+     * ```typescript
+     * const backups = await manager.listBackups();
+     * console.log(`Found ${backups.length} backups`);
+     *
+     * for (const backup of backups) {
+     *   console.log(`${backup.fileName}: ${backup.metadata.entityCount} entities`);
+     * }
+     * ```
+     */
+    async listBackups() {
+        try {
+            // Check if backup directory exists
+            try {
+                await fs.access(this.backupDir);
+            }
+            catch {
+                // Directory doesn't exist - no backups
+                return [];
+            }
+            const files = await fs.readdir(this.backupDir);
+            const backupFiles = files.filter(f => f.startsWith('backup_') && f.endsWith('.jsonl'));
+            const backups = [];
+            for (const fileName of backupFiles) {
+                const filePath = join(this.backupDir, fileName);
+                const metadataPath = `${filePath}.meta.json`;
+                try {
+                    // Read metadata if it exists
+                    const metadataContent = await fs.readFile(metadataPath, 'utf-8');
+                    const metadata = JSON.parse(metadataContent);
+                    backups.push({
+                        fileName,
+                        filePath,
+                        metadata,
+                    });
+                }
+                catch {
+                    // Metadata file doesn't exist or is corrupt - skip this backup
+                    continue;
+                }
+            }
+            // Sort by timestamp (newest first)
+            backups.sort((a, b) => new Date(b.metadata.timestamp).getTime() - new Date(a.metadata.timestamp).getTime());
+            return backups;
+        }
+        catch (error) {
+            throw new FileOperationError('list backups', this.backupDir, error);
+        }
+    }
+    /**
+     * Restore the knowledge graph from a backup file.
+     *
+     * CAUTION: This operation overwrites the current graph with backup data.
+     * Consider creating a backup before restoring.
+     *
+     * @param backupPath - Path to the backup file to restore from
+     * @returns Promise that resolves when restore is complete
+     * @throws {FileOperationError} If restore fails
+     *
+     * @example
+     * ```typescript
+     * // List backups and restore the most recent
+     * const backups = await manager.listBackups();
+     * if (backups.length > 0) {
+     *   await manager.restoreFromBackup(backups[0].filePath);
+     * }
+     *
+     * // Restore specific backup by path
+     * await manager.restoreFromBackup('/data/.backups/backup_2024-01-15_10-30-00.jsonl');
+     * ```
+     */
+    async restoreFromBackup(backupPath) {
+        try {
+            // Verify backup file exists
+            await fs.access(backupPath);
+            // Read backup content
+            const backupContent = await fs.readFile(backupPath, 'utf-8');
+            // Write to main graph file
+            const mainPath = this.storage.getFilePath();
+            await fs.writeFile(mainPath, backupContent);
+            // Clear storage cache to force reload
+            this.storage.clearCache();
+        }
+        catch (error) {
+            throw new FileOperationError('restore from backup', backupPath, error);
+        }
+    }
+    /**
+     * Delete a specific backup file.
+     *
+     * Also deletes the associated metadata file.
+     *
+     * @param backupPath - Path to the backup file to delete
+     * @returns Promise that resolves when deletion is complete
+     * @throws {FileOperationError} If deletion fails
+     *
+     * @example
+     * ```typescript
+     * const backups = await manager.listBackups();
+     * // Delete oldest backup
+     * if (backups.length > 0) {
+     *   await manager.deleteBackup(backups[backups.length - 1].filePath);
+     * }
+     * ```
+     */
+    async deleteBackup(backupPath) {
+        try {
+            // Delete backup file
+            await fs.unlink(backupPath);
+            // Delete metadata file (ignore errors if it doesn't exist)
+            try {
+                await fs.unlink(`${backupPath}.meta.json`);
+            }
+            catch {
+                // Metadata file doesn't exist - that's ok
+            }
+        }
+        catch (error) {
+            throw new FileOperationError('delete backup', backupPath, error);
+        }
+    }
+    /**
+     * Clean old backups, keeping only the most recent N backups.
+     *
+     * Backups are sorted by timestamp, and older backups are deleted.
+     *
+     * @param keepCount - Number of recent backups to keep (default: 10)
+     * @returns Promise resolving to number of backups deleted
+     * @throws {FileOperationError} If cleanup fails
+     *
+     * @example
+     * ```typescript
+     * // Keep only the 5 most recent backups
+     * const deleted = await manager.cleanOldBackups(5);
+     * console.log(`Deleted ${deleted} old backups`);
+     *
+     * // Keep default 10 most recent backups
+     * await manager.cleanOldBackups();
+     * ```
+     */
+    async cleanOldBackups(keepCount = 10) {
+        const backups = await this.listBackups();
+        // If we have fewer backups than keepCount, nothing to delete
+        if (backups.length <= keepCount) {
+            return 0;
+        }
+        // Delete backups beyond keepCount
+        const backupsToDelete = backups.slice(keepCount);
+        let deletedCount = 0;
+        for (const backup of backupsToDelete) {
+            try {
+                await this.deleteBackup(backup.filePath);
+                deletedCount++;
+            }
+            catch {
+                // Continue deleting other backups even if one fails
+                continue;
+            }
+        }
+        return deletedCount;
+    }
+    /**
+     * Get the path to the backup directory.
+     *
+     * @returns The backup directory path
+     */
+    getBackupDir() {
+        return this.backupDir;
+    }
+}