@danielsimonjr/memory-mcp 0.7.2 → 0.47.1

package/dist/features/CompressionManager.js

@@ -0,0 +1,291 @@
+/**
+ * Compression Manager
+ *
+ * Detects and merges duplicate entities to compress the knowledge graph.
+ *
+ * @module features/CompressionManager
+ */
+import { levenshteinDistance } from '../utils/levenshtein.js';
+import { EntityNotFoundError, InsufficientEntitiesError } from '../utils/errors.js';
+import { SIMILARITY_WEIGHTS, DEFAULT_DUPLICATE_THRESHOLD } from '../utils/constants.js';
+/**
+ * Manages graph compression through duplicate detection and merging.
+ */
+export class CompressionManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Calculate similarity between two entities using multiple heuristics.
+     *
+     * Uses configurable weights defined in SIMILARITY_WEIGHTS constant.
+     * See SIMILARITY_WEIGHTS for the breakdown of scoring factors.
+     *
+     * @param e1 - First entity
+     * @param e2 - Second entity
+     * @returns Similarity score from 0 (completely different) to 1 (identical)
+     */
+    calculateEntitySimilarity(e1, e2) {
+        let score = 0;
+        let factors = 0;
+        // Name similarity (Levenshtein-based)
+        const nameDistance = levenshteinDistance(e1.name.toLowerCase(), e2.name.toLowerCase());
+        const maxNameLength = Math.max(e1.name.length, e2.name.length);
+        const nameSimilarity = 1 - nameDistance / maxNameLength;
+        score += nameSimilarity * SIMILARITY_WEIGHTS.NAME;
+        factors += SIMILARITY_WEIGHTS.NAME;
+        // Type similarity (exact match)
+        if (e1.entityType.toLowerCase() === e2.entityType.toLowerCase()) {
+            score += SIMILARITY_WEIGHTS.TYPE;
+        }
+        factors += SIMILARITY_WEIGHTS.TYPE;
+        // Observation overlap (Jaccard similarity)
+        const obs1Set = new Set(e1.observations.map(o => o.toLowerCase()));
+        const obs2Set = new Set(e2.observations.map(o => o.toLowerCase()));
+        const intersection = new Set([...obs1Set].filter(x => obs2Set.has(x)));
+        const union = new Set([...obs1Set, ...obs2Set]);
+        const observationSimilarity = union.size > 0 ? intersection.size / union.size : 0;
+        score += observationSimilarity * SIMILARITY_WEIGHTS.OBSERVATIONS;
+        factors += SIMILARITY_WEIGHTS.OBSERVATIONS;
+        // Tag overlap (Jaccard similarity)
+        if (e1.tags && e2.tags && (e1.tags.length > 0 || e2.tags.length > 0)) {
+            const tags1Set = new Set(e1.tags.map(t => t.toLowerCase()));
+            const tags2Set = new Set(e2.tags.map(t => t.toLowerCase()));
+            const tagIntersection = new Set([...tags1Set].filter(x => tags2Set.has(x)));
+            const tagUnion = new Set([...tags1Set, ...tags2Set]);
+            const tagSimilarity = tagUnion.size > 0 ? tagIntersection.size / tagUnion.size : 0;
+            score += tagSimilarity * SIMILARITY_WEIGHTS.TAGS;
+            factors += SIMILARITY_WEIGHTS.TAGS;
+        }
+        return factors > 0 ? score / factors : 0;
+    }
+    /**
+     * Find duplicate entities in the graph based on similarity threshold.
+     *
+     * OPTIMIZED: Uses bucketing strategies to reduce O(n²) comparisons:
+     * 1. Buckets entities by entityType (only compare same types)
+     * 2. Within each type, buckets by name prefix (first 2 chars normalized)
+     * 3. Only compares entities within same or adjacent buckets
+     *
+     * Complexity: O(n·k) where k is average bucket size (typically << n)
+     *
+     * @param threshold - Similarity threshold (0.0 to 1.0), default DEFAULT_DUPLICATE_THRESHOLD
+     * @returns Array of duplicate groups (each group has similar entities)
+     */
+    async findDuplicates(threshold = DEFAULT_DUPLICATE_THRESHOLD) {
+        const graph = await this.storage.loadGraph();
+        const duplicateGroups = [];
+        const processed = new Set();
+        // Step 1: Bucket entities by type (reduces comparisons drastically)
+        const typeMap = new Map();
+        for (const entity of graph.entities) {
+            const normalizedType = entity.entityType.toLowerCase();
+            if (!typeMap.has(normalizedType)) {
+                typeMap.set(normalizedType, []);
+            }
+            typeMap.get(normalizedType).push(entity);
+        }
+        // Step 2: For each type bucket, sub-bucket by name prefix
+        for (const entities of typeMap.values()) {
+            // Skip single-entity types (no duplicates possible)
+            if (entities.length < 2)
+                continue;
+            // Create name prefix buckets (first 2 chars, normalized)
+            const prefixMap = new Map();
+            for (const entity of entities) {
+                const prefix = entity.name.toLowerCase().slice(0, 2);
+                if (!prefixMap.has(prefix)) {
+                    prefixMap.set(prefix, []);
+                }
+                prefixMap.get(prefix).push(entity);
+            }
+            // Step 3: Compare only within buckets (or adjacent buckets for fuzzy matching)
+            const prefixKeys = Array.from(prefixMap.keys()).sort();
+            for (let bucketIdx = 0; bucketIdx < prefixKeys.length; bucketIdx++) {
+                const currentPrefix = prefixKeys[bucketIdx];
+                const currentBucket = prefixMap.get(currentPrefix);
+                // Collect entities to compare: current bucket + adjacent buckets
+                const candidateEntities = [...currentBucket];
+                // Add next bucket if exists (handles fuzzy prefix matching)
+                if (bucketIdx + 1 < prefixKeys.length) {
+                    candidateEntities.push(...prefixMap.get(prefixKeys[bucketIdx + 1]));
+                }
+                // Compare entities within candidate pool
+                for (let i = 0; i < currentBucket.length; i++) {
+                    const entity1 = currentBucket[i];
+                    if (processed.has(entity1.name))
+                        continue;
+                    const group = [entity1.name];
+                    for (let j = 0; j < candidateEntities.length; j++) {
+                        const entity2 = candidateEntities[j];
+                        if (entity1.name === entity2.name || processed.has(entity2.name))
+                            continue;
+                        const similarity = this.calculateEntitySimilarity(entity1, entity2);
+                        if (similarity >= threshold) {
+                            group.push(entity2.name);
+                            processed.add(entity2.name);
+                        }
+                    }
+                    if (group.length > 1) {
+                        duplicateGroups.push(group);
+                        processed.add(entity1.name);
+                    }
+                }
+            }
+        }
+        return duplicateGroups;
+    }
+    /**
+     * Merge a group of entities into a single entity.
+     *
+     * Merging strategy:
+     * - First entity is kept (or renamed to targetName)
+     * - Observations: Union of all observations
+     * - Tags: Union of all tags
+     * - Importance: Maximum importance value
+     * - createdAt: Earliest date
+     * - lastModified: Current timestamp
+     * - Relations: Redirected to kept entity, duplicates removed
+     *
+     * @param entityNames - Names of entities to merge (first one is kept)
+     * @param targetName - Optional new name for merged entity (default: first entity name)
+     * @returns The merged entity
+     * @throws {InsufficientEntitiesError} If less than 2 entities provided
+     * @throws {EntityNotFoundError} If any entity not found
+     */
+    async mergeEntities(entityNames, targetName) {
+        if (entityNames.length < 2) {
+            throw new InsufficientEntitiesError('merging', 2, entityNames.length);
+        }
+        const graph = await this.storage.loadGraph();
+        const entitiesToMerge = entityNames.map(name => {
+            const entity = graph.entities.find(e => e.name === name);
+            if (!entity) {
+                throw new EntityNotFoundError(name);
+            }
+            return entity;
+        });
+        const keepEntity = entitiesToMerge[0];
+        const mergeEntities = entitiesToMerge.slice(1);
+        // Merge observations (unique)
+        const allObservations = new Set();
+        for (const entity of entitiesToMerge) {
+            entity.observations.forEach(obs => allObservations.add(obs));
+        }
+        keepEntity.observations = Array.from(allObservations);
+        // Merge tags (unique)
+        const allTags = new Set();
+        for (const entity of entitiesToMerge) {
+            if (entity.tags) {
+                entity.tags.forEach(tag => allTags.add(tag));
+            }
+        }
+        if (allTags.size > 0) {
+            keepEntity.tags = Array.from(allTags);
+        }
+        // Use highest importance
+        const importances = entitiesToMerge
+            .map(e => e.importance)
+            .filter(imp => imp !== undefined);
+        if (importances.length > 0) {
+            keepEntity.importance = Math.max(...importances);
+        }
+        // Use earliest createdAt
+        const createdDates = entitiesToMerge
+            .map(e => e.createdAt)
+            .filter(date => date !== undefined);
+        if (createdDates.length > 0) {
+            keepEntity.createdAt = createdDates.sort()[0];
+        }
+        // Update lastModified
+        keepEntity.lastModified = new Date().toISOString();
+        // Rename if requested
+        if (targetName && targetName !== keepEntity.name) {
+            // Update all relations pointing to old name
+            graph.relations.forEach(rel => {
+                if (rel.from === keepEntity.name)
+                    rel.from = targetName;
+                if (rel.to === keepEntity.name)
+                    rel.to = targetName;
+            });
+            keepEntity.name = targetName;
+        }
+        // Update relations from merged entities to point to kept entity
+        for (const mergeEntity of mergeEntities) {
+            graph.relations.forEach(rel => {
+                if (rel.from === mergeEntity.name)
+                    rel.from = keepEntity.name;
+                if (rel.to === mergeEntity.name)
+                    rel.to = keepEntity.name;
+            });
+        }
+        // Remove duplicate relations
+        const uniqueRelations = new Map();
+        for (const relation of graph.relations) {
+            const key = `${relation.from}|${relation.to}|${relation.relationType}`;
+            if (!uniqueRelations.has(key)) {
+                uniqueRelations.set(key, relation);
+            }
+        }
+        graph.relations = Array.from(uniqueRelations.values());
+        // Remove merged entities
+        const mergeNames = new Set(mergeEntities.map(e => e.name));
+        graph.entities = graph.entities.filter(e => !mergeNames.has(e.name));
+        await this.storage.saveGraph(graph);
+        return keepEntity;
+    }
+    /**
+     * Compress the knowledge graph by finding and merging duplicates.
+     *
+     * @param threshold - Similarity threshold for duplicate detection (0.0 to 1.0), default DEFAULT_DUPLICATE_THRESHOLD
+     * @param dryRun - If true, only report what would be compressed without applying changes
+     * @returns Compression result with statistics
+     */
+    async compressGraph(threshold = DEFAULT_DUPLICATE_THRESHOLD, dryRun = false) {
+        const initialGraph = await this.storage.loadGraph();
+        const initialSize = JSON.stringify(initialGraph).length;
+        const duplicateGroups = await this.findDuplicates(threshold);
+        const result = {
+            duplicatesFound: duplicateGroups.reduce((sum, group) => sum + group.length, 0),
+            entitiesMerged: 0,
+            observationsCompressed: 0,
+            relationsConsolidated: 0,
+            spaceFreed: 0,
+            mergedEntities: [],
+        };
+        if (dryRun) {
+            // Just report what would happen
+            for (const group of duplicateGroups) {
+                result.mergedEntities.push({
+                    kept: group[0],
+                    merged: group.slice(1),
+                });
+                result.entitiesMerged += group.length - 1;
+            }
+            return result;
+        }
+        // Actually merge duplicates
+        for (const group of duplicateGroups) {
+            try {
+                await this.mergeEntities(group);
+                result.mergedEntities.push({
+                    kept: group[0],
+                    merged: group.slice(1),
+                });
+                result.entitiesMerged += group.length - 1;
+            }
+            catch (error) {
+                // Skip groups that fail to merge
+                console.error(`Failed to merge group ${group}:`, error);
+            }
+        }
+        // Calculate space saved
+        const finalGraph = await this.storage.loadGraph();
+        const finalSize = JSON.stringify(finalGraph).length;
+        result.spaceFreed = initialSize - finalSize;
+        // Count compressed observations (approximation)
+        result.observationsCompressed = result.entitiesMerged;
+        return result;
+    }
+}

package/dist/features/ExportManager.js

@@ -0,0 +1,305 @@
+/**
+ * Export Manager
+ *
+ * Exports knowledge graphs to various formats (JSON, CSV, GraphML, GEXF, DOT, Markdown, Mermaid).
+ *
+ * @module features/ExportManager
+ */
+/**
+ * Manages knowledge graph exports to multiple formats.
+ */
+export class ExportManager {
+    /**
+     * 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 as pretty-printed JSON.
+     */
+    exportAsJson(graph) {
+        return JSON.stringify(graph, null, 2);
+    }
+    /**
+     * Export as CSV with proper escaping.
+     */
+    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;
+        };
+        // Entities section
+        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(','));
+        }
+        // Relations section
+        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');
+    }
+    /**
+     * Export as GraphML XML format.
+     */
+    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">');
+        // Nodes
+        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>');
+        }
+        // Edges
+        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');
+    }
+    /**
+     * Export as GEXF format for Gephi.
+     */
+    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');
+    }
+    /**
+     * Export as DOT format for GraphViz.
+     */
+    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');
+    }
+    /**
+     * Export as Markdown documentation.
+     */
+    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');
+    }
+    /**
+     * Export as Mermaid diagram.
+     */
+    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');
+    }
+}