Neo4j Agent Memory MCP Server

Instructions

Implementation Reference

• src/tools/guidance-tool.ts:18-274 (handler)

  The core handler function that implements the get_guidance tool logic. It returns markdown-formatted guidance content based on the provided topic or all topics if none specified.
  export function getGuidanceContent(topic?: string): string { const sections = { connections: `## The Power of Connections **Why Connections Matter** - Isolated memories = limited utility - Connected memories = exponential value - Each connection adds context and meaning - Enables discovery of hidden patterns **Connection Strategy** 1. Create the memory first 2. Immediately ask: "What does this relate to?" 3. Search for related memories 4. Create meaningful connections 5. Add properties to connections for context **Example Flow** 1. User: "John works at Google as a software engineer" 2. **Search for John first** - he might already exist! 3. If not found, create memory for John (person) 4. **Search for Google** - it probably already exists 5. If not found, create Google (organization) 6. Connect: John -[WORKS_AT]-> Google 7. Add properties: role="Software Engineer", since="2020" **Connection Patterns** - Person -> Organization (WORKS_AT, FOUNDED, OWNS) - Person -> Person (KNOWS, MANAGES, MARRIED_TO) - Person -> Skill (HAS_SKILL) - Person -> Place (LIVES_IN, FROM) - Project -> Person (LED_BY, INVOLVES) - Event -> Person (ATTENDED_BY, ORGANIZED_BY)`, labels: `## Common Memory Labels Use these labels when creating memories (always use lowercase): **People & Living Things** - person: Individual people - animal: Pets, wildlife - plant: Trees, flowers, crops **Places & Locations** - place: General locations - organization: Companies, institutions - vehicle: Cars, planes, boats **Concepts & Activities** - project: Work or personal projects - event: Meetings, conferences, celebrations - topic: Subjects of interest - activity: Sports, hobbies - skill: Abilities and expertise **Objects & Media** - object: Physical items - food: Meals, ingredients - media: Books, movies, music - document: Files, reports - tool: Software, hardware **Abstract Concepts** - idea: Thoughts, concepts - goal: Objectives, targets - task: To-dos, assignments - habit: Routines, behaviors - health: Medical, wellness`, relationships: `## Common Relationship Types Use UPPERCASE for relationship types: **Personal Relationships** - KNOWS: General acquaintance - FRIENDS_WITH: Close friendship - MARRIED_TO: Spouse relationship - FAMILY_OF: Family connection **Professional Relationships** - WORKS_AT: Employment - WORKS_ON: Project involvement - COLLABORATES_WITH: Working together - MANAGES: Leadership role - REPORTS_TO: Reporting structure - OWNS: Ownership **Location Relationships** - LIVES_IN: Residence - LOCATED_IN: Physical location - VISITED: Past visits - FROM: Origin **Skill & Knowledge** - HAS_SKILL: Possesses ability - TEACHES: Instructing others - LEARNS_FROM: Student relationship **Project & Creation** - LEADS: Project leadership - PARTICIPATES_IN: Involvement - CREATED: Authorship - USES: Utilization`, 'best-practices': `## Best Practices **CRITICAL: Always Create Connections** - Isolated memories have limited value - ALWAYS look for connections - When storing new information, immediately think: "What does this relate to?" - A memory without connections is like a book with no catalog entry - The graph becomes exponentially more useful with each connection **Creating Memories - ALWAYS SEARCH FIRST** - **CRITICAL: Always search before creating** - memories often already exist - Search by name first: search_memories({query: "John Smith"}) - If multiple matches found, **ASK THE USER TO CONFIRM** which one they mean - Show distinguishing details: "I found 3 people named John: John Smith (Engineer at Google), John Smith (Doctor), John Smith (Teacher). Which one did you mean?" - If unsure about a match, describe it and ask: "I found John Smith who works at TechCorp. Is this the same person?" - Only create new memory after confirming it's not a duplicate - Always use lowercase for labels - Include a 'name' property for easy identification - 'created_at' is automatic if not provided - IMMEDIATELY after creating, connect it to related memories **Building Connections** - After creating any memory, ask: "What existing memories relate to this?" - Create connections for: people→organizations, people→projects, people→skills - Add relationship properties for rich context (since, role, status) - One memory can have many connections - don't limit yourself **Searching** - Empty query string returns all memories - Use label parameter to filter by type - Increase depth to include more relationships (depth=2 or 3 for rich context) - Default limit is 10, max is 200 **Managing Relationships** - Use UPPERCASE for relationship types - Add properties to relationships for context (e.g., since, role) - Search for memory IDs before creating connections - Use list_memory_labels to see existing labels **Data Organization** - Keep labels simple and consistent - Reuse existing labels when possible - Add descriptive properties to memories - Use relationships instead of complex properties - Think in graphs: nodes (memories) + edges (relationships) = knowledge`, examples: `## Examples **Creating a Person (WITH SEARCH FIRST)** \`\`\` // ALWAYS search first to avoid duplicates const searchResult = search_memories({ query: "Alice Johnson" }) if (searchResult.length === 0) { // Only create if not found create_memory({ label: "person", properties: { name: "Alice Johnson", occupation: "Software Engineer", company: "Tech Corp" } }) } else { // Use existing memory ID: searchResult[0].memory._id } \`\`\` **Creating a Relationship** \`\`\` // First, find the IDs search_memories({ query: "Alice Johnson" }) search_memories({ query: "Tech Corp" }) // Then connect them create_connection({ fromMemoryId: 123, toMemoryId: 456, type: "WORKS_AT", properties: { role: "Senior Engineer", since: "2020-01-15" } }) \`\`\` **Handling Ambiguous Matches** \`\`\` // User says: "Add that Sarah works at Microsoft" const searchResult = search_memories({ query: "Sarah" }) // Found multiple matches - ASK USER TO CONFIRM if (searchResult.length > 1) { // Show options to user: // "I found 3 people named Sarah: // 1. Sarah Johnson (Marketing Manager at TechCorp) // 2. Sarah Chen (Data Scientist) // 3. Sarah Williams (Designer at StartupXYZ) // Which Sarah works at Microsoft?" } // If only one match but uncertain if (searchResult.length === 1) { // Confirm with user: // "I found Sarah Johnson who is a Marketing Manager at TechCorp. // Is this the Sarah who now works at Microsoft?" } \`\`\` **Searching with Depth** \`\`\` // Find all people and their connections search_memories({ query: "", label: "person", depth: 2, limit: 50 }) \`\`\` **Updating a Memory** \`\`\` update_memory({ nodeId: 123, properties: { occupation: "Lead Engineer", skills: ["Python", "Neo4j", "MCP"] } }) \`\`\``, }; if (!topic) { // Return all sections return `# Neo4j Agent Memory Guidance ${sections.connections} ${sections.labels} ${sections.relationships} ${sections['best-practices']} ${sections.examples}`; } const content = sections[topic as keyof typeof sections]; if (content) { return content; } return `Unknown topic: '${topic}'. Available topics: connections, labels, relationships, best-practices, examples, or leave empty for all guidance.`; }
• src/tools/guidance-tool.ts:3-16 (schema)

  Tool definition object including the input schema for validating get_guidance arguments.
  export const guidanceTool: Tool = { name: 'get_guidance', description: 'Get help on using the memory tools effectively', inputSchema: { type: 'object', properties: { topic: { type: 'string', description: 'Topic: connections, labels, relationships, best-practices, examples, or leave empty for all', }, }, required: [], }, };
• src/tools/guidance-tool.ts:277-285 (schema)

  TypeScript interface and type guard function for input validation of get_guidance arguments.
  export interface GetGuidanceArgs { topic?: string; } export function isGetGuidanceArgs(args: unknown): args is GetGuidanceArgs { if (typeof args !== 'object' || args === null) return true; // Allow empty args const obj = args as Record<string, unknown>; return obj.topic === undefined || typeof obj.topic === 'string'; }
• src/tools/definitions.ts:10-183 (registration)

  The tools array where get_guidance is registered via inclusion of the guidanceTool object.
  export const tools: Tool[] = [ { 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: [], }, }, { name: 'create_memory', description: 'Create a new memory in the knowledge graph. Consider that the memory might already exist, so Search → Create → Connect (its important to try and connect memories)', inputSchema: { type: 'object', properties: { label: { type: 'string', description: 'Memory label in lowercase (use list_memory_labels first to check existing labels for consistency) - common: person, place, organization, project, event, topic, object, animal, plant, food, activity, media, skill, document, meeting, task, habit, health, vehicle, tool, idea, goal', }, properties: { type: 'object', description: 'Information to store about this memory (use "name" as primary identifier, e.g. {name: "John Smith", age: 30, occupation: "Engineer"})', additionalProperties: true, }, }, required: ['label', 'properties'], }, }, { name: 'create_connection', description: 'Create a connection between two memories (its good to have connected memories)', inputSchema: { type: 'object', properties: { fromMemoryId: { type: 'number', description: 'ID of the source memory', }, toMemoryId: { type: 'number', description: 'ID of the target memory', }, type: { type: 'string', description: 'Relationship type such as KNOWS, WORKS_ON, LIVES_IN, HAS_SKILL, PARTICIPATES_IN', }, properties: { type: 'object', description: 'Optional relationship metadata (e.g. {since: "2023-01", role: "Manager", status: "active"})', additionalProperties: true, }, }, required: ['fromMemoryId', 'toMemoryId', 'type'], }, }, { name: 'update_memory', description: 'Update properties of an existing memory such as adding more detail or make a change when you find out something new', inputSchema: { type: 'object', properties: { nodeId: { type: 'number', description: 'ID of the memory to update', }, properties: { type: 'object', description: 'Properties to update/add', additionalProperties: true, }, }, required: ['nodeId', 'properties'], }, }, { name: 'update_connection', description: 'Update properties of an existing connection between memories', inputSchema: { type: 'object', properties: { fromMemoryId: { type: 'number', description: 'ID of the source memory', }, toMemoryId: { type: 'number', description: 'ID of the target memory', }, type: { type: 'string', description: 'Relationship type to identify which connection to update (e.g. WORKS_AT, KNOWS, MANAGES)', }, properties: { type: 'object', description: 'Properties to update/add (e.g. {status: "completed", end_date: "2024-01"})', additionalProperties: true, }, }, required: ['fromMemoryId', 'toMemoryId', 'type', 'properties'], }, }, { 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'], }, }, { name: 'delete_connection', description: 'Delete a specific connection between two memories (use with caution - this permanently removes the relationship)', inputSchema: { type: 'object', properties: { fromMemoryId: { type: 'number', description: 'ID of the source memory', }, toMemoryId: { type: 'number', description: 'ID of the target memory', }, type: { type: 'string', description: 'Exact relationship type to delete (e.g. WORKS_AT, KNOWS, MANAGES)', }, }, required: ['fromMemoryId', 'toMemoryId', 'type'], }, }, { name: 'list_memory_labels', description: 'List all unique memory labels currently in use with their counts (useful for getting an overview of the knowledge graph)', inputSchema: { type: 'object', properties: {}, required: [], }, }, guidanceTool, ];
• src/handlers/index.ts:321-336 (handler)

  The switch case dispatcher in the main tool handler that validates arguments and calls the getGuidanceContent function for get_guidance.
  case 'get_guidance': { if (!isGetGuidanceArgs(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid get_guidance arguments'); } const content = getGuidanceContent(args.topic); return { content: [ { type: 'text', text: content, }, ], }; }