server-memory-enhanced 2.0.0 → 2.2.0

package/dist/index.js

@@ -8,6 +8,9 @@ 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';
+import { JsonlStorageAdapter } from './lib/jsonl-storage-adapter.js';
+import { Neo4jStorageAdapter } from './lib/neo4j-storage-adapter.js';
+import { NEO4J_ENV_VARS, STORAGE_LOG_MESSAGES, NEO4J_ERROR_MESSAGES } from './lib/storage-config.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() {
@@ -25,9 +28,76 @@ export async function ensureMemoryDirectory() {
     }
     return memoryDir;
 }
+/**
+ * Get Neo4j configuration from environment variables.
+ * Extracted for testability and Single Responsibility Principle.
+ */
+function getNeo4jConfig() {
+    const uri = process.env[NEO4J_ENV_VARS.URI];
+    const username = process.env[NEO4J_ENV_VARS.USERNAME];
+    const password = process.env[NEO4J_ENV_VARS.PASSWORD];
+    const database = process.env[NEO4J_ENV_VARS.DATABASE];
+    if (!uri || !username || !password) {
+        return null;
+    }
+    return { uri, username, password, database };
+}
+/**
+ * Create Neo4j storage adapter if configured.
+ * Extracted for Single Responsibility Principle and testability.
+ */
+async function createNeo4jAdapter(config) {
+    try {
+        console.error(STORAGE_LOG_MESSAGES.ATTEMPTING_NEO4J, config.uri);
+        const neo4jAdapter = new Neo4jStorageAdapter(config);
+        await neo4jAdapter.initialize();
+        console.error(STORAGE_LOG_MESSAGES.NEO4J_SUCCESS);
+        return neo4jAdapter;
+    }
+    catch (error) {
+        // Sanitize error message to avoid exposing credentials
+        const safeErrorMessage = error instanceof Error ? error.message.replace(/password[=:][\S]+/gi, 'password:***') : 'Connection failed';
+        console.error(STORAGE_LOG_MESSAGES.NEO4J_FALLBACK, safeErrorMessage);
+        return null;
+    }
+}
+/**
+ * Create JSONL storage adapter.
+ * Extracted for DRY and testability.
+ */
+async function createJsonlAdapter(memoryDirPath) {
+    const jsonlAdapter = new JsonlStorageAdapter(memoryDirPath);
+    await jsonlAdapter.initialize();
+    console.error(STORAGE_LOG_MESSAGES.USING_JSONL, memoryDirPath);
+    return jsonlAdapter;
+}
+/**
+ * Create storage adapter based on environment variables.
+ * Falls back to JSONL storage if Neo4j is not configured or connection fails.
+ *
+ * Follows Open/Closed Principle: Open for extension (add new storage types)
+ * without modifying existing code.
+ */
+async function createStorageAdapter(memoryDirPath) {
+    // Try Neo4j if configured
+    const neo4jConfig = getNeo4jConfig();
+    if (neo4jConfig) {
+        const neo4jAdapter = await createNeo4jAdapter(neo4jConfig);
+        if (neo4jAdapter) {
+            return neo4jAdapter;
+        }
+    }
+    else {
+        console.error(NEO4J_ERROR_MESSAGES.NOT_CONFIGURED);
+    }
+    // Fall back to JSONL storage
+    return createJsonlAdapter(memoryDirPath);
+}
 // 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;
@@ -491,8 +561,38 @@ server.registerTool("get_observation_history", {
 async function main() {
     // Initialize memory directory path
     MEMORY_DIR_PATH = await ensureMemoryDirectory();
-    // Initialize knowledge graph manager with the memory directory path
-    knowledgeGraphManager = new KnowledgeGraphManager(MEMORY_DIR_PATH);
+    // Create storage adapter based on environment variables
+    // Falls back to JSONL if Neo4j is not configured or connection fails
+    const storageAdapter = await createStorageAdapter(MEMORY_DIR_PATH);
+    // Initialize knowledge graph manager with the storage adapter
+    knowledgeGraphManager = new KnowledgeGraphManager(MEMORY_DIR_PATH, storageAdapter);
+    // Register graceful shutdown handlers to ensure storage adapter is closed
+    let isShuttingDown = false;
+    const shutdown = async (signal) => {
+        if (isShuttingDown) {
+            return;
+        }
+        isShuttingDown = true;
+        console.error(`Received ${signal}, shutting down gracefully...`);
+        try {
+            // Close storage adapter (including Neo4j connections) before exiting
+            if (storageAdapter && 'close' in storageAdapter && typeof storageAdapter.close === 'function') {
+                await storageAdapter.close();
+            }
+        }
+        catch (err) {
+            console.error("Error during storage adapter shutdown:", err);
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    process.on("SIGINT", () => {
+        void shutdown("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+        void shutdown("SIGTERM");
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Enhanced Knowledge Graph MCP Server running on stdio");

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-queries.js

@@ -0,0 +1,82 @@
+/**
+ * Neo4j Cypher Queries
+ *
+ * Centralizes all Cypher queries for the Neo4j storage adapter.
+ * Following Single Responsibility Principle - this module is responsible only for query definitions.
+ */
+/**
+ * Constraint and index queries for schema initialization
+ */
+export const SCHEMA_QUERIES = {
+    createUniqueConstraint: 'CREATE CONSTRAINT entity_name_unique IF NOT EXISTS FOR (e:Entity) REQUIRE e.name IS UNIQUE',
+    createEntityTypeIndex: 'CREATE INDEX entity_type_idx IF NOT EXISTS FOR (e:Entity) ON (e.entityType)',
+    createThreadIndex: 'CREATE INDEX entity_thread_idx IF NOT EXISTS FOR (e:Entity) ON (e.agentThreadId)',
+    createTimestampIndex: 'CREATE INDEX entity_timestamp_idx IF NOT EXISTS FOR (e:Entity) ON (e.timestamp)',
+};
+/**
+ * Entity queries
+ */
+export const ENTITY_QUERIES = {
+    loadAll: `
+    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
+  `,
+    // Note: Using CREATE instead of MERGE is intentional here.
+    // The saveGraph() method first deletes all existing data, then creates fresh entities.
+    // This is a complete graph replacement operation, not an upsert.
+    // The unique constraint on entity names prevents duplicates within a single transaction.
+    create: `
+    CREATE (e:Entity {
+      name: $name,
+      entityType: $entityType,
+      observations: $observations,
+      agentThreadId: $agentThreadId,
+      timestamp: $timestamp,
+      confidence: $confidence,
+      importance: $importance
+    })
+  `,
+};
+/**
+ * Relation queries
+ */
+export const RELATION_QUERIES = {
+    loadAll: `
+    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
+  `,
+    // Note: Using MATCH for both entities is intentional.
+    // The saveGraph() method ensures entities are created first, then relations.
+    // Since this runs in a transaction after entity creation, both entities must exist.
+    // If either entity doesn't exist, the relation creation will fail the transaction,
+    // maintaining data integrity (no orphaned relations).
+    create: `
+    MATCH (from:Entity {name: $from})
+    MATCH (to:Entity {name: $to})
+    CREATE (from)-[r:RELATES_TO {
+      relationType: $relationType,
+      agentThreadId: $agentThreadId,
+      timestamp: $timestamp,
+      confidence: $confidence,
+      importance: $importance
+    }]->(to)
+  `,
+};
+/**
+ * Maintenance queries
+ */
+export const MAINTENANCE_QUERIES = {
+    deleteAll: 'MATCH (n:Entity) DETACH DELETE n',
+};

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

@@ -0,0 +1,271 @@
+/**
+ * Neo4j Storage Adapter
+ *
+ * Production-ready implementation of the Neo4j storage adapter.
+ * Provides full CRUD operations for the knowledge graph using Neo4j.
+ *
+ * SOLID Principles Applied:
+ * - Single Responsibility: Adapter only handles Neo4j storage operations
+ * - Open/Closed: Can be extended without modification through IStorageAdapter
+ * - Liskov Substitution: Can replace any IStorageAdapter implementation
+ * - Interface Segregation: Implements minimal IStorageAdapter interface
+ * - Dependency Inversion: Depends on IStorageAdapter abstraction
+ *
+ * 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);
+ * ```
+ */
+import neo4j from 'neo4j-driver';
+import { SCHEMA_QUERIES, ENTITY_QUERIES, RELATION_QUERIES, MAINTENANCE_QUERIES } from './neo4j-queries.js';
+import { NEO4J_ERROR_MESSAGES } from './storage-config.js';
+/**
+ * Neo4j-based storage adapter for the knowledge graph.
+ * Follows Single Responsibility Principle - only handles Neo4j storage operations.
+ */
+export class Neo4jStorageAdapter {
+    config;
+    driver = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Initialize Neo4j connection and schema.
+     * Creates constraints and indexes for optimal performance.
+     */
+    async initialize() {
+        try {
+            await this.initializeDriver();
+            await this.verifyConnection();
+            await this.initializeSchema();
+        }
+        catch (error) {
+            throw new Error(`${NEO4J_ERROR_MESSAGES.CONNECTION_FAILED}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Initialize the Neo4j driver.
+     * Extracted for better testability and separation of concerns.
+     */
+    async initializeDriver() {
+        this.driver = neo4j.driver(this.config.uri, neo4j.auth.basic(this.config.username, this.config.password));
+    }
+    /**
+     * Verify connection to Neo4j.
+     * Extracted for better error handling and testability.
+     */
+    async verifyConnection() {
+        if (!this.driver) {
+            throw new Error(NEO4J_ERROR_MESSAGES.NOT_INITIALIZED);
+        }
+        await this.driver.verifyConnectivity();
+    }
+    /**
+     * Initialize database schema (constraints and indexes).
+     * Extracted for Single Responsibility Principle.
+     */
+    async initializeSchema() {
+        const session = await this.createSession();
+        try {
+            await session.run(SCHEMA_QUERIES.createUniqueConstraint);
+            await session.run(SCHEMA_QUERIES.createEntityTypeIndex);
+            await session.run(SCHEMA_QUERIES.createThreadIndex);
+            await session.run(SCHEMA_QUERIES.createTimestampIndex);
+        }
+        finally {
+            await session.close();
+        }
+    }
+    /**
+     * Create a Neo4j session.
+     * Centralized session creation for DRY principle.
+     */
+    async createSession() {
+        this.ensureDriverInitialized();
+        return this.driver.session({ database: this.config.database });
+    }
+    /**
+     * Ensure driver is initialized.
+     * Guard clause for better error handling.
+     */
+    ensureDriverInitialized() {
+        if (!this.driver) {
+            throw new Error(NEO4J_ERROR_MESSAGES.NOT_INITIALIZED);
+        }
+    }
+    /**
+     * Serialize observations for Neo4j storage.
+     * Extracted for testability and reusability (DRY).
+     */
+    serializeObservations(observations) {
+        return JSON.stringify(observations);
+    }
+    /**
+     * Deserialize observations from Neo4j storage.
+     * Extracted for testability and reusability (DRY).
+     * Returns empty array on parse error for robustness.
+     */
+    deserializeObservations(observationsJson) {
+        try {
+            return JSON.parse(observationsJson);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Map Neo4j record to Entity object.
+     * Extracted for Single Responsibility Principle and DRY.
+     */
+    mapRecordToEntity(record) {
+        return {
+            name: record.get('name'),
+            entityType: record.get('entityType'),
+            observations: this.deserializeObservations(record.get('observations')),
+            agentThreadId: record.get('agentThreadId'),
+            timestamp: record.get('timestamp'),
+            confidence: record.get('confidence'),
+            importance: record.get('importance')
+        };
+    }
+    /**
+     * Map Neo4j record to Relation object.
+     * Extracted for Single Responsibility Principle and DRY.
+     */
+    mapRecordToRelation(record) {
+        return {
+            from: record.get('from'),
+            to: record.get('to'),
+            relationType: record.get('relationType'),
+            agentThreadId: record.get('agentThreadId'),
+            timestamp: record.get('timestamp'),
+            confidence: record.get('confidence'),
+            importance: record.get('importance')
+        };
+    }
+    /**
+     * Load the complete knowledge graph from Neo4j.
+     * Delegates to specialized methods for clarity.
+     */
+    async loadGraph() {
+        this.ensureDriverInitialized();
+        const session = await this.createSession();
+        try {
+            const entities = await this.loadEntities(session);
+            const relations = await this.loadRelations(session);
+            return { entities, relations };
+        }
+        finally {
+            await session.close();
+        }
+    }
+    /**
+     * Load all entities from Neo4j.
+     * Extracted for Single Responsibility Principle.
+     */
+    async loadEntities(session) {
+        const result = await session.run(ENTITY_QUERIES.loadAll);
+        return result.records.map(record => this.mapRecordToEntity(record));
+    }
+    /**
+     * Load all relations from Neo4j.
+     * Extracted for Single Responsibility Principle.
+     */
+    async loadRelations(session) {
+        const result = await session.run(RELATION_QUERIES.loadAll);
+        return result.records.map(record => this.mapRecordToRelation(record));
+    }
+    /**
+     * Save the complete knowledge graph to Neo4j.
+     * Uses transactions for atomicity.
+     */
+    async saveGraph(graph) {
+        this.ensureDriverInitialized();
+        const session = await this.createSession();
+        try {
+            await session.executeWrite(async (tx) => {
+                await this.clearDatabase(tx);
+                await this.saveEntities(tx, graph.entities);
+                await this.saveRelations(tx, graph.relations);
+            });
+        }
+        finally {
+            await session.close();
+        }
+    }
+    /**
+     * Clear all data from the database.
+     * Extracted for Single Responsibility Principle.
+     */
+    async clearDatabase(tx) {
+        await tx.run(MAINTENANCE_QUERIES.deleteAll);
+    }
+    /**
+     * Save all entities to Neo4j.
+     * Extracted for Single Responsibility Principle and testability.
+     */
+    async saveEntities(tx, entities) {
+        for (const entity of entities) {
+            await this.saveEntity(tx, entity);
+        }
+    }
+    /**
+     * Save a single entity to Neo4j.
+     * Extracted for DRY and testability.
+     */
+    async saveEntity(tx, entity) {
+        await tx.run(ENTITY_QUERIES.create, {
+            name: entity.name,
+            entityType: entity.entityType,
+            observations: this.serializeObservations(entity.observations),
+            agentThreadId: entity.agentThreadId,
+            timestamp: entity.timestamp,
+            confidence: entity.confidence,
+            importance: entity.importance
+        });
+    }
+    /**
+     * Save all relations to Neo4j.
+     * Extracted for Single Responsibility Principle and testability.
+     */
+    async saveRelations(tx, relations) {
+        for (const relation of relations) {
+            await this.saveRelation(tx, relation);
+        }
+    }
+    /**
+     * Save a single relation to Neo4j.
+     * Extracted for DRY and testability.
+     */
+    async saveRelation(tx, relation) {
+        await tx.run(RELATION_QUERIES.create, {
+            from: relation.from,
+            to: relation.to,
+            relationType: relation.relationType,
+            agentThreadId: relation.agentThreadId,
+            timestamp: relation.timestamp,
+            confidence: relation.confidence,
+            importance: relation.importance
+        });
+    }
+    /**
+     * Close Neo4j connection.
+     * Properly cleans up resources.
+     */
+    async close() {
+        if (this.driver) {
+            await this.driver.close();
+            this.driver = null;
+        }
+    }
+}

package/dist/lib/storage-config.js

@@ -0,0 +1,40 @@
+/**
+ * Storage Configuration Constants
+ *
+ * Centralizes all configuration constants for storage adapters.
+ * Following DRY principle - define once, use everywhere.
+ */
+/**
+ * Environment variable names for Neo4j configuration
+ */
+export const NEO4J_ENV_VARS = {
+    URI: 'NEO4J_URI',
+    USERNAME: 'NEO4J_USERNAME',
+    PASSWORD: 'NEO4J_PASSWORD',
+    DATABASE: 'NEO4J_DATABASE',
+};
+/**
+ * Default Neo4j configuration values
+ */
+export const NEO4J_DEFAULTS = {
+    URI: 'neo4j://localhost:7687',
+    USERNAME: 'neo4j',
+    PASSWORD: 'testpassword',
+};
+/**
+ * Error messages for Neo4j storage
+ */
+export const NEO4J_ERROR_MESSAGES = {
+    NOT_INITIALIZED: 'Neo4j driver not initialized. Call initialize() first.',
+    CONNECTION_FAILED: 'Failed to initialize Neo4j connection',
+    NOT_CONFIGURED: 'Neo4j not configured (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD), using JSONL storage',
+};
+/**
+ * Log messages for storage selection
+ */
+export const STORAGE_LOG_MESSAGES = {
+    ATTEMPTING_NEO4J: 'Attempting to connect to Neo4j at',
+    NEO4J_SUCCESS: 'Successfully connected to Neo4j storage',
+    NEO4J_FALLBACK: 'Failed to connect to Neo4j, falling back to JSONL storage:',
+    USING_JSONL: 'Using JSONL storage at',
+};

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.2.0",
   "description": "Enhanced MCP server for memory with agent threading, timestamps, and confidence scoring",
   "license": "MIT",
   "mcpName": "io.github.modelcontextprotocol/server-memory-enhanced",
@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
+    "neo4j-driver": "^6.0.1",
     "zod": "^3.25.0"
   },
   "devDependencies": {