Neo4j Agent Memory MCP Server

Instructions

Implementation Reference

• src/handlers/index.ts:22-188 (handler)

  Core handler logic for the 'search_memories' tool. Validates arguments, implements flexible full-text search across all memory properties using JavaScript (word-based matching in arrays/objects), builds Neo4j queries for filtering by label/date, collects matching memory IDs, then fetches detailed results with optional connected nodes up to specified depth. Handles fallbacks and limits results.
  case 'search_memories': { if (!isSearchMemoriesArgs(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid search_memories arguments'); } const depth = args.depth ?? 1; const limit = Math.min(args.limit ?? 10, 200); let orderBy = 'memory.created_at DESC'; if (args.order_by) { const orderMatch = args.order_by.match(/^(memory\.|n\.)?([a-zA-Z_]+)\s+(ASC|DESC)$/i); if (orderMatch) { const property = orderMatch[2]; const direction = orderMatch[3].toUpperCase(); orderBy = `memory.${property} ${direction}`; } } const params: Record<string, any> = {}; if (args.query) params.query = args.query; if (args.label) params.label = args.label; if (args.since_date) params.since_date = args.since_date; // Try a different approach: execute simple queries and handle complexity in JavaScript const allMemoryIds = new Set<number>(); try { // First, get all memories that match the label and date filters (if any) let baseQuery = `MATCH (memory)`; const conditions = []; if (args.label) { conditions.push(`labels(memory)[0] = $label`); } if (args.since_date) { conditions.push(`memory.created_at >= $since_date`); } if (conditions.length > 0) { baseQuery += ` WHERE ` + conditions.join(' AND '); } baseQuery += ` RETURN id(memory) as id, properties(memory) as props`; const queryParams: Record<string, any> = {}; if (args.label) queryParams.label = args.label; if (args.since_date) queryParams.since_date = args.since_date; const allMemories = await neo4j.executeQuery(baseQuery, queryParams); // Filter in JavaScript for (const record of allMemories) { const props = record.props; // If query is empty, include all memories (they already match label/date filters) if (!args.query || args.query.trim() === '') { allMemoryIds.add(record.id); continue; } // Split query into words for more flexible matching const queryWords = args.query.toLowerCase().trim().split(/\s+/); let found = false; // Search through all properties for (const [key, value] of Object.entries(props)) { if (value === null || value === undefined) continue; const valueStr = Array.isArray(value) ? value.map(v => v?.toString() || '').join(' ').toLowerCase() : value.toString().toLowerCase(); // Check if ANY query word is found in this property for (const word of queryWords) { if (valueStr.includes(word)) { found = true; break; } } if (found) { allMemoryIds.add(record.id); break; } } } } catch (error) { console.error('Error in search:', error); // Fallback to a simpler query if the above fails const conditions = []; if (args.query && args.query.trim() !== '') { conditions.push('(memory.name CONTAINS $query OR memory.context CONTAINS $query OR memory.description CONTAINS $query)'); } if (args.label) { conditions.push('labels(memory)[0] = $label'); } if (args.since_date) { conditions.push('memory.created_at >= $since_date'); } let fallbackQuery = `MATCH (memory)`; if (conditions.length > 0) { fallbackQuery += ` WHERE ${conditions.join(' AND ')}`; } fallbackQuery += ` RETURN collect(DISTINCT id(memory)) as memoryIds`; const fallbackParams: Record<string, any> = {}; if (args.query) fallbackParams.query = args.query; if (args.label) fallbackParams.label = args.label; if (args.since_date) fallbackParams.since_date = args.since_date; const fallbackResults = await neo4j.executeQuery(fallbackQuery, fallbackParams); if (fallbackResults.length > 0 && fallbackResults[0].memoryIds) { fallbackResults[0].memoryIds.forEach((id: number) => allMemoryIds.add(id)); } } if (allMemoryIds.size === 0) { return { content: [ { type: 'text', text: JSON.stringify([], null, 2), }, ], }; } // Query 3: Fetch the actual memories with connections let finalQuery = ` MATCH (memory) WHERE id(memory) IN $memoryIds `; if (depth > 0) { finalQuery += ` OPTIONAL MATCH path = (memory)-[*1..${depth}]-(related) RETURN memory, collect(DISTINCT { memory: related, relationship: relationships(path)[0], distance: length(path) }) as connections ORDER BY ${orderBy} LIMIT ${limit} `; } else { finalQuery += ` RETURN memory, [] as connections ORDER BY ${orderBy} LIMIT ${limit}`; } const result = await neo4j.executeQuery(finalQuery, { memoryIds: Array.from(allMemoryIds) }); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/tools/definitions.ts:11-44 (schema)

  MCP protocol tool schema definition for 'search_memories', exported in the tools array. Defines input parameters with descriptions used for tool discovery and validation by MCP clients.
  { name: 'search_memories', description: 'Search and retrieve memories from the knowledge graph', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search text to find in any property (searches for ANY word - e.g. "Ben Weeks" finds memories containing "Ben" OR "Weeks")', }, label: { type: 'string', description: 'Filter by memory label', }, depth: { type: 'number', description: 'Relationship depth to include, defaults to 1', }, order_by: { type: 'string', description: 'Sort order such as created_at DESC, name ASC', }, limit: { type: 'number', description: 'Maximum results to return, defaults to 10, max 200', }, since_date: { type: 'string', description: 'ISO date string to filter memories created after this date (e.g., "2024-01-01" or "2024-01-01T00:00:00Z")', }, }, required: [], }, },
• src/types.ts:13-65 (schema)

  Internal TypeScript interface and type guard validator for SearchMemoriesArgs, imported and used in the handler for runtime argument validation.
  export interface SearchMemoriesArgs { query?: string; label?: string; depth?: number; order_by?: string; limit?: number; since_date?: string; } export interface CreateConnectionArgs { fromMemoryId: number; toMemoryId: number; type: string; properties?: Record<string, any>; } export interface UpdateMemoryArgs { nodeId: number; properties: Record<string, any>; } export interface UpdateConnectionArgs { fromMemoryId: number; toMemoryId: number; type: string; properties: Record<string, any>; } 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; }
• src/server.ts:39-41 (registration)

  Registration of all tools (including search_memories) via the imported tools array in the MCP server's listTools request handler.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools, }));