Neo4j Agent Memory MCP Server

Instructions

Implementation Reference

• src/handlers/index.ts:265-278 (handler)

  Handler for the 'delete_memory' tool. Validates arguments using isDeleteMemoryArgs, calls neo4j.deleteNode to delete the node and its connections, and returns the result as JSON.

  case 'delete_memory': {
    if (!isDeleteMemoryArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid delete_memory arguments');
    }
    const result = await neo4j.deleteNode(args.nodeId);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/neo4j-client.ts:116-126 (helper)

  Neo4jClient method that performs DETACH DELETE on the node by ID, removing it and all connected relationships, returning the count of deleted nodes.

  async deleteNode(nodeId: number): Promise<any> {
    const result = await this.executeQuery(
      `MATCH (n) WHERE id(n) = $nodeId
       DETACH DELETE n
       RETURN count(n) as deletedCount`,
      {
        nodeId: neo4j.int(nodeId),
      }
    );
    return result[0];
  }

• src/tools/definitions.ts:137-150 (schema)

  Tool definition including name, description, and input schema for MCP tool registration.

  {
    name: 'delete_memory',
    description: 'Delete a memory and all its connections (use with caution - this permanently removes the memory and all its connections)',
    inputSchema: {
      type: 'object',
      properties: {
        nodeId: {
          type: 'number',
          description: 'ID of the memory to delete',
        },
      },
      required: ['nodeId'],
    },
  },

• src/types.ts:41-103 (schema)

  TypeScript interface and runtime validator function for DeleteMemoryArgs used in handler validation.

  export interface DeleteMemoryArgs {
    nodeId: number;
  }
  
  export interface DeleteConnectionArgs {
    fromMemoryId: number;
    toMemoryId: number;
    type: string;
  }
  
  export interface ListMemoryLabelsArgs {
    // No arguments needed for this tool
  }
  
  export function isCreateMemoryArgs(args: unknown): args is CreateMemoryArgs {
    return typeof args === 'object' && args !== null && typeof (args as CreateMemoryArgs).label === 'string' && typeof (args as CreateMemoryArgs).properties === 'object';
  }
  
  export function isSearchMemoriesArgs(args: unknown): args is SearchMemoriesArgs {
    if (typeof args !== 'object' || args === null) return false;
    const searchArgs = args as SearchMemoriesArgs;
    if (searchArgs.query !== undefined && typeof searchArgs.query !== 'string') return false;
    if (searchArgs.since_date !== undefined && typeof searchArgs.since_date !== 'string') return false;
    return true;
  }
  
  export function isCreateConnectionArgs(args: unknown): args is CreateConnectionArgs {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof (args as CreateConnectionArgs).fromMemoryId === 'number' &&
      typeof (args as CreateConnectionArgs).toMemoryId === 'number' &&
      typeof (args as CreateConnectionArgs).type === 'string'
    );
  }
  
  export function isUpdateMemoryArgs(args: unknown): args is UpdateMemoryArgs {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof (args as UpdateMemoryArgs).nodeId === 'number' &&
      typeof (args as UpdateMemoryArgs).properties === 'object'
    );
  }
  
  export function isUpdateConnectionArgs(args: unknown): args is UpdateConnectionArgs {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof (args as UpdateConnectionArgs).fromMemoryId === 'number' &&
      typeof (args as UpdateConnectionArgs).toMemoryId === 'number' &&
      typeof (args as UpdateConnectionArgs).type === 'string' &&
      typeof (args as UpdateConnectionArgs).properties === 'object'
    );
  }
  
  export function isDeleteMemoryArgs(args: unknown): args is DeleteMemoryArgs {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof (args as DeleteMemoryArgs).nodeId === 'number'
    );
  }