server-memory-enhanced 2.1.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,6 +28,71 @@ 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';
@@ -493,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/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

@@ -1,12 +1,15 @@
 /**
- * Neo4j Storage Adapter (Skeleton Implementation)
+ * Neo4j Storage Adapter
  *
- * 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
+ * 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
@@ -23,120 +26,246 @@
  * 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
- * This is a skeleton implementation - requires neo4j-driver package
+ * Neo4j-based storage adapter for the knowledge graph.
+ * Follows Single Responsibility Principle - only handles Neo4j storage operations.
  */
 export class Neo4jStorageAdapter {
     config;
-    // private driver: any; // Would be neo4j.Driver from neo4j-driver package
+    driver = null;
     constructor(config) {
         this.config = config;
     }
     /**
-     * Initialize Neo4j connection
+     * Initialize Neo4j connection and schema.
+     * Creates constraints and indexes for optimal performance.
      */
     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
+        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() {
-        // 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
+        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) {
-        // 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
+        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() {
-        // TODO: Close the driver
-        // if (this.driver) {
-        //   await this.driver.close();
-        // }
+        if (this.driver) {
+            await this.driver.close();
+            this.driver = null;
+        }
     }
 }
-/**
- * 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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-memory-enhanced",
-  "version": "2.1.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": {