server-memory-enhanced 2.0.0 → 2.1.0

package/dist/index.js

@@ -28,6 +28,8 @@ export async function ensureMemoryDirectory() {
 // Initialize memory directory path (will be set during startup)
 let MEMORY_DIR_PATH;
 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 EntitySchemaCompat = EntitySchema;

package/dist/lib/jsonl-storage-adapter.js

@@ -0,0 +1,315 @@
+/**
+ * JSONL Storage Adapter - implements file-based storage using JSON Lines format
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+// Constants for file naming and types
+const THREAD_FILE_PREFIX = 'thread-';
+const THREAD_FILE_EXTENSION = '.jsonl';
+const ENTITY_TYPE = 'entity';
+const RELATION_TYPE = 'relation';
+const FILE_NOT_FOUND_ERROR = 'ENOENT';
+/**
+ * Type guard to check if an error is a FileSystemError
+ */
+function isFileSystemError(error) {
+    return error instanceof Error && 'code' in error;
+}
+/**
+ * Check if a string field is valid (non-empty after trimming)
+ */
+function isValidString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * JSONL-based storage adapter for the knowledge graph
+ * Stores data in thread-specific JSONL files
+ *
+ * Responsibilities:
+ * - File I/O operations for JSONL format
+ * - Thread-based data organization
+ * - Data serialization/deserialization
+ */
+export class JsonlStorageAdapter {
+    memoryDirPath;
+    constructor(memoryDirPath) {
+        this.memoryDirPath = memoryDirPath;
+    }
+    /**
+     * Get the file path for a specific thread
+     */
+    getThreadFilePath(agentThreadId) {
+        return path.join(this.memoryDirPath, `${THREAD_FILE_PREFIX}${agentThreadId}${THREAD_FILE_EXTENSION}`);
+    }
+    /**
+     * Check if an item is a valid entity
+     */
+    isValidEntity(item) {
+        return item.type === ENTITY_TYPE &&
+            isValidString(item.name) &&
+            isValidString(item.entityType) &&
+            Array.isArray(item.observations) &&
+            isValidString(item.agentThreadId) &&
+            isValidString(item.timestamp) &&
+            typeof item.confidence === 'number' &&
+            typeof item.importance === 'number';
+    }
+    /**
+     * Check if an item is a valid relation
+     */
+    isValidRelation(item) {
+        return item.type === RELATION_TYPE &&
+            isValidString(item.from) &&
+            isValidString(item.to) &&
+            isValidString(item.relationType) &&
+            isValidString(item.agentThreadId) &&
+            isValidString(item.timestamp) &&
+            typeof item.confidence === 'number' &&
+            typeof item.importance === 'number';
+    }
+    /**
+     * Parse and validate a single JSONL line
+     */
+    parseLine(line, filePath) {
+        try {
+            return JSON.parse(line);
+        }
+        catch (parseError) {
+            console.warn(`Skipping malformed JSON line in ${filePath} (line length: ${line.length} chars)`);
+            return null;
+        }
+    }
+    /**
+     * Convert JSONL item to Entity
+     */
+    toEntity(item) {
+        return {
+            name: item.name,
+            entityType: item.entityType,
+            observations: item.observations,
+            agentThreadId: item.agentThreadId,
+            timestamp: item.timestamp,
+            confidence: item.confidence,
+            importance: item.importance
+        };
+    }
+    /**
+     * Convert JSONL item to Relation
+     */
+    toRelation(item) {
+        return {
+            from: item.from,
+            to: item.to,
+            relationType: item.relationType,
+            agentThreadId: item.agentThreadId,
+            timestamp: item.timestamp,
+            confidence: item.confidence,
+            importance: item.importance
+        };
+    }
+    /**
+     * Process a single JSONL item and add to graph
+     */
+    processItem(item, graph, filePath) {
+        if (!item) {
+            return;
+        }
+        if (this.isValidEntity(item)) {
+            graph.entities.push(this.toEntity(item));
+        }
+        else if (this.isValidRelation(item)) {
+            graph.relations.push(this.toRelation(item));
+        }
+        else if (item.type === ENTITY_TYPE || item.type === RELATION_TYPE) {
+            console.warn(`Skipping ${item.type} with missing required fields in ${filePath}`);
+        }
+    }
+    /**
+     * Serialize an entity to JSONL format
+     */
+    serializeEntity(entity) {
+        return JSON.stringify({
+            type: ENTITY_TYPE,
+            name: entity.name,
+            entityType: entity.entityType,
+            observations: entity.observations,
+            agentThreadId: entity.agentThreadId,
+            timestamp: entity.timestamp,
+            confidence: entity.confidence,
+            importance: entity.importance
+        });
+    }
+    /**
+     * Serialize a relation to JSONL format
+     */
+    serializeRelation(relation) {
+        return JSON.stringify({
+            type: RELATION_TYPE,
+            from: relation.from,
+            to: relation.to,
+            relationType: relation.relationType,
+            agentThreadId: relation.agentThreadId,
+            timestamp: relation.timestamp,
+            confidence: relation.confidence,
+            importance: relation.importance
+        });
+    }
+    /**
+     * Get or create thread data in the map
+     */
+    getOrCreateThreadData(threadMap, threadId) {
+        let threadData = threadMap.get(threadId);
+        if (!threadData) {
+            threadData = { entities: [], relations: [] };
+            threadMap.set(threadId, threadData);
+        }
+        return threadData;
+    }
+    /**
+     * Check if error is a file not found error
+     */
+    isFileNotFoundError(error) {
+        return isFileSystemError(error) && error.code === FILE_NOT_FOUND_ERROR;
+    }
+    /**
+     * Extract thread ID from filename
+     */
+    extractThreadId(fileName) {
+        const match = fileName.match(new RegExp(`^${THREAD_FILE_PREFIX}(.+)${THREAD_FILE_EXTENSION}$`));
+        return match ? match[1] : null;
+    }
+    /**
+     * Load graph data from a single JSONL file
+     */
+    async loadGraphFromFile(filePath) {
+        try {
+            const data = await fs.readFile(filePath, "utf-8");
+            const lines = data.split("\n").filter(line => line.trim() !== "");
+            const graph = { entities: [], relations: [] };
+            for (const line of lines) {
+                const item = this.parseLine(line, filePath);
+                this.processItem(item, graph, filePath);
+            }
+            return graph;
+        }
+        catch (error) {
+            if (this.isFileNotFoundError(error)) {
+                return { entities: [], relations: [] };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get all thread file names in the memory directory
+     */
+    async getThreadFileNames() {
+        const files = await fs.readdir(this.memoryDirPath).catch(() => []);
+        return files.filter(f => f.startsWith(THREAD_FILE_PREFIX) && f.endsWith(THREAD_FILE_EXTENSION));
+    }
+    /**
+     * Merge multiple graphs into one
+     */
+    mergeGraphs(graphs) {
+        return graphs.reduce((acc, graph) => ({
+            entities: [...acc.entities, ...graph.entities],
+            relations: [...acc.relations, ...graph.relations]
+        }), { entities: [], relations: [] });
+    }
+    /**
+     * Load the complete knowledge graph from all thread files
+     */
+    async loadGraph() {
+        const threadFiles = await this.getThreadFileNames();
+        const graphs = await Promise.all(threadFiles.map(f => this.loadGraphFromFile(path.join(this.memoryDirPath, f))));
+        return this.mergeGraphs(graphs);
+    }
+    /**
+     * Delete empty thread file if it exists
+     */
+    async deleteThreadFileIfExists(threadFilePath) {
+        try {
+            await fs.unlink(threadFilePath);
+        }
+        catch (error) {
+            if (!this.isFileNotFoundError(error)) {
+                console.warn(`Failed to delete empty thread file ${threadFilePath}:`, error);
+            }
+        }
+    }
+    /**
+     * Serialize thread data to JSONL lines
+     */
+    serializeThreadData(threadData) {
+        return [
+            ...threadData.entities.map(e => this.serializeEntity(e)),
+            ...threadData.relations.map(r => this.serializeRelation(r))
+        ];
+    }
+    /**
+     * Save data for a specific thread
+     */
+    async saveGraphForThread(agentThreadId, threadData) {
+        const threadFilePath = this.getThreadFilePath(agentThreadId);
+        const lines = this.serializeThreadData(threadData);
+        if (lines.length === 0) {
+            await this.deleteThreadFileIfExists(threadFilePath);
+            return;
+        }
+        await fs.writeFile(threadFilePath, lines.join("\n"));
+    }
+    /**
+     * Group graph data by thread ID
+     */
+    groupByThread(graph) {
+        const threadMap = new Map();
+        for (const entity of graph.entities) {
+            const threadData = this.getOrCreateThreadData(threadMap, entity.agentThreadId);
+            threadData.entities.push(entity);
+        }
+        for (const relation of graph.relations) {
+            const threadData = this.getOrCreateThreadData(threadMap, relation.agentThreadId);
+            threadData.relations.push(relation);
+        }
+        return threadMap;
+    }
+    /**
+     * Save all thread data to their respective files
+     */
+    async saveAllThreads(threadMap) {
+        const savePromises = Array.from(threadMap.entries()).map(([threadId, data]) => this.saveGraphForThread(threadId, data));
+        await Promise.all(savePromises);
+    }
+    /**
+     * Clean up stale thread files that are no longer in the graph
+     */
+    async cleanupStaleThreadFiles(activeThreadIds) {
+        try {
+            const threadFiles = await this.getThreadFileNames();
+            const deletePromises = threadFiles.map(async (fileName) => {
+                const threadId = this.extractThreadId(fileName);
+                if (threadId && !activeThreadIds.has(threadId)) {
+                    const filePath = path.join(this.memoryDirPath, fileName);
+                    await this.deleteThreadFileIfExists(filePath);
+                }
+            });
+            await Promise.all(deletePromises);
+        }
+        catch (error) {
+            console.warn('Failed to clean up stale thread files:', error);
+        }
+    }
+    /**
+     * Save the complete knowledge graph to thread-specific files
+     */
+    async saveGraph(graph) {
+        const threadMap = this.groupByThread(graph);
+        await this.saveAllThreads(threadMap);
+        await this.cleanupStaleThreadFiles(new Set(threadMap.keys()));
+    }
+    /**
+     * Initialize the storage adapter (create memory directory if needed)
+     */
+    async initialize() {
+        await fs.mkdir(this.memoryDirPath, { recursive: true });
+    }
+}

package/dist/lib/knowledge-graph-manager.js

@@ -1,182 +1,38 @@
 /**
  * KnowledgeGraphManager - Main class for managing the knowledge graph
  */
-import { promises as fs } from 'fs';
-import path from 'path';
 import { randomUUID } from 'crypto';
+import { JsonlStorageAdapter } from './jsonl-storage-adapter.js';
 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;
+    storage;
+    initializePromise = null;
+    constructor(memoryDirPath, storageAdapter) {
+        this.storage = storageAdapter || new JsonlStorageAdapter(memoryDirPath);
+        // Lazy initialization - will be called on first operation
     }
-    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);
+    /**
+     * Ensure storage is initialized before any operation
+     * This is called automatically by all public methods
+     */
+    async ensureInitialized() {
+        if (!this.initializePromise) {
+            this.initializePromise = this.storage.initialize();
         }
+        await this.initializePromise;
     }
     async createEntities(entities) {
-        const graph = await this.loadGraph();
+        await this.ensureInitialized();
+        const graph = await this.storage.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);
+        await this.storage.saveGraph(graph);
         return newEntities;
     }
     async createRelations(relations) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // Validate that referenced entities exist
         const entityNames = new Set(graph.entities.map(e => e.name));
         const validRelations = relations.filter(r => {
@@ -192,11 +48,11 @@ export class KnowledgeGraphManager {
             existingRelation.to === r.to &&
             existingRelation.relationType === r.relationType));
         graph.relations.push(...newRelations);
-        await this.saveGraph(graph);
+        await this.storage.saveGraph(graph);
         return newRelations;
     }
     async addObservations(observations) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         const results = observations.map(o => {
             const entity = graph.entities.find(e => e.name === o.entityName);
             if (!entity) {
@@ -231,17 +87,17 @@ export class KnowledgeGraphManager {
             entity.importance = Math.max(entity.importance, o.importance);
             return { entityName: o.entityName, addedObservations: newObservations };
         });
-        await this.saveGraph(graph);
+        await this.storage.saveGraph(graph);
         return results;
     }
     async deleteEntities(entityNames) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.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);
+        await this.storage.saveGraph(graph);
     }
     async deleteObservations(deletions) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         deletions.forEach(d => {
             const entity = graph.entities.find(e => e.name === d.entityName);
             if (entity) {
@@ -249,22 +105,22 @@ export class KnowledgeGraphManager {
                 entity.observations = entity.observations.filter(o => !d.observations.includes(o.content) && !d.observations.includes(o.id));
             }
         });
-        await this.saveGraph(graph);
+        await this.storage.saveGraph(graph);
     }
     async deleteRelations(relations) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.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);
+        await this.storage.saveGraph(graph);
     }
     async readGraph() {
-        return this.loadGraph();
+        return this.storage.loadGraph();
     }
     async searchNodes(query) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // Filter entities
         const filteredEntities = graph.entities.filter(e => e.name.toLowerCase().includes(query.toLowerCase()) ||
             e.entityType.toLowerCase().includes(query.toLowerCase()) ||
@@ -280,7 +136,7 @@ export class KnowledgeGraphManager {
         return filteredGraph;
     }
     async openNodes(names) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // Filter entities
         const filteredEntities = graph.entities.filter(e => names.includes(e.name));
         // Create a Set of filtered entity names for quick lookup
@@ -294,7 +150,7 @@ export class KnowledgeGraphManager {
         return filteredGraph;
     }
     async queryNodes(filters) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // If no filters provided, return entire graph
         if (!filters) {
             return graph;
@@ -349,7 +205,7 @@ export class KnowledgeGraphManager {
     }
     // Enhancement 1: Memory Statistics & Insights
     async getMemoryStats() {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // Count entity types
         const entityTypes = {};
         graph.entities.forEach(e => {
@@ -392,7 +248,7 @@ export class KnowledgeGraphManager {
     }
     // Enhancement 2: Get recent changes
     async getRecentChanges(since) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.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);
@@ -405,7 +261,7 @@ export class KnowledgeGraphManager {
     }
     // Enhancement 3: Relationship path finding
     async findRelationPath(from, to, maxDepth = 5) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         if (from === to) {
             return { found: true, path: [from], relations: [] };
         }
@@ -463,7 +319,7 @@ export class KnowledgeGraphManager {
     }
     // Enhancement 4: Detect conflicting observations
     async detectConflicts() {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         const conflicts = [];
         for (const entity of graph.entities) {
             const entityConflicts = [];
@@ -504,7 +360,7 @@ export class KnowledgeGraphManager {
     }
     // Enhancement 5: Memory pruning
     async pruneMemory(options) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         const initialEntityCount = graph.entities.length;
         const initialRelationCount = graph.relations.length;
         // Filter entities to remove
@@ -534,7 +390,7 @@ export class KnowledgeGraphManager {
         const relationsToKeep = graph.relations.filter(r => keptEntityNames.has(r.from) && keptEntityNames.has(r.to));
         graph.entities = entitiesToKeep;
         graph.relations = relationsToKeep;
-        await this.saveGraph(graph);
+        await this.storage.saveGraph(graph);
         return {
             removedEntities: initialEntityCount - entitiesToKeep.length,
             removedRelations: initialRelationCount - relationsToKeep.length
@@ -542,7 +398,7 @@ export class KnowledgeGraphManager {
     }
     // Enhancement 6: Batch operations
     async bulkUpdate(updates) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         let updated = 0;
         const notFound = [];
         for (const update of updates) {
@@ -575,12 +431,12 @@ export class KnowledgeGraphManager {
             entity.timestamp = new Date().toISOString();
             updated++;
         }
-        await this.saveGraph(graph);
+        await this.storage.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 graph = await this.storage.loadGraph();
         const entity = graph.entities.find(e => e.name === entityName);
         if (!entity) {
             throw new Error(`Entity with name ${entityName} not found`);
@@ -600,17 +456,17 @@ export class KnowledgeGraphManager {
             };
             entity.observations.push(flagObservation);
             entity.timestamp = new Date().toISOString();
-            await this.saveGraph(graph);
+            await this.storage.saveGraph(graph);
         }
     }
     // Enhancement 8: Get entities flagged for review
     async getFlaggedEntities() {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         return graph.entities.filter(e => e.observations.some(obs => obs.content.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 graph = await this.storage.loadGraph();
         const contextEntityNames = new Set(entityNames);
         // Expand to include related entities up to specified depth
         for (let d = 0; d < depth; d++) {
@@ -635,7 +491,7 @@ export class KnowledgeGraphManager {
     }
     // Enhancement 10: List conversations (agent threads)
     async listConversations() {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // Group data by agent thread
         const threadMap = new Map();
         // Collect entities by thread
@@ -673,7 +529,7 @@ export class KnowledgeGraphManager {
     }
     // Analytics: Get analytics for a specific thread (limited to 4 core metrics)
     async getAnalytics(threadId) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // Filter to thread-specific data
         const threadEntities = graph.entities.filter(e => e.agentThreadId === threadId);
         const threadRelations = graph.relations.filter(r => r.agentThreadId === threadId);
@@ -756,7 +612,7 @@ export class KnowledgeGraphManager {
     }
     // Observation Versioning: Get full history chain for an observation
     async getObservationHistory(entityName, observationId) {
-        const graph = await this.loadGraph();
+        const graph = await this.storage.loadGraph();
         // Find the entity
         const entity = graph.entities.find(e => e.name === entityName);
         if (!entity) {

package/dist/lib/neo4j-storage-adapter.js

@@ -0,0 +1,142 @@
+/**
+ * Neo4j Storage Adapter (Skeleton Implementation)
+ *
+ * This is a skeleton implementation showing how a Neo4j storage adapter could be built.
+ * To use this in production, you would need to:
+ * 1. Install neo4j-driver: npm install neo4j-driver
+ * 2. Implement the actual Cypher queries
+ * 3. Add error handling and connection management
+ * 4. Add transaction support for atomic operations
+ *
+ * Example usage:
+ * ```typescript
+ * import { Neo4jStorageAdapter } from './neo4j-storage-adapter.js';
+ * import { KnowledgeGraphManager } from './knowledge-graph-manager.js';
+ *
+ * const neo4jAdapter = new Neo4jStorageAdapter({
+ *   uri: 'neo4j://localhost:7687',
+ *   username: 'neo4j',
+ *   password: 'password'
+ * });
+ *
+ * await neo4jAdapter.initialize();
+ * const manager = new KnowledgeGraphManager('', neo4jAdapter);
+ * ```
+ */
+/**
+ * Neo4j-based storage adapter for the knowledge graph
+ * This is a skeleton implementation - requires neo4j-driver package
+ */
+export class Neo4jStorageAdapter {
+    config;
+    // private driver: any; // Would be neo4j.Driver from neo4j-driver package
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Initialize Neo4j connection
+     */
+    async initialize() {
+        // TODO: Initialize Neo4j driver
+        // this.driver = neo4j.driver(
+        //   this.config.uri,
+        //   neo4j.auth.basic(this.config.username, this.config.password)
+        // );
+        // TODO: Verify connectivity
+        // await this.driver.verifyConnectivity();
+        // TODO: Create constraints and indexes
+        // const session = this.driver.session({ database: this.config.database });
+        // try {
+        //   await session.run('CREATE CONSTRAINT IF NOT EXISTS FOR (e:Entity) REQUIRE e.name IS UNIQUE');
+        //   await session.run('CREATE INDEX IF NOT EXISTS FOR (e:Entity) ON (e.entityType)');
+        //   await session.run('CREATE INDEX IF NOT EXISTS FOR (e:Entity) ON (e.agentThreadId)');
+        // } finally {
+        //   await session.close();
+        // }
+        throw new Error('Neo4jStorageAdapter requires neo4j-driver package to be installed and methods to be implemented. See STORAGE.md documentation for setup instructions.');
+    }
+    /**
+     * Load the complete knowledge graph from Neo4j
+     */
+    async loadGraph() {
+        // TODO: Implement Cypher query to load all entities and relations
+        // Example Cypher for entities:
+        // MATCH (e:Entity)
+        // RETURN e.name as name, 
+        //        e.entityType as entityType,
+        //        e.observations as observations,
+        //        e.agentThreadId as agentThreadId,
+        //        e.timestamp as timestamp,
+        //        e.confidence as confidence,
+        //        e.importance as importance
+        // Example Cypher for relations:
+        // MATCH (from:Entity)-[r:RELATES_TO]->(to:Entity)
+        // RETURN from.name as from,
+        //        to.name as to,
+        //        r.relationType as relationType,
+        //        r.agentThreadId as agentThreadId,
+        //        r.timestamp as timestamp,
+        //        r.confidence as confidence,
+        //        r.importance as importance
+        throw new Error('Neo4jStorageAdapter.loadGraph() is not implemented. This is a skeleton - install neo4j-driver and implement the Cypher queries shown in comments above.');
+    }
+    /**
+     * Save the complete knowledge graph to Neo4j
+     */
+    async saveGraph(graph) {
+        // TODO: Implement transactional save
+        // This should:
+        // 1. Start a transaction
+        // 2. Delete all existing nodes and relationships (or use MERGE for upsert)
+        // 3. Create all entities as nodes
+        // 4. Create all relations as relationships
+        // 5. Commit the transaction
+        // Example Cypher for creating entity:
+        // MERGE (e:Entity {name: $name})
+        // SET e.entityType = $entityType,
+        //     e.observations = $observations,
+        //     e.agentThreadId = $agentThreadId,
+        //     e.timestamp = $timestamp,
+        //     e.confidence = $confidence,
+        //     e.importance = $importance
+        // Example Cypher for creating relation:
+        // MATCH (from:Entity {name: $from})
+        // MATCH (to:Entity {name: $to})
+        // MERGE (from)-[r:RELATES_TO {relationType: $relationType}]->(to)
+        // SET r.agentThreadId = $agentThreadId,
+        //     r.timestamp = $timestamp,
+        //     r.confidence = $confidence,
+        //     r.importance = $importance
+        throw new Error('Neo4jStorageAdapter.saveGraph() is not implemented. This is a skeleton - install neo4j-driver and implement the transactional save logic shown in comments above.');
+    }
+    /**
+     * Close Neo4j connection
+     */
+    async close() {
+        // TODO: Close the driver
+        // if (this.driver) {
+        //   await this.driver.close();
+        // }
+    }
+}
+/**
+ * Example of how this adapter could be used:
+ *
+ * const neo4jAdapter = new Neo4jStorageAdapter({
+ *   uri: 'neo4j://localhost:7687',
+ *   username: 'neo4j',
+ *   password: 'password',
+ *   database: 'knowledge-graph'
+ * });
+ *
+ * await neo4jAdapter.initialize();
+ *
+ * const manager = new KnowledgeGraphManager('', neo4jAdapter);
+ *
+ * // Use the manager as normal - all operations will now use Neo4j
+ * await manager.createEntities([...]);
+ * const graph = await manager.readGraph();
+ *
+ * // Clean up when done
+ * await neo4jAdapter.close();
+ */

package/dist/lib/storage-interface.js

@@ -0,0 +1,5 @@
+/**
+ * Storage interface abstraction for the Knowledge Graph
+ * This allows for different storage backends (JSONL, Neo4j, etc.)
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-memory-enhanced",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Enhanced MCP server for memory with agent threading, timestamps, and confidence scoring",
   "license": "MIT",
   "mcpName": "io.github.modelcontextprotocol/server-memory-enhanced",