@danielsimonjr/memory-mcp 11.1.1 → 12.5.2

package/dist/features/IOManager.js

@@ -1,997 +0,0 @@
-/**
- * IO Manager
- *
- * Unified manager for import, export, and backup operations.
- * Consolidates BackupManager, ExportManager, and ImportManager (Sprint 11.4).
- *
- * @module features/IOManager
- */
-import { promises as fs } from 'fs';
-import { dirname, join } from 'path';
-import { FileOperationError } from '../utils/errors.js';
-import { compress, decompress, hasBrotliExtension, COMPRESSION_CONFIG, STREAMING_CONFIG, } from '../utils/index.js';
-import { StreamingExporter } from './StreamingExporter.js';
-// ============================================================
-// IO MANAGER CLASS
-// ============================================================
-/**
- * Unified manager for import, export, and backup operations.
- *
- * Combines functionality from:
- * - ExportManager: Graph export to various formats
- * - ImportManager: Graph import from various formats
- * - BackupManager: Point-in-time backup and restore
- */
-export class IOManager {
-    storage;
-    backupDir;
-    constructor(storage) {
-        this.storage = storage;
-        const filePath = this.storage.getFilePath();
-        const dir = dirname(filePath);
-        this.backupDir = join(dir, '.backups');
-    }
-    // ============================================================
-    // EXPORT OPERATIONS
-    // ============================================================
-    /**
-     * Export graph to specified format.
-     *
-     * @param graph - Knowledge graph to export
-     * @param format - Export format
-     * @returns Formatted export string
-     */
-    exportGraph(graph, format) {
-        switch (format) {
-            case 'json':
-                return this.exportAsJson(graph);
-            case 'csv':
-                return this.exportAsCsv(graph);
-            case 'graphml':
-                return this.exportAsGraphML(graph);
-            case 'gexf':
-                return this.exportAsGEXF(graph);
-            case 'dot':
-                return this.exportAsDOT(graph);
-            case 'markdown':
-                return this.exportAsMarkdown(graph);
-            case 'mermaid':
-                return this.exportAsMermaid(graph);
-            default:
-                throw new Error(`Unsupported export format: ${format}`);
-        }
-    }
-    /**
-     * Export graph with optional brotli compression.
-     *
-     * Compression is applied when:
-     * - `options.compress` is explicitly set to `true`
-     * - The exported content exceeds 100KB (auto-compress threshold)
-     *
-     * Compressed content is returned as base64-encoded string.
-     * Uncompressed content is returned as UTF-8 string.
-     *
-     * @param graph - Knowledge graph to export
-     * @param format - Export format
-     * @param options - Export options including compression settings
-     * @returns Export result with content and compression metadata
-     *
-     * @example
-     * ```typescript
-     * // Export with explicit compression
-     * const result = await manager.exportGraphWithCompression(graph, 'json', {
-     *   compress: true,
-     *   compressionQuality: 11
-     * });
-     *
-     * // Export with auto-compression for large graphs
-     * const result = await manager.exportGraphWithCompression(graph, 'json');
-     * // Compresses automatically if content > 100KB
-     * ```
-     */
-    async exportGraphWithCompression(graph, format, options) {
-        // Check if streaming should be used
-        const shouldStream = options?.streaming ||
-            (options?.outputPath && graph.entities.length >= STREAMING_CONFIG.STREAMING_THRESHOLD);
-        if (shouldStream && options?.outputPath) {
-            return this.streamExport(format, graph, options);
-        }
-        // Generate export content using existing method
-        const content = this.exportGraph(graph, format);
-        const originalSize = Buffer.byteLength(content, 'utf-8');
-        // Determine if compression should be applied
-        const shouldCompress = options?.compress === true ||
-            (options?.compress !== false &&
-                originalSize > COMPRESSION_CONFIG.AUTO_COMPRESS_EXPORT_SIZE);
-        if (shouldCompress) {
-            const quality = options?.compressionQuality ?? COMPRESSION_CONFIG.BROTLI_QUALITY_BATCH;
-            const compressionResult = await compress(content, {
-                quality,
-                mode: 'text',
-            });
-            return {
-                format,
-                content: compressionResult.compressed.toString('base64'),
-                entityCount: graph.entities.length,
-                relationCount: graph.relations.length,
-                compressed: true,
-                encoding: 'base64',
-                originalSize,
-                compressedSize: compressionResult.compressedSize,
-                compressionRatio: compressionResult.ratio,
-            };
-        }
-        // Return uncompressed content
-        return {
-            format,
-            content,
-            entityCount: graph.entities.length,
-            relationCount: graph.relations.length,
-            compressed: false,
-            encoding: 'utf-8',
-            originalSize,
-            compressedSize: originalSize,
-            compressionRatio: 1,
-        };
-    }
-    /**
-     * Stream export to a file for large graphs.
-     *
-     * Uses StreamingExporter to write entities and relations incrementally
-     * to avoid loading the entire export content into memory.
-     *
-     * @param format - Export format
-     * @param graph - Knowledge graph to export
-     * @param options - Export options with required outputPath
-     * @returns Export result with streaming metadata
-     * @private
-     */
-    async streamExport(format, graph, options) {
-        const exporter = new StreamingExporter(options.outputPath);
-        let result;
-        switch (format) {
-            case 'json':
-                // Use JSONL format for streaming (line-delimited JSON)
-                result = await exporter.streamJSONL(graph);
-                break;
-            case 'csv':
-                result = await exporter.streamCSV(graph);
-                break;
-            default:
-                // Fallback to in-memory export for unsupported streaming formats
-                const content = this.exportGraph(graph, format);
-                await fs.writeFile(options.outputPath, content);
-                result = {
-                    bytesWritten: Buffer.byteLength(content, 'utf-8'),
-                    entitiesWritten: graph.entities.length,
-                    relationsWritten: graph.relations.length,
-                    durationMs: 0,
-                };
-        }
-        return {
-            format,
-            content: `Streamed to ${options.outputPath}`,
-            entityCount: result.entitiesWritten,
-            relationCount: result.relationsWritten,
-            compressed: false,
-            encoding: 'utf-8',
-            originalSize: result.bytesWritten,
-            compressedSize: result.bytesWritten,
-            compressionRatio: 1,
-            streamed: true,
-            outputPath: options.outputPath,
-        };
-    }
-    exportAsJson(graph) {
-        return JSON.stringify(graph, null, 2);
-    }
-    exportAsCsv(graph) {
-        const lines = [];
-        const escapeCsvField = (field) => {
-            if (field === undefined || field === null)
-                return '';
-            const str = String(field);
-            if (str.includes(',') || str.includes('"') || str.includes('\n')) {
-                return `"${str.replace(/"/g, '""')}"`;
-            }
-            return str;
-        };
-        lines.push('# ENTITIES');
-        lines.push('name,entityType,observations,createdAt,lastModified,tags,importance');
-        for (const entity of graph.entities) {
-            const observationsStr = entity.observations.join('; ');
-            const tagsStr = entity.tags ? entity.tags.join('; ') : '';
-            const importanceStr = entity.importance !== undefined ? String(entity.importance) : '';
-            lines.push([
-                escapeCsvField(entity.name),
-                escapeCsvField(entity.entityType),
-                escapeCsvField(observationsStr),
-                escapeCsvField(entity.createdAt),
-                escapeCsvField(entity.lastModified),
-                escapeCsvField(tagsStr),
-                escapeCsvField(importanceStr),
-            ].join(','));
-        }
-        lines.push('');
-        lines.push('# RELATIONS');
-        lines.push('from,to,relationType,createdAt,lastModified');
-        for (const relation of graph.relations) {
-            lines.push([
-                escapeCsvField(relation.from),
-                escapeCsvField(relation.to),
-                escapeCsvField(relation.relationType),
-                escapeCsvField(relation.createdAt),
-                escapeCsvField(relation.lastModified),
-            ].join(','));
-        }
-        return lines.join('\n');
-    }
-    exportAsGraphML(graph) {
-        const lines = [];
-        const escapeXml = (str) => {
-            if (str === undefined || str === null)
-                return '';
-            return String(str)
-                .replace(/&/g, '&')
-                .replace(/</g, '&lt;')
-                .replace(/>/g, '&gt;')
-                .replace(/"/g, '&quot;')
-                .replace(/'/g, '&apos;');
-        };
-        lines.push('<?xml version="1.0" encoding="UTF-8"?>');
-        lines.push('<graphml xmlns="http://graphml.graphdrawing.org/xmlns">');
-        lines.push('  <key id="d0" for="node" attr.name="entityType" attr.type="string"/>');
-        lines.push('  <key id="d1" for="node" attr.name="observations" attr.type="string"/>');
-        lines.push('  <key id="d2" for="node" attr.name="createdAt" attr.type="string"/>');
-        lines.push('  <key id="d3" for="node" attr.name="lastModified" attr.type="string"/>');
-        lines.push('  <key id="d4" for="node" attr.name="tags" attr.type="string"/>');
-        lines.push('  <key id="d5" for="node" attr.name="importance" attr.type="double"/>');
-        lines.push('  <key id="e0" for="edge" attr.name="relationType" attr.type="string"/>');
-        lines.push('  <key id="e1" for="edge" attr.name="createdAt" attr.type="string"/>');
-        lines.push('  <key id="e2" for="edge" attr.name="lastModified" attr.type="string"/>');
-        lines.push('  <graph id="G" edgedefault="directed">');
-        for (const entity of graph.entities) {
-            const nodeId = escapeXml(entity.name);
-            lines.push(`    <node id="${nodeId}">`);
-            lines.push(`      <data key="d0">${escapeXml(entity.entityType)}</data>`);
-            lines.push(`      <data key="d1">${escapeXml(entity.observations.join('; '))}</data>`);
-            if (entity.createdAt)
-                lines.push(`      <data key="d2">${escapeXml(entity.createdAt)}</data>`);
-            if (entity.lastModified)
-                lines.push(`      <data key="d3">${escapeXml(entity.lastModified)}</data>`);
-            if (entity.tags?.length)
-                lines.push(`      <data key="d4">${escapeXml(entity.tags.join('; '))}</data>`);
-            if (entity.importance !== undefined)
-                lines.push(`      <data key="d5">${entity.importance}</data>`);
-            lines.push('    </node>');
-        }
-        let edgeId = 0;
-        for (const relation of graph.relations) {
-            const sourceId = escapeXml(relation.from);
-            const targetId = escapeXml(relation.to);
-            lines.push(`    <edge id="e${edgeId}" source="${sourceId}" target="${targetId}">`);
-            lines.push(`      <data key="e0">${escapeXml(relation.relationType)}</data>`);
-            if (relation.createdAt)
-                lines.push(`      <data key="e1">${escapeXml(relation.createdAt)}</data>`);
-            if (relation.lastModified)
-                lines.push(`      <data key="e2">${escapeXml(relation.lastModified)}</data>`);
-            lines.push('    </edge>');
-            edgeId++;
-        }
-        lines.push('  </graph>');
-        lines.push('</graphml>');
-        return lines.join('\n');
-    }
-    exportAsGEXF(graph) {
-        const lines = [];
-        const escapeXml = (str) => {
-            if (str === undefined || str === null)
-                return '';
-            return String(str)
-                .replace(/&/g, '&amp;')
-                .replace(/</g, '&lt;')
-                .replace(/>/g, '&gt;')
-                .replace(/"/g, '&quot;')
-                .replace(/'/g, '&apos;');
-        };
-        lines.push('<?xml version="1.0" encoding="UTF-8"?>');
-        lines.push('<gexf xmlns="http://www.gexf.net/1.2draft" version="1.2">');
-        lines.push('  <meta>');
-        lines.push('    <creator>Memory MCP Server</creator>');
-        lines.push('  </meta>');
-        lines.push('  <graph mode="static" defaultedgetype="directed">');
-        lines.push('    <attributes class="node">');
-        lines.push('      <attribute id="0" title="entityType" type="string"/>');
-        lines.push('      <attribute id="1" title="observations" type="string"/>');
-        lines.push('    </attributes>');
-        lines.push('    <nodes>');
-        for (const entity of graph.entities) {
-            const nodeId = escapeXml(entity.name);
-            lines.push(`      <node id="${nodeId}" label="${nodeId}">`);
-            lines.push('        <attvalues>');
-            lines.push(`          <attvalue for="0" value="${escapeXml(entity.entityType)}"/>`);
-            lines.push(`          <attvalue for="1" value="${escapeXml(entity.observations.join('; '))}"/>`);
-            lines.push('        </attvalues>');
-            lines.push('      </node>');
-        }
-        lines.push('    </nodes>');
-        lines.push('    <edges>');
-        let edgeId = 0;
-        for (const relation of graph.relations) {
-            const sourceId = escapeXml(relation.from);
-            const targetId = escapeXml(relation.to);
-            const label = escapeXml(relation.relationType);
-            lines.push(`      <edge id="${edgeId}" source="${sourceId}" target="${targetId}" label="${label}"/>`);
-            edgeId++;
-        }
-        lines.push('    </edges>');
-        lines.push('  </graph>');
-        lines.push('</gexf>');
-        return lines.join('\n');
-    }
-    exportAsDOT(graph) {
-        const lines = [];
-        const escapeDot = (str) => {
-            return '"' + str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n') + '"';
-        };
-        lines.push('digraph KnowledgeGraph {');
-        lines.push('  rankdir=LR;');
-        lines.push('  node [shape=box, style=rounded];');
-        lines.push('');
-        for (const entity of graph.entities) {
-            const nodeId = escapeDot(entity.name);
-            const label = [`${entity.name}`, `Type: ${entity.entityType}`];
-            if (entity.tags?.length)
-                label.push(`Tags: ${entity.tags.join(', ')}`);
-            const labelStr = escapeDot(label.join('\\n'));
-            lines.push(`  ${nodeId} [label=${labelStr}];`);
-        }
-        lines.push('');
-        for (const relation of graph.relations) {
-            const fromId = escapeDot(relation.from);
-            const toId = escapeDot(relation.to);
-            const label = escapeDot(relation.relationType);
-            lines.push(`  ${fromId} -> ${toId} [label=${label}];`);
-        }
-        lines.push('}');
-        return lines.join('\n');
-    }
-    exportAsMarkdown(graph) {
-        const lines = [];
-        lines.push('# Knowledge Graph Export');
-        lines.push('');
-        lines.push(`**Exported:** ${new Date().toISOString()}`);
-        lines.push(`**Entities:** ${graph.entities.length}`);
-        lines.push(`**Relations:** ${graph.relations.length}`);
-        lines.push('');
-        lines.push('## Entities');
-        lines.push('');
-        for (const entity of graph.entities) {
-            lines.push(`### ${entity.name}`);
-            lines.push('');
-            lines.push(`- **Type:** ${entity.entityType}`);
-            if (entity.tags?.length)
-                lines.push(`- **Tags:** ${entity.tags.map(t => `\`${t}\``).join(', ')}`);
-            if (entity.importance !== undefined)
-                lines.push(`- **Importance:** ${entity.importance}/10`);
-            if (entity.observations.length > 0) {
-                lines.push('');
-                lines.push('**Observations:**');
-                for (const obs of entity.observations) {
-                    lines.push(`- ${obs}`);
-                }
-            }
-            lines.push('');
-        }
-        if (graph.relations.length > 0) {
-            lines.push('## Relations');
-            lines.push('');
-            for (const relation of graph.relations) {
-                lines.push(`- **${relation.from}** → *${relation.relationType}* → **${relation.to}**`);
-            }
-            lines.push('');
-        }
-        return lines.join('\n');
-    }
-    exportAsMermaid(graph) {
-        const lines = [];
-        const sanitizeId = (str) => str.replace(/[^a-zA-Z0-9_]/g, '_');
-        const escapeLabel = (str) => str.replace(/"/g, '#quot;');
-        lines.push('graph LR');
-        lines.push('  %% Knowledge Graph');
-        lines.push('');
-        const nodeIds = new Map();
-        for (const entity of graph.entities) {
-            nodeIds.set(entity.name, sanitizeId(entity.name));
-        }
-        for (const entity of graph.entities) {
-            const nodeId = nodeIds.get(entity.name);
-            const labelParts = [entity.name, `Type: ${entity.entityType}`];
-            if (entity.tags?.length)
-                labelParts.push(`Tags: ${entity.tags.join(', ')}`);
-            const label = escapeLabel(labelParts.join('<br/>'));
-            lines.push(`  ${nodeId}["${label}"]`);
-        }
-        lines.push('');
-        for (const relation of graph.relations) {
-            const fromId = nodeIds.get(relation.from);
-            const toId = nodeIds.get(relation.to);
-            if (fromId && toId) {
-                const label = escapeLabel(relation.relationType);
-                lines.push(`  ${fromId} -->|"${label}"| ${toId}`);
-            }
-        }
-        return lines.join('\n');
-    }
-    // ============================================================
-    // IMPORT OPERATIONS
-    // ============================================================
-    /**
-     * Import graph from formatted data.
-     *
-     * @param format - Import format
-     * @param data - Import data string
-     * @param mergeStrategy - How to handle conflicts
-     * @param dryRun - If true, preview changes without applying
-     * @returns Import result with statistics
-     */
-    async importGraph(format, data, mergeStrategy = 'skip', dryRun = false) {
-        let importedGraph;
-        try {
-            switch (format) {
-                case 'json':
-                    importedGraph = this.parseJsonImport(data);
-                    break;
-                case 'csv':
-                    importedGraph = this.parseCsvImport(data);
-                    break;
-                case 'graphml':
-                    importedGraph = this.parseGraphMLImport(data);
-                    break;
-                default:
-                    throw new Error(`Unsupported import format: ${format}`);
-            }
-        }
-        catch (error) {
-            return {
-                entitiesAdded: 0,
-                entitiesSkipped: 0,
-                entitiesUpdated: 0,
-                relationsAdded: 0,
-                relationsSkipped: 0,
-                errors: [`Failed to parse ${format} data: ${error instanceof Error ? error.message : String(error)}`],
-            };
-        }
-        return await this.mergeImportedGraph(importedGraph, mergeStrategy, dryRun);
-    }
-    parseJsonImport(data) {
-        const parsed = JSON.parse(data);
-        if (!parsed.entities || !Array.isArray(parsed.entities)) {
-            throw new Error('Invalid JSON: missing or invalid entities array');
-        }
-        if (!parsed.relations || !Array.isArray(parsed.relations)) {
-            throw new Error('Invalid JSON: missing or invalid relations array');
-        }
-        return {
-            entities: parsed.entities,
-            relations: parsed.relations,
-        };
-    }
-    parseCsvImport(data) {
-        const lines = data
-            .split('\n')
-            .map(line => line.trim())
-            .filter(line => line);
-        const entities = [];
-        const relations = [];
-        let section = null;
-        let headerParsed = false;
-        const parseCsvLine = (line) => {
-            const fields = [];
-            let current = '';
-            let inQuotes = false;
-            for (let i = 0; i < line.length; i++) {
-                const char = line[i];
-                if (char === '"') {
-                    if (inQuotes && line[i + 1] === '"') {
-                        current += '"';
-                        i++;
-                    }
-                    else {
-                        inQuotes = !inQuotes;
-                    }
-                }
-                else if (char === ',' && !inQuotes) {
-                    fields.push(current);
-                    current = '';
-                }
-                else {
-                    current += char;
-                }
-            }
-            fields.push(current);
-            return fields;
-        };
-        for (const line of lines) {
-            if (line.startsWith('# ENTITIES')) {
-                section = 'entities';
-                headerParsed = false;
-                continue;
-            }
-            else if (line.startsWith('# RELATIONS')) {
-                section = 'relations';
-                headerParsed = false;
-                continue;
-            }
-            if (line.startsWith('#'))
-                continue;
-            if (section === 'entities') {
-                if (!headerParsed) {
-                    headerParsed = true;
-                    continue;
-                }
-                const fields = parseCsvLine(line);
-                if (fields.length >= 2) {
-                    const entity = {
-                        name: fields[0],
-                        entityType: fields[1],
-                        observations: fields[2]
-                            ? fields[2]
-                                .split(';')
-                                .map(s => s.trim())
-                                .filter(s => s)
-                            : [],
-                        createdAt: fields[3] || undefined,
-                        lastModified: fields[4] || undefined,
-                        tags: fields[5]
-                            ? fields[5]
-                                .split(';')
-                                .map(s => s.trim().toLowerCase())
-                                .filter(s => s)
-                            : undefined,
-                        importance: fields[6] ? parseFloat(fields[6]) : undefined,
-                    };
-                    entities.push(entity);
-                }
-            }
-            else if (section === 'relations') {
-                if (!headerParsed) {
-                    headerParsed = true;
-                    continue;
-                }
-                const fields = parseCsvLine(line);
-                if (fields.length >= 3) {
-                    const relation = {
-                        from: fields[0],
-                        to: fields[1],
-                        relationType: fields[2],
-                        createdAt: fields[3] || undefined,
-                        lastModified: fields[4] || undefined,
-                    };
-                    relations.push(relation);
-                }
-            }
-        }
-        return { entities, relations };
-    }
-    parseGraphMLImport(data) {
-        const entities = [];
-        const relations = [];
-        const nodeRegex = /<node\s+id="([^"]+)"[^>]*>([\s\S]*?)<\/node>/g;
-        let nodeMatch;
-        while ((nodeMatch = nodeRegex.exec(data)) !== null) {
-            const nodeId = nodeMatch[1];
-            const nodeContent = nodeMatch[2];
-            const getDataValue = (key) => {
-                const dataRegex = new RegExp(`<data\\s+key="${key}">([^<]*)<\/data>`);
-                const match = dataRegex.exec(nodeContent);
-                return match ? match[1] : undefined;
-            };
-            const entity = {
-                name: nodeId,
-                entityType: getDataValue('d0') || getDataValue('entityType') || 'unknown',
-                observations: (getDataValue('d1') || getDataValue('observations') || '')
-                    .split(';')
-                    .map(s => s.trim())
-                    .filter(s => s),
-                createdAt: getDataValue('d2') || getDataValue('createdAt'),
-                lastModified: getDataValue('d3') || getDataValue('lastModified'),
-                tags: (getDataValue('d4') || getDataValue('tags') || '')
-                    .split(';')
-                    .map(s => s.trim().toLowerCase())
-                    .filter(s => s),
-                importance: getDataValue('d5') || getDataValue('importance') ? parseFloat(getDataValue('d5') || getDataValue('importance') || '0') : undefined,
-            };
-            entities.push(entity);
-        }
-        const edgeRegex = /<edge\s+[^>]*source="([^"]+)"\s+target="([^"]+)"[^>]*>([\s\S]*?)<\/edge>/g;
-        let edgeMatch;
-        while ((edgeMatch = edgeRegex.exec(data)) !== null) {
-            const source = edgeMatch[1];
-            const target = edgeMatch[2];
-            const edgeContent = edgeMatch[3];
-            const getDataValue = (key) => {
-                const dataRegex = new RegExp(`<data\\s+key="${key}">([^<]*)<\/data>`);
-                const match = dataRegex.exec(edgeContent);
-                return match ? match[1] : undefined;
-            };
-            const relation = {
-                from: source,
-                to: target,
-                relationType: getDataValue('e0') || getDataValue('relationType') || 'related_to',
-                createdAt: getDataValue('e1') || getDataValue('createdAt'),
-                lastModified: getDataValue('e2') || getDataValue('lastModified'),
-            };
-            relations.push(relation);
-        }
-        return { entities, relations };
-    }
-    async mergeImportedGraph(importedGraph, mergeStrategy, dryRun) {
-        const existingGraph = await this.storage.getGraphForMutation();
-        const result = {
-            entitiesAdded: 0,
-            entitiesSkipped: 0,
-            entitiesUpdated: 0,
-            relationsAdded: 0,
-            relationsSkipped: 0,
-            errors: [],
-        };
-        const existingEntitiesMap = new Map();
-        for (const entity of existingGraph.entities) {
-            existingEntitiesMap.set(entity.name, entity);
-        }
-        const existingRelationsSet = new Set();
-        for (const relation of existingGraph.relations) {
-            existingRelationsSet.add(`${relation.from}|${relation.to}|${relation.relationType}`);
-        }
-        for (const importedEntity of importedGraph.entities) {
-            const existing = existingEntitiesMap.get(importedEntity.name);
-            if (!existing) {
-                result.entitiesAdded++;
-                if (!dryRun) {
-                    existingGraph.entities.push(importedEntity);
-                    existingEntitiesMap.set(importedEntity.name, importedEntity);
-                }
-            }
-            else {
-                switch (mergeStrategy) {
-                    case 'replace':
-                        result.entitiesUpdated++;
-                        if (!dryRun) {
-                            Object.assign(existing, importedEntity);
-                        }
-                        break;
-                    case 'skip':
-                        result.entitiesSkipped++;
-                        break;
-                    case 'merge':
-                        result.entitiesUpdated++;
-                        if (!dryRun) {
-                            existing.observations = [
-                                ...new Set([...existing.observations, ...importedEntity.observations]),
-                            ];
-                            if (importedEntity.tags) {
-                                existing.tags = existing.tags || [];
-                                existing.tags = [...new Set([...existing.tags, ...importedEntity.tags])];
-                            }
-                            if (importedEntity.importance !== undefined) {
-                                existing.importance = importedEntity.importance;
-                            }
-                            existing.lastModified = new Date().toISOString();
-                        }
-                        break;
-                    case 'fail':
-                        result.errors.push(`Entity "${importedEntity.name}" already exists`);
-                        break;
-                }
-            }
-        }
-        for (const importedRelation of importedGraph.relations) {
-            const relationKey = `${importedRelation.from}|${importedRelation.to}|${importedRelation.relationType}`;
-            if (!existingEntitiesMap.has(importedRelation.from)) {
-                result.errors.push(`Relation source entity "${importedRelation.from}" does not exist`);
-                continue;
-            }
-            if (!existingEntitiesMap.has(importedRelation.to)) {
-                result.errors.push(`Relation target entity "${importedRelation.to}" does not exist`);
-                continue;
-            }
-            if (!existingRelationsSet.has(relationKey)) {
-                result.relationsAdded++;
-                if (!dryRun) {
-                    existingGraph.relations.push(importedRelation);
-                    existingRelationsSet.add(relationKey);
-                }
-            }
-            else {
-                if (mergeStrategy === 'fail') {
-                    result.errors.push(`Relation "${relationKey}" already exists`);
-                }
-                else {
-                    result.relationsSkipped++;
-                }
-            }
-        }
-        if (!dryRun && (mergeStrategy !== 'fail' || result.errors.length === 0)) {
-            await this.storage.saveGraph(existingGraph);
-        }
-        return result;
-    }
-    // ============================================================
-    // BACKUP OPERATIONS
-    // ============================================================
-    /**
-     * Ensure backup directory exists.
-     */
-    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.
-     * @param compressed - Whether the backup will be compressed (affects extension)
-     */
-    generateBackupFileName(compressed = true) {
-        const now = new Date();
-        const timestamp = now.toISOString()
-            .replace(/:/g, '-')
-            .replace(/\./g, '-')
-            .replace('T', '_')
-            .replace('Z', '');
-        const extension = compressed ? '.jsonl.br' : '.jsonl';
-        return `backup_${timestamp}${extension}`;
-    }
-    /**
-     * Create a backup of the current knowledge graph.
-     *
-     * By default, backups are compressed with brotli for 50-70% space reduction.
-     * Use `options.compress = false` to create uncompressed backups.
-     *
-     * @param options - Backup options (compress, description) or legacy description string
-     * @returns Promise resolving to BackupResult with compression statistics
-     *
-     * @example
-     * ```typescript
-     * // Compressed backup (default)
-     * const result = await manager.createBackup({ description: 'Pre-migration backup' });
-     * console.log(`Compressed from ${result.originalSize} to ${result.compressedSize} bytes`);
-     *
-     * // Uncompressed backup
-     * const result = await manager.createBackup({ compress: false });
-     * ```
-     */
-    async createBackup(options) {
-        await this.ensureBackupDir();
-        // Handle legacy string argument (backward compatibility)
-        const opts = typeof options === 'string'
-            ? { description: options, compress: COMPRESSION_CONFIG.AUTO_COMPRESS_BACKUP }
-            : { compress: COMPRESSION_CONFIG.AUTO_COMPRESS_BACKUP, ...options };
-        const shouldCompress = opts.compress ?? COMPRESSION_CONFIG.AUTO_COMPRESS_BACKUP;
-        const graph = await this.storage.loadGraph();
-        const timestamp = new Date().toISOString();
-        const fileName = this.generateBackupFileName(shouldCompress);
-        const backupPath = join(this.backupDir, fileName);
-        try {
-            const originalPath = this.storage.getFilePath();
-            let fileContent;
-            try {
-                fileContent = await fs.readFile(originalPath, 'utf-8');
-            }
-            catch {
-                // If file doesn't exist, 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');
-            }
-            const originalSize = Buffer.byteLength(fileContent, 'utf-8');
-            let compressedSize = originalSize;
-            let compressionRatio = 1;
-            if (shouldCompress) {
-                // Compress with maximum quality for backups (archive quality)
-                const compressionResult = await compress(fileContent, {
-                    quality: COMPRESSION_CONFIG.BROTLI_QUALITY_ARCHIVE,
-                    mode: 'text',
-                });
-                await fs.writeFile(backupPath, compressionResult.compressed);
-                compressedSize = compressionResult.compressedSize;
-                compressionRatio = compressionResult.ratio;
-            }
-            else {
-                // Write uncompressed backup
-                await fs.writeFile(backupPath, fileContent);
-            }
-            const stats = await fs.stat(backupPath);
-            const metadata = {
-                timestamp,
-                entityCount: graph.entities.length,
-                relationCount: graph.relations.length,
-                fileSize: stats.size,
-                description: opts.description,
-                compressed: shouldCompress,
-                originalSize,
-                compressionRatio: shouldCompress ? compressionRatio : undefined,
-                compressionFormat: shouldCompress ? 'brotli' : 'none',
-            };
-            const metadataPath = `${backupPath}.meta.json`;
-            await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
-            return {
-                path: backupPath,
-                timestamp,
-                entityCount: graph.entities.length,
-                relationCount: graph.relations.length,
-                compressed: shouldCompress,
-                originalSize,
-                compressedSize,
-                compressionRatio,
-                description: opts.description,
-            };
-        }
-        catch (error) {
-            throw new FileOperationError('create backup', backupPath, error);
-        }
-    }
-    /**
-     * List all available backups, sorted by timestamp (newest first).
-     *
-     * Detects both compressed (.jsonl.br) and uncompressed (.jsonl) backups.
-     *
-     * @returns Promise resolving to array of backup information with compression details
-     */
-    async listBackups() {
-        try {
-            try {
-                await fs.access(this.backupDir);
-            }
-            catch {
-                return [];
-            }
-            const files = await fs.readdir(this.backupDir);
-            // Match both .jsonl and .jsonl.br backup files, exclude metadata files
-            const backupFiles = files.filter(f => f.startsWith('backup_') &&
-                (f.endsWith('.jsonl') || f.endsWith('.jsonl.br')) &&
-                !f.endsWith('.meta.json'));
-            const backups = [];
-            for (const fileName of backupFiles) {
-                const filePath = join(this.backupDir, fileName);
-                const isCompressed = hasBrotliExtension(fileName);
-                // Try to read metadata file (handles both .jsonl.meta.json and .jsonl.br.meta.json)
-                const metadataPath = `${filePath}.meta.json`;
-                try {
-                    const [metadataContent, stats] = await Promise.all([
-                        fs.readFile(metadataPath, 'utf-8'),
-                        fs.stat(filePath),
-                    ]);
-                    const metadata = JSON.parse(metadataContent);
-                    // Ensure compression fields are present (backward compatibility)
-                    if (metadata.compressed === undefined) {
-                        metadata.compressed = isCompressed;
-                    }
-                    if (metadata.compressionFormat === undefined) {
-                        metadata.compressionFormat = isCompressed ? 'brotli' : 'none';
-                    }
-                    backups.push({
-                        fileName,
-                        filePath,
-                        metadata,
-                        compressed: isCompressed,
-                        size: stats.size,
-                    });
-                }
-                catch {
-                    // Skip backups without valid metadata
-                    continue;
-                }
-            }
-            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.
-     *
-     * Automatically detects and decompresses brotli-compressed backups (.br extension).
-     * Maintains backward compatibility with uncompressed backups.
-     *
-     * @param backupPath - Path to the backup file to restore from
-     * @returns Promise resolving to RestoreResult with restoration details
-     *
-     * @example
-     * ```typescript
-     * // Restore from compressed backup
-     * const result = await manager.restoreFromBackup('/path/to/backup.jsonl.br');
-     * console.log(`Restored ${result.entityCount} entities from compressed backup`);
-     *
-     * // Restore from uncompressed backup (legacy)
-     * const result = await manager.restoreFromBackup('/path/to/backup.jsonl');
-     * ```
-     */
-    async restoreFromBackup(backupPath) {
-        try {
-            await fs.access(backupPath);
-            const isCompressed = hasBrotliExtension(backupPath);
-            const backupBuffer = await fs.readFile(backupPath);
-            let backupContent;
-            if (isCompressed) {
-                // Decompress the backup
-                const decompressedBuffer = await decompress(backupBuffer);
-                backupContent = decompressedBuffer.toString('utf-8');
-            }
-            else {
-                // Read as plain text
-                backupContent = backupBuffer.toString('utf-8');
-            }
-            const mainPath = this.storage.getFilePath();
-            await fs.writeFile(mainPath, backupContent);
-            this.storage.clearCache();
-            // Load the restored graph to get counts
-            const graph = await this.storage.loadGraph();
-            return {
-                entityCount: graph.entities.length,
-                relationCount: graph.relations.length,
-                restoredFrom: backupPath,
-                wasCompressed: isCompressed,
-            };
-        }
-        catch (error) {
-            throw new FileOperationError('restore from backup', backupPath, error);
-        }
-    }
-    /**
-     * Delete a specific backup file.
-     *
-     * @param backupPath - Path to the backup file to delete
-     */
-    async deleteBackup(backupPath) {
-        try {
-            await fs.unlink(backupPath);
-            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.
-     *
-     * @param keepCount - Number of recent backups to keep (default: 10)
-     * @returns Promise resolving to number of backups deleted
-     */
-    async cleanOldBackups(keepCount = 10) {
-        const backups = await this.listBackups();
-        if (backups.length <= keepCount) {
-            return 0;
-        }
-        const backupsToDelete = backups.slice(keepCount);
-        let deletedCount = 0;
-        for (const backup of backupsToDelete) {
-            try {
-                await this.deleteBackup(backup.filePath);
-                deletedCount++;
-            }
-            catch {
-                continue;
-            }
-        }
-        return deletedCount;
-    }
-    /**
-     * Get the path to the backup directory.
-     */
-    getBackupDir() {
-        return this.backupDir;
-    }
-}