server-memory-enhanced 0.2.0 → 2.1.0

package/dist/index.js

@@ -5,6 +5,9 @@ import { z } from "zod";
 import { promises as fs } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { KnowledgeGraphManager } from './lib/knowledge-graph-manager.js';
+import { EntitySchema, RelationSchema, SaveMemoryInputSchema, SaveMemoryOutputSchema, GetAnalyticsInputSchema, GetAnalyticsOutputSchema, GetObservationHistoryInputSchema, GetObservationHistoryOutputSchema } from './lib/schemas.js';
+import { handleSaveMemory } from './lib/save-memory-handler.js';
 // Define memory directory path using environment variable with fallback
 export const defaultMemoryDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'memory-data');
 export async function ensureMemoryDirectory() {
@@ -24,661 +27,56 @@ export async function ensureMemoryDirectory() {
 }
 // Initialize memory directory path (will be set during startup)
 let MEMORY_DIR_PATH;
-// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
-export class KnowledgeGraphManager {
-    memoryDirPath;
-    static NEGATION_WORDS = new Set(['not', 'no', 'never', 'neither', 'none', 'doesn\'t', 'don\'t', 'isn\'t', 'aren\'t']);
-    constructor(memoryDirPath) {
-        this.memoryDirPath = memoryDirPath;
-    }
-    getThreadFilePath(agentThreadId) {
-        return path.join(this.memoryDirPath, `thread-${agentThreadId}.jsonl`);
-    }
-    async loadGraphFromFile(filePath) {
-        try {
-            const data = await fs.readFile(filePath, "utf-8");
-            const lines = data.split("\n").filter(line => line.trim() !== "");
-            return lines.reduce((graph, line) => {
-                let item;
-                try {
-                    item = JSON.parse(line);
-                }
-                catch (parseError) {
-                    console.warn(`Skipping malformed JSON line in ${filePath} (line length: ${line.length} chars)`);
-                    return graph;
-                }
-                if (item.type === "entity") {
-                    // Validate required fields
-                    if (!item.name || !item.entityType || !Array.isArray(item.observations) ||
-                        !item.agentThreadId || !item.timestamp ||
-                        typeof item.confidence !== 'number' || typeof item.importance !== 'number') {
-                        console.warn(`Skipping entity with missing required fields in ${filePath}`);
-                        return graph;
-                    }
-                    graph.entities.push({
-                        name: item.name,
-                        entityType: item.entityType,
-                        observations: item.observations,
-                        agentThreadId: item.agentThreadId,
-                        timestamp: item.timestamp,
-                        confidence: item.confidence,
-                        importance: item.importance
-                    });
-                }
-                if (item.type === "relation") {
-                    // Validate required fields
-                    if (!item.from || !item.to || !item.relationType ||
-                        !item.agentThreadId || !item.timestamp ||
-                        typeof item.confidence !== 'number' || typeof item.importance !== 'number') {
-                        console.warn(`Skipping relation with missing required fields in ${filePath}`);
-                        return graph;
-                    }
-                    graph.relations.push({
-                        from: item.from,
-                        to: item.to,
-                        relationType: item.relationType,
-                        agentThreadId: item.agentThreadId,
-                        timestamp: item.timestamp,
-                        confidence: item.confidence,
-                        importance: item.importance
-                    });
-                }
-                return graph;
-            }, { entities: [], relations: [] });
-        }
-        catch (error) {
-            if (error instanceof Error && 'code' in error && error.code === "ENOENT") {
-                return { entities: [], relations: [] };
-            }
-            throw error;
-        }
-    }
-    async loadGraph() {
-        const files = await fs.readdir(this.memoryDirPath).catch(() => []);
-        const threadFiles = files.filter(f => f.startsWith('thread-') && f.endsWith('.jsonl'));
-        const graphs = await Promise.all(threadFiles.map(f => this.loadGraphFromFile(path.join(this.memoryDirPath, f))));
-        return graphs.reduce((acc, graph) => ({
-            entities: [...acc.entities, ...graph.entities],
-            relations: [...acc.relations, ...graph.relations]
-        }), { entities: [], relations: [] });
-    }
-    async saveGraphForThread(agentThreadId, entities, relations) {
-        const threadFilePath = this.getThreadFilePath(agentThreadId);
-        const lines = [
-            ...entities.map(e => JSON.stringify({
-                type: "entity",
-                name: e.name,
-                entityType: e.entityType,
-                observations: e.observations,
-                agentThreadId: e.agentThreadId,
-                timestamp: e.timestamp,
-                confidence: e.confidence,
-                importance: e.importance
-            })),
-            ...relations.map(r => JSON.stringify({
-                type: "relation",
-                from: r.from,
-                to: r.to,
-                relationType: r.relationType,
-                agentThreadId: r.agentThreadId,
-                timestamp: r.timestamp,
-                confidence: r.confidence,
-                importance: r.importance
-            })),
-        ];
-        // Avoid creating or keeping empty files when there is no data for this thread
-        if (lines.length === 0) {
-            try {
-                await fs.unlink(threadFilePath);
-            }
-            catch (error) {
-                // Only ignore ENOENT errors (file doesn't exist)
-                if (error instanceof Error && 'code' in error && error.code !== 'ENOENT') {
-                    console.warn(`Failed to delete empty thread file ${threadFilePath}:`, error);
-                }
-            }
-            return;
-        }
-        await fs.writeFile(threadFilePath, lines.join("\n"));
-    }
-    async saveGraph(graph) {
-        // Group entities and relations by agentThreadId
-        const threadMap = new Map();
-        for (const entity of graph.entities) {
-            if (!threadMap.has(entity.agentThreadId)) {
-                threadMap.set(entity.agentThreadId, { entities: [], relations: [] });
-            }
-            threadMap.get(entity.agentThreadId).entities.push(entity);
-        }
-        for (const relation of graph.relations) {
-            if (!threadMap.has(relation.agentThreadId)) {
-                threadMap.set(relation.agentThreadId, { entities: [], relations: [] });
-            }
-            threadMap.get(relation.agentThreadId).relations.push(relation);
-        }
-        // Save each thread's data to its own file
-        await Promise.all(Array.from(threadMap.entries()).map(([threadId, data]) => this.saveGraphForThread(threadId, data.entities, data.relations)));
-        // Clean up stale thread files that no longer have data
-        try {
-            const files = await fs.readdir(this.memoryDirPath).catch(() => []);
-            const threadFiles = files.filter(f => f.startsWith('thread-') && f.endsWith('.jsonl'));
-            await Promise.all(threadFiles.map(async (fileName) => {
-                // Extract threadId from filename: thread-{agentThreadId}.jsonl
-                const match = fileName.match(/^thread-(.+)\.jsonl$/);
-                if (match) {
-                    const threadId = match[1];
-                    if (!threadMap.has(threadId)) {
-                        const filePath = path.join(this.memoryDirPath, fileName);
-                        try {
-                            await fs.unlink(filePath);
-                        }
-                        catch (error) {
-                            // Only log non-ENOENT errors
-                            if (error instanceof Error && 'code' in error && error.code !== 'ENOENT') {
-                                console.warn(`Failed to delete stale thread file ${filePath}:`, error);
-                            }
-                        }
-                    }
-                }
-            }));
-        }
-        catch (error) {
-            // Best-effort cleanup: log but don't fail the save operation
-            console.warn('Failed to clean up stale thread files:', error);
-        }
-    }
-    async createEntities(entities) {
-        const graph = await this.loadGraph();
-        // Entity names are globally unique across all threads in the collaborative knowledge graph
-        // This prevents duplicate entities while allowing multiple threads to contribute to the same entity
-        const newEntities = entities.filter(e => !graph.entities.some(existingEntity => existingEntity.name === e.name));
-        graph.entities.push(...newEntities);
-        await this.saveGraph(graph);
-        return newEntities;
-    }
-    async createRelations(relations) {
-        const graph = await this.loadGraph();
-        // Validate that referenced entities exist
-        const entityNames = new Set(graph.entities.map(e => e.name));
-        const validRelations = relations.filter(r => {
-            if (!entityNames.has(r.from) || !entityNames.has(r.to)) {
-                console.warn(`Skipping relation ${r.from} -> ${r.to}: one or both entities do not exist`);
-                return false;
-            }
-            return true;
-        });
-        // Relations are globally unique by (from, to, relationType) across all threads
-        // This enables multiple threads to collaboratively build the knowledge graph
-        const newRelations = validRelations.filter(r => !graph.relations.some(existingRelation => existingRelation.from === r.from &&
-            existingRelation.to === r.to &&
-            existingRelation.relationType === r.relationType));
-        graph.relations.push(...newRelations);
-        await this.saveGraph(graph);
-        return newRelations;
-    }
-    async addObservations(observations) {
-        const graph = await this.loadGraph();
-        const results = observations.map(o => {
-            const entity = graph.entities.find(e => e.name === o.entityName);
-            if (!entity) {
-                throw new Error(`Entity with name ${o.entityName} not found`);
-            }
-            const newObservations = o.contents.filter(content => !entity.observations.includes(content));
-            entity.observations.push(...newObservations);
-            // Update metadata based on this operation, but keep original agentThreadId
-            // to maintain thread file consistency and avoid orphaned data
-            entity.timestamp = o.timestamp;
-            entity.confidence = o.confidence;
-            entity.importance = o.importance;
-            return { entityName: o.entityName, addedObservations: newObservations };
-        });
-        await this.saveGraph(graph);
-        return results;
-    }
-    async deleteEntities(entityNames) {
-        const graph = await this.loadGraph();
-        graph.entities = graph.entities.filter(e => !entityNames.includes(e.name));
-        graph.relations = graph.relations.filter(r => !entityNames.includes(r.from) && !entityNames.includes(r.to));
-        await this.saveGraph(graph);
-    }
-    async deleteObservations(deletions) {
-        const graph = await this.loadGraph();
-        deletions.forEach(d => {
-            const entity = graph.entities.find(e => e.name === d.entityName);
-            if (entity) {
-                entity.observations = entity.observations.filter(o => !d.observations.includes(o));
-            }
-        });
-        await this.saveGraph(graph);
-    }
-    async deleteRelations(relations) {
-        const graph = await this.loadGraph();
-        // Delete relations globally across all threads by matching (from, to, relationType)
-        // In a collaborative knowledge graph, deletions affect all threads
-        graph.relations = graph.relations.filter(r => !relations.some(delRelation => r.from === delRelation.from &&
-            r.to === delRelation.to &&
-            r.relationType === delRelation.relationType));
-        await this.saveGraph(graph);
-    }
-    async readGraph() {
-        return this.loadGraph();
-    }
-    async searchNodes(query) {
-        const graph = await this.loadGraph();
-        // Filter entities
-        const filteredEntities = graph.entities.filter(e => e.name.toLowerCase().includes(query.toLowerCase()) ||
-            e.entityType.toLowerCase().includes(query.toLowerCase()) ||
-            e.observations.some(o => o.toLowerCase().includes(query.toLowerCase())));
-        // Create a Set of filtered entity names for quick lookup
-        const filteredEntityNames = new Set(filteredEntities.map(e => e.name));
-        // Filter relations to only include those between filtered entities
-        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
-        const filteredGraph = {
-            entities: filteredEntities,
-            relations: filteredRelations,
-        };
-        return filteredGraph;
-    }
-    async openNodes(names) {
-        const graph = await this.loadGraph();
-        // Filter entities
-        const filteredEntities = graph.entities.filter(e => names.includes(e.name));
-        // Create a Set of filtered entity names for quick lookup
-        const filteredEntityNames = new Set(filteredEntities.map(e => e.name));
-        // Filter relations to only include those between filtered entities
-        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
-        const filteredGraph = {
-            entities: filteredEntities,
-            relations: filteredRelations,
-        };
-        return filteredGraph;
-    }
-    async queryNodes(filters) {
-        const graph = await this.loadGraph();
-        // If no filters provided, return entire graph
-        if (!filters) {
-            return graph;
-        }
-        // Apply filters to entities
-        const filteredEntities = graph.entities.filter(e => {
-            // Timestamp range filter
-            if (filters.timestampStart && e.timestamp < filters.timestampStart)
-                return false;
-            if (filters.timestampEnd && e.timestamp > filters.timestampEnd)
-                return false;
-            // Confidence range filter
-            if (filters.confidenceMin !== undefined && e.confidence < filters.confidenceMin)
-                return false;
-            if (filters.confidenceMax !== undefined && e.confidence > filters.confidenceMax)
-                return false;
-            // Importance range filter
-            if (filters.importanceMin !== undefined && e.importance < filters.importanceMin)
-                return false;
-            if (filters.importanceMax !== undefined && e.importance > filters.importanceMax)
-                return false;
-            return true;
-        });
-        // Create a Set of filtered entity names for quick lookup
-        const filteredEntityNames = new Set(filteredEntities.map(e => e.name));
-        // Apply filters to relations (and ensure they connect filtered entities)
-        const filteredRelations = graph.relations.filter(r => {
-            // Must connect filtered entities
-            if (!filteredEntityNames.has(r.from) || !filteredEntityNames.has(r.to))
-                return false;
-            // Timestamp range filter
-            if (filters.timestampStart && r.timestamp < filters.timestampStart)
-                return false;
-            if (filters.timestampEnd && r.timestamp > filters.timestampEnd)
-                return false;
-            // Confidence range filter
-            if (filters.confidenceMin !== undefined && r.confidence < filters.confidenceMin)
-                return false;
-            if (filters.confidenceMax !== undefined && r.confidence > filters.confidenceMax)
-                return false;
-            // Importance range filter
-            if (filters.importanceMin !== undefined && r.importance < filters.importanceMin)
-                return false;
-            if (filters.importanceMax !== undefined && r.importance > filters.importanceMax)
-                return false;
-            return true;
-        });
-        return {
-            entities: filteredEntities,
-            relations: filteredRelations,
-        };
-    }
-    // Enhancement 1: Memory Statistics & Insights
-    async getMemoryStats() {
-        const graph = await this.loadGraph();
-        // Count entity types
-        const entityTypes = {};
-        graph.entities.forEach(e => {
-            entityTypes[e.entityType] = (entityTypes[e.entityType] || 0) + 1;
-        });
-        // Calculate averages
-        const avgConfidence = graph.entities.length > 0
-            ? graph.entities.reduce((sum, e) => sum + e.confidence, 0) / graph.entities.length
-            : 0;
-        const avgImportance = graph.entities.length > 0
-            ? graph.entities.reduce((sum, e) => sum + e.importance, 0) / graph.entities.length
-            : 0;
-        // Count unique threads
-        const threads = new Set([
-            ...graph.entities.map(e => e.agentThreadId),
-            ...graph.relations.map(r => r.agentThreadId)
-        ]);
-        // Recent activity (last 7 days, grouped by day)
-        const now = new Date();
-        const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
-        const recentEntities = graph.entities.filter(e => new Date(e.timestamp) >= sevenDaysAgo);
-        // Group by day
-        const activityByDay = {};
-        recentEntities.forEach(e => {
-            const day = e.timestamp.substring(0, 10); // YYYY-MM-DD
-            activityByDay[day] = (activityByDay[day] || 0) + 1;
-        });
-        const recentActivity = Object.entries(activityByDay)
-            .map(([timestamp, entityCount]) => ({ timestamp, entityCount }))
-            .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
-        return {
-            entityCount: graph.entities.length,
-            relationCount: graph.relations.length,
-            threadCount: threads.size,
-            entityTypes,
-            avgConfidence,
-            avgImportance,
-            recentActivity
-        };
-    }
-    // Enhancement 2: Get recent changes
-    async getRecentChanges(since) {
-        const graph = await this.loadGraph();
-        const sinceDate = new Date(since);
-        // Only return entities and relations that were actually modified since the specified time
-        const recentEntities = graph.entities.filter(e => new Date(e.timestamp) >= sinceDate);
-        const recentEntityNames = new Set(recentEntities.map(e => e.name));
-        // Only include relations that are recent themselves
-        const recentRelations = graph.relations.filter(r => new Date(r.timestamp) >= sinceDate);
-        return {
-            entities: recentEntities,
-            relations: recentRelations
-        };
-    }
-    // Enhancement 3: Relationship path finding
-    async findRelationPath(from, to, maxDepth = 5) {
-        const graph = await this.loadGraph();
-        if (from === to) {
-            return { found: true, path: [from], relations: [] };
-        }
-        // BFS to find shortest path
-        const queue = [
-            { entity: from, path: [from], relations: [] }
-        ];
-        const visited = new Set([from]);
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (current.path.length > maxDepth) {
-                continue;
-            }
-            // Find all relations connected to current entity (both outgoing and incoming for bidirectional search)
-            const outgoing = graph.relations.filter(r => r.from === current.entity);
-            const incoming = graph.relations.filter(r => r.to === current.entity);
-            // Check outgoing relations
-            for (const rel of outgoing) {
-                if (rel.to === to) {
-                    return {
-                        found: true,
-                        path: [...current.path, rel.to],
-                        relations: [...current.relations, rel]
-                    };
-                }
-                if (!visited.has(rel.to)) {
-                    visited.add(rel.to);
-                    queue.push({
-                        entity: rel.to,
-                        path: [...current.path, rel.to],
-                        relations: [...current.relations, rel]
-                    });
-                }
-            }
-            // Check incoming relations (traverse backwards)
-            for (const rel of incoming) {
-                if (rel.from === to) {
-                    return {
-                        found: true,
-                        path: [...current.path, rel.from],
-                        relations: [...current.relations, rel]
-                    };
-                }
-                if (!visited.has(rel.from)) {
-                    visited.add(rel.from);
-                    queue.push({
-                        entity: rel.from,
-                        path: [...current.path, rel.from],
-                        relations: [...current.relations, rel]
-                    });
-                }
-            }
-        }
-        return { found: false, path: [], relations: [] };
-    }
-    // Enhancement 4: Detect conflicting observations
-    async detectConflicts() {
-        const graph = await this.loadGraph();
-        const conflicts = [];
-        for (const entity of graph.entities) {
-            const entityConflicts = [];
-            for (let i = 0; i < entity.observations.length; i++) {
-                for (let j = i + 1; j < entity.observations.length; j++) {
-                    const obs1 = entity.observations[i].toLowerCase();
-                    const obs2 = entity.observations[j].toLowerCase();
-                    // Check for negation patterns
-                    const obs1HasNegation = Array.from(KnowledgeGraphManager.NEGATION_WORDS).some(word => obs1.includes(word));
-                    const obs2HasNegation = Array.from(KnowledgeGraphManager.NEGATION_WORDS).some(word => obs2.includes(word));
-                    // If one has negation and they share key words, might be a conflict
-                    if (obs1HasNegation !== obs2HasNegation) {
-                        const words1 = obs1.split(/\s+/).filter(w => w.length > 3);
-                        const words2Set = new Set(obs2.split(/\s+/).filter(w => w.length > 3));
-                        const commonWords = words1.filter(w => words2Set.has(w) && !KnowledgeGraphManager.NEGATION_WORDS.has(w));
-                        if (commonWords.length >= 2) {
-                            entityConflicts.push({
-                                obs1: entity.observations[i],
-                                obs2: entity.observations[j],
-                                reason: 'Potential contradiction with negation'
-                            });
-                        }
-                    }
-                }
-            }
-            if (entityConflicts.length > 0) {
-                conflicts.push({ entityName: entity.name, conflicts: entityConflicts });
-            }
-        }
-        return conflicts;
-    }
-    // Enhancement 5: Memory pruning
-    async pruneMemory(options) {
-        const graph = await this.loadGraph();
-        const initialEntityCount = graph.entities.length;
-        const initialRelationCount = graph.relations.length;
-        // Filter entities to remove
-        let entitiesToKeep = graph.entities;
-        if (options.olderThan) {
-            const cutoffDate = new Date(options.olderThan);
-            entitiesToKeep = entitiesToKeep.filter(e => new Date(e.timestamp) >= cutoffDate);
-        }
-        if (options.importanceLessThan !== undefined) {
-            entitiesToKeep = entitiesToKeep.filter(e => e.importance >= options.importanceLessThan);
-        }
-        // Ensure we keep minimum entities
-        // If keepMinEntities is set and we need more entities, take from the already-filtered set
-        // sorted by importance and recency
-        if (options.keepMinEntities && entitiesToKeep.length < options.keepMinEntities) {
-            // Sort the filtered entities by importance and timestamp, keep the most important and recent
-            const sorted = [...entitiesToKeep].sort((a, b) => {
-                if (a.importance !== b.importance)
-                    return b.importance - a.importance;
-                return b.timestamp.localeCompare(a.timestamp);
-            });
-            // If we still don't have enough, we keep what we have
-            entitiesToKeep = sorted.slice(0, Math.min(options.keepMinEntities, sorted.length));
-        }
-        const keptEntityNames = new Set(entitiesToKeep.map(e => e.name));
-        // Remove relations that reference removed entities
-        const relationsToKeep = graph.relations.filter(r => keptEntityNames.has(r.from) && keptEntityNames.has(r.to));
-        graph.entities = entitiesToKeep;
-        graph.relations = relationsToKeep;
-        await this.saveGraph(graph);
-        return {
-            removedEntities: initialEntityCount - entitiesToKeep.length,
-            removedRelations: initialRelationCount - relationsToKeep.length
-        };
-    }
-    // Enhancement 6: Batch operations
-    async bulkUpdate(updates) {
-        const graph = await this.loadGraph();
-        let updated = 0;
-        const notFound = [];
-        for (const update of updates) {
-            const entity = graph.entities.find(e => e.name === update.entityName);
-            if (!entity) {
-                notFound.push(update.entityName);
-                continue;
-            }
-            if (update.confidence !== undefined) {
-                entity.confidence = update.confidence;
-            }
-            if (update.importance !== undefined) {
-                entity.importance = update.importance;
-            }
-            if (update.addObservations) {
-                const newObs = update.addObservations.filter(obs => !entity.observations.includes(obs));
-                entity.observations.push(...newObs);
-            }
-            entity.timestamp = new Date().toISOString();
-            updated++;
-        }
-        await this.saveGraph(graph);
-        return { updated, notFound };
-    }
-    // Enhancement 7: Flag for review (Human-in-the-Loop)
-    async flagForReview(entityName, reason, reviewer) {
-        const graph = await this.loadGraph();
-        const entity = graph.entities.find(e => e.name === entityName);
-        if (!entity) {
-            throw new Error(`Entity with name ${entityName} not found`);
-        }
-        // Add a special observation to mark for review
-        const flagObservation = `[FLAGGED FOR REVIEW: ${reason}${reviewer ? ` - Reviewer: ${reviewer}` : ''}]`;
-        if (!entity.observations.includes(flagObservation)) {
-            entity.observations.push(flagObservation);
-            entity.timestamp = new Date().toISOString();
-            await this.saveGraph(graph);
-        }
-    }
-    // Enhancement 8: Get entities flagged for review
-    async getFlaggedEntities() {
-        const graph = await this.loadGraph();
-        return graph.entities.filter(e => e.observations.some(obs => obs.includes('[FLAGGED FOR REVIEW:')));
-    }
-    // Enhancement 9: Get context (entities related to a topic/entity)
-    async getContext(entityNames, depth = 1) {
-        const graph = await this.loadGraph();
-        const contextEntityNames = new Set(entityNames);
-        // Expand to include related entities up to specified depth
-        for (let d = 0; d < depth; d++) {
-            const currentEntities = Array.from(contextEntityNames);
-            for (const entityName of currentEntities) {
-                // Find all relations involving this entity
-                const relatedRelations = graph.relations.filter(r => r.from === entityName || r.to === entityName);
-                // Add related entities
-                relatedRelations.forEach(r => {
-                    contextEntityNames.add(r.from);
-                    contextEntityNames.add(r.to);
-                });
-            }
-        }
-        // Get all entities and relations in context
-        const contextEntities = graph.entities.filter(e => contextEntityNames.has(e.name));
-        const contextRelations = graph.relations.filter(r => contextEntityNames.has(r.from) && contextEntityNames.has(r.to));
-        return {
-            entities: contextEntities,
-            relations: contextRelations
-        };
-    }
-    // Enhancement 10: List conversations (agent threads)
-    async listConversations() {
-        const graph = await this.loadGraph();
-        // Group data by agent thread
-        const threadMap = new Map();
-        // Collect entities by thread
-        for (const entity of graph.entities) {
-            if (!threadMap.has(entity.agentThreadId)) {
-                threadMap.set(entity.agentThreadId, { entities: [], relations: [], timestamps: [] });
-            }
-            const threadData = threadMap.get(entity.agentThreadId);
-            threadData.entities.push(entity);
-            threadData.timestamps.push(entity.timestamp);
-        }
-        // Collect relations by thread
-        for (const relation of graph.relations) {
-            if (!threadMap.has(relation.agentThreadId)) {
-                threadMap.set(relation.agentThreadId, { entities: [], relations: [], timestamps: [] });
-            }
-            const threadData = threadMap.get(relation.agentThreadId);
-            threadData.relations.push(relation);
-            threadData.timestamps.push(relation.timestamp);
-        }
-        // Build conversation summaries
-        const conversations = Array.from(threadMap.entries()).map(([agentThreadId, data]) => {
-            const timestamps = data.timestamps.sort((a, b) => a.localeCompare(b));
-            return {
-                agentThreadId,
-                entityCount: data.entities.length,
-                relationCount: data.relations.length,
-                firstCreated: timestamps[0] || '',
-                lastUpdated: timestamps[timestamps.length - 1] || ''
-            };
-        });
-        // Sort by last updated (most recent first)
-        conversations.sort((a, b) => b.lastUpdated.localeCompare(a.lastUpdated));
-        return { conversations };
-    }
-}
+export { KnowledgeGraphManager } from './lib/knowledge-graph-manager.js';
+export { JsonlStorageAdapter } from './lib/jsonl-storage-adapter.js';
+export { Neo4jStorageAdapter } from './lib/neo4j-storage-adapter.js';
 let knowledgeGraphManager;
 // Zod schemas for enhanced entities and relations
-const EntitySchema = z.object({
-    name: z.string().describe("The name of the entity"),
-    entityType: z.string().describe("The type of the entity"),
-    observations: z.array(z.string()).describe("An array of observation contents associated with the entity"),
-    agentThreadId: z.string().describe("The agent thread ID that created this entity"),
-    timestamp: z.string().describe("ISO 8601 timestamp of when the entity was created"),
-    confidence: z.number().min(0).max(1).describe("Confidence coefficient from 0 to 1"),
-    importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)")
-});
-const RelationSchema = z.object({
-    from: z.string().describe("The name of the entity where the relation starts"),
-    to: z.string().describe("The name of the entity where the relation ends"),
-    relationType: z.string().describe("The type of the relation"),
-    agentThreadId: z.string().describe("The agent thread ID that created this relation"),
-    timestamp: z.string().describe("ISO 8601 timestamp of when the relation was created"),
-    confidence: z.number().min(0).max(1).describe("Confidence coefficient from 0 to 1"),
-    importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)")
-});
+const EntitySchemaCompat = EntitySchema;
+const RelationSchemaCompat = RelationSchema;
 // The server instance and tools exposed to Claude
 const server = new McpServer({
     name: "memory-enhanced-server",
     version: "0.2.0",
 });
-// Register create_entities tool
+// Register NEW save_memory tool (Section 1 of spec - Unified Tool)
+server.registerTool("save_memory", {
+    title: "Save Memory",
+    description: "Save entities and their relations to memory graph atomically. RULES: 1) Each observation max 150 chars (atomic facts only). 2) Each entity MUST have at least 1 relation. This is the recommended way to create entities and relations.",
+    inputSchema: SaveMemoryInputSchema,
+    outputSchema: SaveMemoryOutputSchema
+}, async (input) => {
+    const result = await handleSaveMemory(input, (entities) => knowledgeGraphManager.createEntities(entities), (relations) => knowledgeGraphManager.createRelations(relations));
+    if (result.success) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `✓ Successfully saved ${result.created.entities} entities and ${result.created.relations} relations.\n` +
+                        `Quality score: ${(result.quality_score * 100).toFixed(1)}%\n` +
+                        (result.warnings.length > 0 ? `\nWarnings:\n${result.warnings.join('\n')}` : '')
+                }],
+            structuredContent: result
+        };
+    }
+    else {
+        return {
+            content: [{
+                    type: "text",
+                    text: `✗ Validation failed:\n${result.validation_errors?.join('\n')}`
+                }],
+            structuredContent: result,
+            isError: true
+        };
+    }
+});
 server.registerTool("create_entities", {
     title: "Create Entities",
     description: "Create multiple new entities in the knowledge graph with metadata (agent thread ID, timestamp, confidence, importance)",
     inputSchema: {
-        entities: z.array(EntitySchema)
+        entities: z.array(EntitySchemaCompat)
     },
     outputSchema: {
-        entities: z.array(EntitySchema)
+        entities: z.array(EntitySchemaCompat)
     }
 }, async ({ entities }) => {
     const result = await knowledgeGraphManager.createEntities(entities);
@@ -692,10 +90,10 @@ server.registerTool("create_relations", {
     title: "Create Relations",
     description: "Create multiple new relations between entities in the knowledge graph with metadata (agent thread ID, timestamp, confidence, importance). Relations should be in active voice",
     inputSchema: {
-        relations: z.array(RelationSchema)
+        relations: z.array(RelationSchemaCompat)
     },
     outputSchema: {
-        relations: z.array(RelationSchema)
+        relations: z.array(RelationSchemaCompat)
     }
 }, async ({ relations }) => {
     const result = await knowledgeGraphManager.createRelations(relations);
@@ -775,7 +173,7 @@ server.registerTool("delete_relations", {
     title: "Delete Relations",
     description: "Delete multiple relations from the knowledge graph",
     inputSchema: {
-        relations: z.array(RelationSchema).describe("An array of relations to delete")
+        relations: z.array(RelationSchemaCompat).describe("An array of relations to delete")
     },
     outputSchema: {
         success: z.boolean(),
@@ -794,8 +192,8 @@ server.registerTool("read_graph", {
     description: "Read the entire knowledge graph",
     inputSchema: {},
     outputSchema: {
-        entities: z.array(EntitySchema),
-        relations: z.array(RelationSchema)
+        entities: z.array(EntitySchemaCompat),
+        relations: z.array(RelationSchemaCompat)
     }
 }, async () => {
     const graph = await knowledgeGraphManager.readGraph();
@@ -812,8 +210,8 @@ server.registerTool("search_nodes", {
         query: z.string().describe("The search query to match against entity names, types, and observation content")
     },
     outputSchema: {
-        entities: z.array(EntitySchema),
-        relations: z.array(RelationSchema)
+        entities: z.array(EntitySchemaCompat),
+        relations: z.array(RelationSchemaCompat)
     }
 }, async ({ query }) => {
     const graph = await knowledgeGraphManager.searchNodes(query);
@@ -830,8 +228,8 @@ server.registerTool("open_nodes", {
         names: z.array(z.string()).describe("An array of entity names to retrieve")
     },
     outputSchema: {
-        entities: z.array(EntitySchema),
-        relations: z.array(RelationSchema)
+        entities: z.array(EntitySchemaCompat),
+        relations: z.array(RelationSchemaCompat)
     }
 }, async ({ names }) => {
     const graph = await knowledgeGraphManager.openNodes(names);
@@ -853,8 +251,8 @@ server.registerTool("query_nodes", {
         importanceMax: z.number().min(0).max(1).optional().describe("Maximum importance value (0-1)")
     },
     outputSchema: {
-        entities: z.array(EntitySchema),
-        relations: z.array(RelationSchema)
+        entities: z.array(EntitySchemaCompat),
+        relations: z.array(RelationSchemaCompat)
     }
 }, async (filters) => {
     const graph = await knowledgeGraphManager.queryNodes(filters);
@@ -895,8 +293,8 @@ server.registerTool("get_recent_changes", {
         since: z.string().describe("ISO 8601 timestamp - return changes since this time")
     },
     outputSchema: {
-        entities: z.array(EntitySchema),
-        relations: z.array(RelationSchema)
+        entities: z.array(EntitySchemaCompat),
+        relations: z.array(RelationSchemaCompat)
     }
 }, async ({ since }) => {
     const changes = await knowledgeGraphManager.getRecentChanges(since);
@@ -917,7 +315,7 @@ server.registerTool("find_relation_path", {
     outputSchema: {
         found: z.boolean(),
         path: z.array(z.string()),
-        relations: z.array(RelationSchema)
+        relations: z.array(RelationSchemaCompat)
     }
 }, async ({ from, to, maxDepth }) => {
     const result = await knowledgeGraphManager.findRelationPath(from, to, maxDepth || 5);
@@ -1017,7 +415,7 @@ server.registerTool("get_flagged_entities", {
     description: "Retrieve all entities that have been flagged for human review",
     inputSchema: {},
     outputSchema: {
-        entities: z.array(EntitySchema)
+        entities: z.array(EntitySchemaCompat)
     }
 }, async () => {
     const entities = await knowledgeGraphManager.getFlaggedEntities();
@@ -1035,8 +433,8 @@ server.registerTool("get_context", {
         depth: z.number().optional().default(1).describe("How many relationship hops to include (default: 1)")
     },
     outputSchema: {
-        entities: z.array(EntitySchema),
-        relations: z.array(RelationSchema)
+        entities: z.array(EntitySchemaCompat),
+        relations: z.array(RelationSchemaCompat)
     }
 }, async ({ entityNames, depth }) => {
     const context = await knowledgeGraphManager.getContext(entityNames, depth || 1);
@@ -1066,6 +464,32 @@ server.registerTool("list_conversations", {
         structuredContent: result
     };
 });
+// Register get_analytics tool
+server.registerTool("get_analytics", {
+    title: "Get Analytics",
+    description: "Get analytics for a specific thread with 4 core metrics: recent changes, top important entities, most connected entities, and orphaned entities",
+    inputSchema: GetAnalyticsInputSchema,
+    outputSchema: GetAnalyticsOutputSchema
+}, async (input) => {
+    const result = await knowledgeGraphManager.getAnalytics(input.threadId);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result
+    };
+});
+// Register get_observation_history tool
+server.registerTool("get_observation_history", {
+    title: "Get Observation History",
+    description: "Retrieve the full version chain for a specific observation, showing how it evolved over time",
+    inputSchema: GetObservationHistoryInputSchema,
+    outputSchema: GetObservationHistoryOutputSchema
+}, async (input) => {
+    const result = await knowledgeGraphManager.getObservationHistory(input.entityName, input.observationId);
+    return {
+        content: [{ type: "text", text: JSON.stringify({ history: result }, null, 2) }],
+        structuredContent: { history: result }
+    };
+});
 async function main() {
     // Initialize memory directory path
     MEMORY_DIR_PATH = await ensureMemoryDirectory();