Neo4j Agent Memory MCP Server

A specialized MCP server that bridges Neo4j graph database with AI agents, providing memory-focused tools for storing, recalling, and connecting information in a knowledge graph.

Quick Start 🚀

You can run this MCP server directly using npx:

Or add it to your Claude Desktop configuration:

Features

• 🧠 Persistent Memory Storage - Store and retrieve memories across conversations

• 🔗 Semantic Relationships - Create meaningful connections between memories (KNOWS, WORKS_AT, CREATED, etc.)

• 🔍 Intelligent Search - Natural language search across all memory properties and relationships

• 🏷️ Flexible Labeling - Use any label for memories (person, place, project, idea, etc.)

• ⏰ Temporal Tracking - Automatic timestamps and date-based queries

• 🌐 Graph Exploration - Traverse relationships to discover connected information

• 🎯 Context-Aware - Search with depth to include related memories

• 🔧 LLM-Optimized - Simple tools that let the AI handle the complexity

• 🏢 Enterprise Ready - Supports multiple Neo4j databases

• 📚 Built-in Guidance - Get help on best practices and usage patterns

Philosophy: LLM-Driven Intelligence

Unlike traditional approaches that embed complex logic in tools, this server provides simple, atomic operations and lets the LLM handle all the intelligence:

• No hidden logic: Tools do exactly what they say - no auto-disambiguation or smart matching

• LLM decides everything: Entity recognition, relationship inference, and conflict resolution

• Transparent operations: Every action is explicit and predictable

• Maximum flexibility: The LLM can implement any strategy without tool limitations

Search Behavior

The search_memories tool uses word tokenization:

• Query "John Smith" finds memories containing "John" OR "Smith"

• This returns more results, letting the LLM pick the most relevant

• Better than exact substring matching for names and multi-word queries

This approach makes the system more powerful and adaptable, as improvements in LLM capabilities directly translate to better memory management.

Neo4j Enterprise Support

This server now supports connecting to specific databases in Neo4j Enterprise Edition. By default, it connects to the "neo4j" database, but you can specify a different database using the NEO4J_DATABASE environment variable.

Memory Tools

• search_memories: Search and retrieve memories from the knowledge graph

  • Word-based search: Searches for ANY word in your query (e.g., "Ben Weeks" finds memories containing "Ben" OR "Weeks")

  • Natural language search across all memory properties (or leave empty to get all)

  • Filter by memory type (person, place, project, etc.)

  • Filter by date with since_date parameter (ISO format)

  • Control relationship depth and result limits

  • Sort by any field (created_at, name, etc.)

• create_memory: Create a new memory in the knowledge graph

  • Flexible type system - use any label in lowercase (person, place, project, skill, etc.)

  • Store any properties as key-value pairs

  • Automatic timestamps for temporal tracking

• create_connection: Create relationships between memories

  • Link memories using semantic relationship types (KNOWS, WORKS_AT, LIVES_IN, etc.)

  • Add properties to relationships (since, role, status, etc.)

  • Build complex knowledge networks

• update_memory: Update properties of existing memories

  • Add or modify any property

  • Set properties to null to remove them

• update_connection: Update relationship properties

  • Modify relationship metadata

  • Track changes over time

• delete_memory: Remove memories and all their connections

  • Use with caution - permanent deletion

  • Automatically removes all relationships

• delete_connection: Remove specific relationships

  • Precise relationship removal

  • Keeps the memories intact

• list_memory_labels: List all unique memory labels in use

  • Shows all labels with counts

  • Helps maintain consistency

  • Prevents duplicate label variations

• get_guidance: Get help on using the memory tools effectively

  • Topics: labels, relationships, best-practices, examples

  • Returns comprehensive guidance for LLMs

  • Use when uncertain about label/relationship naming

Prerequisites

1. Neo4j Database (v4.4+ or v5.x)

   • Install Neo4j Community or Enterprise Edition

   • Download from neo4j.com/download

   • Or use Docker: docker run -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j

2. Node.js (v18 or higher)

   • Required to run the MCP server

   • Download from nodejs.org

3. Claude Desktop (for MCP integration)

   • Download from claude.ai/download

Installation

Installing via Smithery

To install Neo4j Agent Memory MCP Server for Claude Desktop automatically via Smithery:

For Development

1. Clone the repository:

2. Install dependencies:

3. Build the project:

Configuration

Environment Variables

The server requires the following environment variables:

• NEO4J_URI: Neo4j database URI (required, e.g., bolt://localhost:7687)

• NEO4J_USERNAME: Neo4j username (required)

• NEO4J_PASSWORD: Neo4j password (required)

• NEO4J_DATABASE: Neo4j database name (optional) - For Neo4j Enterprise with multiple databases

Setting up Environment Variables

For Development

Copy .env.example to .env and update with your credentials:

For Claude Desktop

Add the environment variables to your Claude Desktop configuration (see Quick Start above).

Usage Examples

The LLM handles all the complexity of deciding what to store and how to connect memories:

Storing Information

Retrieving Information

Building Relationships

Connecting to a Specific Database

For Neo4j Enterprise users with multiple databases, you can specify which database to connect to:

This will connect to "myCustomDatabase" instead of the default "neo4j" database.

More Complex Examples

Finding Related Information

Creating Domain-Specific Memories

Managing Relationships

Advanced Queries

The LLM can handle complex queries by intelligently using the search tools:

Word-Based Search

Note: The search finds ANY word from your query, allowing the LLM to present all potentially relevant results and identify the best match based on context.

Recent Memories (Last 7 Days)

Disambiguation

Temporal Queries

Flexible Memory Types

The system doesn't enforce strict types - you can create any type of memory that makes sense:

Common Types (lowercase): person, place, organization, project, event, topic, object, animal, plant, food, activity, media, skill, document, meeting, task, habit, health, vehicle, tool, idea, goal

But you can use any type (lowercase): recipe, dream, memory, quote, book, movie, emotion, relationship, appointment, medication, exercise, symptom, payment, contract, etc.

The LLM will intelligently reuse existing types when appropriate to maintain consistency.

The Power of Connections

The true value of this memory system lies not just in storing individual memories, but in creating connections between them. A knowledge graph becomes exponentially more useful as you build relationships:

Why Connections Matter

• Context Discovery: Connected memories provide rich context that isolated facts cannot

• Relationship Patterns: Reveal hidden patterns and insights through relationship analysis

• Temporal Understanding: Track how relationships evolve over time

• Network Effects: Each new connection increases the value of existing memories

Best Practices for Building Connections

1. Always look for relationships when storing new information:

   Bad: Just store "John is a developer" Good: Store John AND connect him to his company, projects, skills, and colleagues

2. Use semantic relationship types that capture meaning:

   WORKS_AT, MANAGES, KNOWS, LIVES_IN, CREATED, USES, LEARNED_FROM

3. Add relationship properties for richer context:

   create_connection({ "fromMemoryId": 123, "toMemoryId": 456, "type": "WORKS_ON", "properties": {"role": "Lead", "since": "2023-01", "hours_per_week": 20} })

4. Think in graphs: When recalling information, use depth > 1 to explore the network:

   search_memories({"query": "John", "depth": 3}) // Explores connections up to 3 hops away

Remember: A memory without connections is like a book in a library with no catalog - it exists, but its utility is limited. The more you connect your memories, the more intelligent and useful your knowledge graph becomes.

Testing

Run the test suite:

Interactive Testing with MCP Inspector

For interactive testing and debugging, use the MCP Inspector:

The inspector provides a web UI to:

• Test all available tools interactively

• See real-time request/response data

• Validate your Neo4j connection

• Debug tool parameters and responses

License

MIT