@danielsimonjr/memory-mcp 0.7.2 → 0.41.0

package/dist/features/HierarchyManager.js

@@ -0,0 +1,219 @@
+/**
+ * Hierarchy Manager
+ *
+ * Manages entity parent-child relationships and hierarchical operations.
+ *
+ * @module features/HierarchyManager
+ */
+import { EntityNotFoundError, CycleDetectedError } from '../utils/errors.js';
+/**
+ * Manages hierarchical entity relationships.
+ */
+export class HierarchyManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Set the parent of an entity.
+     *
+     * Validates:
+     * - Entity and parent exist
+     * - Setting parent won't create a cycle
+     *
+     * @param entityName - Entity to set parent for
+     * @param parentName - Parent entity name (null to remove parent)
+     * @returns Updated entity
+     * @throws {EntityNotFoundError} If entity or parent not found
+     * @throws {CycleDetectedError} If setting parent would create a cycle
+     */
+    async setEntityParent(entityName, parentName) {
+        const graph = await this.storage.loadGraph();
+        const entity = graph.entities.find(e => e.name === entityName);
+        if (!entity) {
+            throw new EntityNotFoundError(entityName);
+        }
+        // If setting a parent, validate it exists and doesn't create a cycle
+        if (parentName !== null) {
+            const parent = graph.entities.find(e => e.name === parentName);
+            if (!parent) {
+                throw new EntityNotFoundError(parentName);
+            }
+            // Check for cycles
+            if (this.wouldCreateCycle(graph, entityName, parentName)) {
+                throw new CycleDetectedError(entityName, parentName);
+            }
+        }
+        entity.parentId = parentName || undefined;
+        entity.lastModified = new Date().toISOString();
+        await this.storage.saveGraph(graph);
+        return entity;
+    }
+    /**
+     * Check if setting a parent would create a cycle in the hierarchy.
+     *
+     * @param graph - Knowledge graph
+     * @param entityName - Entity to set parent for
+     * @param parentName - Proposed parent
+     * @returns True if cycle would be created
+     */
+    wouldCreateCycle(graph, entityName, parentName) {
+        const visited = new Set();
+        let current = parentName;
+        while (current) {
+            if (visited.has(current)) {
+                return true; // Cycle detected in existing hierarchy
+            }
+            if (current === entityName) {
+                return true; // Would create a cycle
+            }
+            visited.add(current);
+            const currentEntity = graph.entities.find(e => e.name === current);
+            current = currentEntity?.parentId;
+        }
+        return false;
+    }
+    /**
+     * Get the immediate children of an entity.
+     *
+     * @param entityName - Parent entity name
+     * @returns Array of child entities
+     * @throws {EntityNotFoundError} If entity not found
+     */
+    async getChildren(entityName) {
+        const graph = await this.storage.loadGraph();
+        // Verify entity exists
+        if (!graph.entities.find(e => e.name === entityName)) {
+            throw new EntityNotFoundError(entityName);
+        }
+        return graph.entities.filter(e => e.parentId === entityName);
+    }
+    /**
+     * Get the parent of an entity.
+     *
+     * @param entityName - Entity name
+     * @returns Parent entity or null if no parent
+     * @throws {EntityNotFoundError} If entity not found
+     */
+    async getParent(entityName) {
+        const graph = await this.storage.loadGraph();
+        const entity = graph.entities.find(e => e.name === entityName);
+        if (!entity) {
+            throw new EntityNotFoundError(entityName);
+        }
+        if (!entity.parentId) {
+            return null;
+        }
+        const parent = graph.entities.find(e => e.name === entity.parentId);
+        return parent || null;
+    }
+    /**
+     * Get all ancestors of an entity (parent, grandparent, etc.).
+     *
+     * @param entityName - Entity name
+     * @returns Array of ancestor entities (ordered from immediate parent to root)
+     * @throws {EntityNotFoundError} If entity not found
+     */
+    async getAncestors(entityName) {
+        const graph = await this.storage.loadGraph();
+        const ancestors = [];
+        let current = graph.entities.find(e => e.name === entityName);
+        if (!current) {
+            throw new EntityNotFoundError(entityName);
+        }
+        while (current.parentId) {
+            const parent = graph.entities.find(e => e.name === current.parentId);
+            if (!parent)
+                break;
+            ancestors.push(parent);
+            current = parent;
+        }
+        return ancestors;
+    }
+    /**
+     * Get all descendants of an entity (children, grandchildren, etc.).
+     *
+     * Uses breadth-first traversal.
+     *
+     * @param entityName - Entity name
+     * @returns Array of descendant entities
+     * @throws {EntityNotFoundError} If entity not found
+     */
+    async getDescendants(entityName) {
+        const graph = await this.storage.loadGraph();
+        // Verify entity exists
+        if (!graph.entities.find(e => e.name === entityName)) {
+            throw new EntityNotFoundError(entityName);
+        }
+        const descendants = [];
+        const toProcess = [entityName];
+        while (toProcess.length > 0) {
+            const current = toProcess.shift();
+            const children = graph.entities.filter(e => e.parentId === current);
+            for (const child of children) {
+                descendants.push(child);
+                toProcess.push(child.name);
+            }
+        }
+        return descendants;
+    }
+    /**
+     * Get the entire subtree rooted at an entity (entity + all descendants).
+     *
+     * Includes relations between entities in the subtree.
+     *
+     * @param entityName - Root entity name
+     * @returns Knowledge graph containing subtree
+     * @throws {EntityNotFoundError} If entity not found
+     */
+    async getSubtree(entityName) {
+        const graph = await this.storage.loadGraph();
+        const entity = graph.entities.find(e => e.name === entityName);
+        if (!entity) {
+            throw new EntityNotFoundError(entityName);
+        }
+        const descendants = await this.getDescendants(entityName);
+        const subtreeEntities = [entity, ...descendants];
+        const subtreeEntityNames = new Set(subtreeEntities.map(e => e.name));
+        // Include relations between entities in the subtree
+        const subtreeRelations = graph.relations.filter(r => subtreeEntityNames.has(r.from) && subtreeEntityNames.has(r.to));
+        return {
+            entities: subtreeEntities,
+            relations: subtreeRelations,
+        };
+    }
+    /**
+     * Get root entities (entities with no parent).
+     *
+     * @returns Array of root entities
+     */
+    async getRootEntities() {
+        const graph = await this.storage.loadGraph();
+        return graph.entities.filter(e => !e.parentId);
+    }
+    /**
+     * Get the depth of an entity in the hierarchy.
+     *
+     * Root entities have depth 0, their children depth 1, etc.
+     *
+     * @param entityName - Entity name
+     * @returns Depth (number of ancestors)
+     * @throws Error if entity not found
+     */
+    async getEntityDepth(entityName) {
+        const ancestors = await this.getAncestors(entityName);
+        return ancestors.length;
+    }
+    /**
+     * Move an entity to a new parent (maintaining its descendants).
+     *
+     * Alias for setEntityParent.
+     *
+     * @param entityName - Entity to move
+     * @param newParentName - New parent name (null to make root)
+     * @returns Updated entity
+     */
+    async moveEntity(entityName, newParentName) {
+        return await this.setEntityParent(entityName, newParentName);
+    }
+}

package/dist/features/ImportExportManager.js

@@ -0,0 +1,50 @@
+/**
+ * Import/Export Manager
+ *
+ * Orchestrates import and export operations with optional filtering.
+ *
+ * @module features/ImportExportManager
+ */
+/**
+ * Orchestrates import and export operations.
+ */
+export class ImportExportManager {
+    basicSearch;
+    exportManager;
+    importManager;
+    constructor(exportManager, importManager, basicSearch) {
+        this.basicSearch = basicSearch;
+        this.exportManager = exportManager;
+        this.importManager = importManager;
+    }
+    /**
+     * Export graph to specified format with optional filtering.
+     *
+     * @param format - Export format
+     * @param filter - Optional export filter
+     * @returns Formatted export string
+     */
+    async exportGraph(format, filter) {
+        let graph;
+        if (filter) {
+            graph = await this.basicSearch.searchByDateRange(filter.startDate, filter.endDate, filter.entityType, filter.tags);
+        }
+        else {
+            // Get full graph via basicSearch's storage
+            graph = await this.basicSearch.storage.loadGraph();
+        }
+        return this.exportManager.exportGraph(graph, format);
+    }
+    /**
+     * 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, dryRun) {
+        return this.importManager.importGraph(format, data, mergeStrategy, dryRun);
+    }
+}

package/dist/features/ImportManager.js

@@ -0,0 +1,328 @@
+/**
+ * Import Manager
+ *
+ * Imports knowledge graphs from various formats (JSON, CSV, GraphML) with merge strategies.
+ *
+ * @module features/ImportManager
+ */
+/**
+ * Manages knowledge graph imports from multiple formats.
+ */
+export class ImportManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Parse JSON format.
+     */
+    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,
+        };
+    }
+    /**
+     * Parse CSV format.
+     *
+     * Expects: # ENTITIES section with header, then # RELATIONS section with header
+     */
+    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 };
+    }
+    /**
+     * Parse GraphML format.
+     *
+     * Note: Simplified regex-based parser for basic GraphML structure.
+     */
+    parseGraphMLImport(data) {
+        const entities = [];
+        const relations = [];
+        // Extract nodes
+        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);
+        }
+        // Extract edges
+        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 };
+    }
+    /**
+     * Merge imported graph with existing graph.
+     */
+    async mergeImportedGraph(importedGraph, mergeStrategy, dryRun) {
+        const existingGraph = await this.storage.loadGraph();
+        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}`);
+        }
+        // Process entities
+        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;
+                }
+            }
+        }
+        // Process relations
+        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++;
+                }
+            }
+        }
+        // Save if not dry run and no blocking errors
+        if (!dryRun && (mergeStrategy !== 'fail' || result.errors.length === 0)) {
+            await this.storage.saveGraph(existingGraph);
+        }
+        return result;
+    }
+}