@danielsimonjr/memory-mcp 11.1.1 → 12.5.2

package/dist/features/AnalyticsManager.js

@@ -1,223 +0,0 @@
-/**
- * Analytics Manager
- *
- * Handles graph statistics and validation operations.
- * Extracted from SearchManager (Phase 4: Consolidate God Objects).
- *
- * @module features/AnalyticsManager
- */
-/**
- * Manages analytics operations for 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 issues = [];
-        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)) {
-                issues.push({
-                    type: 'orphaned_relation',
-                    message: `Relation has non-existent source entity: "${relation.from}"`,
-                    details: { relation, missingEntity: relation.from },
-                });
-            }
-            if (!entityNames.has(relation.to)) {
-                issues.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) {
-                issues.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() === '') {
-                issues.push({
-                    type: 'invalid_data',
-                    message: 'Entity has empty or missing name',
-                    details: { entity },
-                });
-            }
-            if (!entity.entityType || entity.entityType.trim() === '') {
-                issues.push({
-                    type: 'invalid_data',
-                    message: `Entity "${entity.name}" has empty or missing entityType`,
-                    details: { entity },
-                });
-            }
-            if (!Array.isArray(entity.observations)) {
-                issues.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 = issues.filter(e => e.type === 'orphaned_relation').length;
-        const entitiesWithoutRelationsCount = warnings.filter(w => w.type === 'isolated_entity').length;
-        return {
-            isValid: issues.length === 0,
-            issues,
-            warnings,
-            summary: {
-                totalErrors: issues.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.d.ts

@@ -1,121 +0,0 @@
-/**
- * Archive Manager
- *
- * Handles archiving (removal) of entities based on criteria.
- * Archives are stored as compressed files for space-efficient long-term storage.
- * Extracted from EntityManager (Phase 4: Consolidate God Objects).
- * Enhanced with brotli compression in Phase 3 Sprint 5.
- *
- * @module features/ArchiveManager
- */
-import type { GraphStorage } from '../core/GraphStorage.js';
-/**
- * Criteria for archiving entities.
- */
-export interface ArchiveCriteria {
-    /** Entities older than this date (ISO 8601) */
-    olderThan?: string;
-    /** Entities with importance less than this value */
-    importanceLessThan?: number;
-    /** Entities with any of these tags */
-    tags?: string[];
-}
-/**
- * Options for archive operations.
- */
-export interface ArchiveOptions {
-    /** Dry run mode - preview without making changes */
-    dryRun?: boolean;
-    /** Whether to save archived entities to a compressed file (default: true) */
-    saveToFile?: boolean;
-}
-/**
- * Result of archive operation.
- * Extends ArchiveResultExtended with compression statistics.
- */
-export interface ArchiveResult {
-    /** Number of entities archived */
-    archived: number;
-    /** Names of archived entities */
-    entityNames: string[];
-    /** Path to the archive file (if created) */
-    archivePath?: string;
-    /** Original size of archive data in bytes */
-    originalSize?: number;
-    /** Compressed size in bytes */
-    compressedSize?: number;
-    /** Compression ratio (compressedSize / originalSize). Lower is better. */
-    compressionRatio?: number;
-}
-/**
- * Manages archive operations for the knowledge graph.
- *
- * Archives are stored as brotli-compressed files in the `.archives` directory.
- * Maximum compression quality is used for optimal long-term storage.
- */
-export declare class ArchiveManager {
-    private storage;
-    private readonly archiveDir;
-    constructor(storage: GraphStorage);
-    /**
-     * 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
-     *
-     * By default, archived entities are saved to a compressed file before
-     * being removed from the active graph. Use `saveToFile: false` to
-     * skip creating the archive file.
-     *
-     * @param criteria - Archiving criteria
-     * @param options - Archive options (dryRun, saveToFile)
-     * @returns Archive result with count, entity names, and compression stats
-     *
-     * @example
-     * ```typescript
-     * // Archive old entities with compression
-     * const result = await manager.archiveEntities({
-     *   olderThan: '2023-01-01T00:00:00Z',
-     *   importanceLessThan: 3
-     * });
-     * console.log(`Archived ${result.archived} entities`);
-     * console.log(`Compressed from ${result.originalSize} to ${result.compressedSize} bytes`);
-     *
-     * // Preview without making changes
-     * const preview = await manager.archiveEntities(criteria, { dryRun: true });
-     * ```
-     */
-    archiveEntities(criteria: ArchiveCriteria, options?: ArchiveOptions | boolean): Promise<ArchiveResult>;
-    /**
-     * Save entities to a compressed archive file.
-     *
-     * Creates a brotli-compressed file in the `.archives` directory
-     * with maximum compression quality for space efficiency.
-     *
-     * @param entities - Entities to archive
-     * @returns Archive file path and compression statistics
-     */
-    private saveToArchive;
-    /**
-     * List all available archives.
-     *
-     * @returns Array of archive information with compression details
-     */
-    listArchives(): Promise<Array<{
-        fileName: string;
-        filePath: string;
-        timestamp: string;
-        entityCount: number;
-        compressed: boolean;
-        originalSize?: number;
-        compressedSize?: number;
-        compressionRatio?: number;
-    }>>;
-    /**
-     * Get the path to the archives directory.
-     */
-    getArchiveDir(): string;
-}
-//# sourceMappingURL=ArchiveManager.d.ts.map

package/dist/features/ArchiveManager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ArchiveManager.d.ts","sourceRoot":"","sources":["../../src/features/ArchiveManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IAGb,OAAO,CAAC,OAAO;IAF3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEhB,OAAO,EAAE,YAAY;IAMzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,eAAe,CACnB,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,cAAc,GAAG,OAAY,GACrC,OAAO,CAAC,aAAa,CAAC;IA+FzB;;;;;;;;OAQG;YACW,aAAa;IAmD3B;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC;QAClC,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC,CAAC;IA6DH;;OAEG;IACH,aAAa,IAAI,MAAM;CAGxB"}

package/dist/features/ArchiveManager.js

@@ -1,240 +0,0 @@
-/**
- * Archive Manager
- *
- * Handles archiving (removal) of entities based on criteria.
- * Archives are stored as compressed files for space-efficient long-term storage.
- * Extracted from EntityManager (Phase 4: Consolidate God Objects).
- * Enhanced with brotli compression in Phase 3 Sprint 5.
- *
- * @module features/ArchiveManager
- */
-import { promises as fs } from 'fs';
-import { dirname, join } from 'path';
-import { compress, COMPRESSION_CONFIG } from '../utils/index.js';
-/**
- * Manages archive operations for the knowledge graph.
- *
- * Archives are stored as brotli-compressed files in the `.archives` directory.
- * Maximum compression quality is used for optimal long-term storage.
- */
-export class ArchiveManager {
-    storage;
-    archiveDir;
-    constructor(storage) {
-        this.storage = storage;
-        const filePath = this.storage.getFilePath();
-        const dir = dirname(filePath);
-        this.archiveDir = join(dir, '.archives');
-    }
-    /**
-     * 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
-     *
-     * By default, archived entities are saved to a compressed file before
-     * being removed from the active graph. Use `saveToFile: false` to
-     * skip creating the archive file.
-     *
-     * @param criteria - Archiving criteria
-     * @param options - Archive options (dryRun, saveToFile)
-     * @returns Archive result with count, entity names, and compression stats
-     *
-     * @example
-     * ```typescript
-     * // Archive old entities with compression
-     * const result = await manager.archiveEntities({
-     *   olderThan: '2023-01-01T00:00:00Z',
-     *   importanceLessThan: 3
-     * });
-     * console.log(`Archived ${result.archived} entities`);
-     * console.log(`Compressed from ${result.originalSize} to ${result.compressedSize} bytes`);
-     *
-     * // Preview without making changes
-     * const preview = await manager.archiveEntities(criteria, { dryRun: true });
-     * ```
-     */
-    async archiveEntities(criteria, options = {}) {
-        // Handle legacy boolean argument (backward compatibility)
-        const opts = typeof options === 'boolean'
-            ? { dryRun: options, saveToFile: true }
-            : { saveToFile: true, ...options };
-        // Use read-only graph for analysis
-        const readGraph = await this.storage.loadGraph();
-        const toArchive = [];
-        for (const entity of readGraph.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);
-            }
-        }
-        // Dry run - return preview without changes
-        if (opts.dryRun) {
-            return {
-                archived: toArchive.length,
-                entityNames: toArchive.map(e => e.name),
-            };
-        }
-        // No entities to archive
-        if (toArchive.length === 0) {
-            return {
-                archived: 0,
-                entityNames: [],
-            };
-        }
-        // Save to compressed archive file
-        let archivePath;
-        let originalSize;
-        let compressedSize;
-        let compressionRatio;
-        if (opts.saveToFile) {
-            const archiveResult = await this.saveToArchive(toArchive);
-            archivePath = archiveResult.archivePath;
-            originalSize = archiveResult.originalSize;
-            compressedSize = archiveResult.compressedSize;
-            compressionRatio = archiveResult.compressionRatio;
-        }
-        // Get mutable copy for write operation
-        const graph = await this.storage.getGraphForMutation();
-        // 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),
-            archivePath,
-            originalSize,
-            compressedSize,
-            compressionRatio,
-        };
-    }
-    /**
-     * Save entities to a compressed archive file.
-     *
-     * Creates a brotli-compressed file in the `.archives` directory
-     * with maximum compression quality for space efficiency.
-     *
-     * @param entities - Entities to archive
-     * @returns Archive file path and compression statistics
-     */
-    async saveToArchive(entities) {
-        // Ensure archive directory exists
-        await fs.mkdir(this.archiveDir, { recursive: true });
-        // Generate timestamp-based filename
-        const timestamp = new Date().toISOString()
-            .replace(/:/g, '-')
-            .replace(/\./g, '-')
-            .replace('T', '_')
-            .replace('Z', '');
-        const archivePath = join(this.archiveDir, `archive_${timestamp}.jsonl.br`);
-        // Serialize entities to JSONL format
-        const content = entities.map(e => JSON.stringify(e)).join('\n');
-        // Compress with maximum quality for archives
-        const compressionResult = await compress(content, {
-            quality: COMPRESSION_CONFIG.BROTLI_QUALITY_ARCHIVE,
-            mode: 'text',
-        });
-        // Write compressed archive
-        await fs.writeFile(archivePath, compressionResult.compressed);
-        // Write metadata file
-        const metadataPath = `${archivePath}.meta.json`;
-        const metadata = {
-            timestamp: new Date().toISOString(),
-            entityCount: entities.length,
-            entityNames: entities.map(e => e.name),
-            compressed: true,
-            compressionFormat: 'brotli',
-            originalSize: compressionResult.originalSize,
-            compressedSize: compressionResult.compressedSize,
-            compressionRatio: compressionResult.ratio,
-        };
-        await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
-        return {
-            archivePath,
-            originalSize: compressionResult.originalSize,
-            compressedSize: compressionResult.compressedSize,
-            compressionRatio: compressionResult.ratio,
-        };
-    }
-    /**
-     * List all available archives.
-     *
-     * @returns Array of archive information with compression details
-     */
-    async listArchives() {
-        try {
-            try {
-                await fs.access(this.archiveDir);
-            }
-            catch {
-                return [];
-            }
-            const files = await fs.readdir(this.archiveDir);
-            const archiveFiles = files.filter(f => f.startsWith('archive_') &&
-                (f.endsWith('.jsonl') || f.endsWith('.jsonl.br')) &&
-                !f.endsWith('.meta.json'));
-            const archives = [];
-            for (const fileName of archiveFiles) {
-                const filePath = join(this.archiveDir, fileName);
-                const metadataPath = `${filePath}.meta.json`;
-                try {
-                    const metadataContent = await fs.readFile(metadataPath, 'utf-8');
-                    const metadata = JSON.parse(metadataContent);
-                    archives.push({
-                        fileName,
-                        filePath,
-                        timestamp: metadata.timestamp,
-                        entityCount: metadata.entityCount,
-                        compressed: metadata.compressed ?? fileName.endsWith('.br'),
-                        originalSize: metadata.originalSize,
-                        compressedSize: metadata.compressedSize,
-                        compressionRatio: metadata.compressionRatio,
-                    });
-                }
-                catch {
-                    // Skip archives without valid metadata
-                    continue;
-                }
-            }
-            // Sort by timestamp (newest first)
-            archives.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
-            return archives;
-        }
-        catch {
-            return [];
-        }
-    }
-    /**
-     * Get the path to the archives directory.
-     */
-    getArchiveDir() {
-        return this.archiveDir;
-    }
-}