What is Mcp Neo4j Memory Server

mcp-neo4j-memory-server is a Model Context Protocol (MCP) server that utilizes Neo4j as a backend for storing and retrieving knowledge graphs, facilitating efficient knowledge management.

Use cases

Use cases include building intelligent chatbots that can recall user-specific information, creating applications for data-driven decision-making, and enhancing knowledge management systems in enterprises.

How to use

To use mcp-neo4j-memory-server, install it via NPM or Docker. Configure the Neo4j connection using environment variables, then interact with it through AI assistants that support the MCP protocol by following specific user interaction steps.

Key features

Key features include seamless integration with Neo4j for knowledge graph storage, customizable connection settings via environment variables, and support for AI interactions through the MCP protocol.

Where to use

mcp-neo4j-memory-server can be used in various domains such as artificial intelligence, data analysis, and knowledge management, where structured data representation and retrieval are essential.

Neo4j Memory Server

A Model Context Protocol (MCP) server that provides AI assistants with persistent, intelligent memory capabilities using Neo4j’s graph database with unified architecture

What it does

This server enables AI assistants to:

• Remember - Store memories as interconnected knowledge nodes with observations and metadata
• Search - Find relevant memories using semantic vector search, exact matching, and graph traversal
• Connect - Create meaningful relationships between memories with batch operations and cross-references
• Organize - Separate memories by project using different databases
• Evolve - Track how knowledge develops over time with temporal metadata and relationship networks

Features

Core Capabilities

• 🧠 Graph Memory - Memories as nodes, relationships as edges, observations as content
• 🔍 Unified Search - Semantic vectors, exact matching, wildcards, and graph traversal in one tool
• 🔗 Smart Relations - Typed connections with strength, source tracking, and temporal metadata
• 📊 Multi-Database - Isolated project contexts with instant switching

Advanced Operations

• ⚡ Batch Operations - Create multiple memories with relationships in single request using localId
• 🎯 Context Control - Response detail levels: minimal (lists), full (complete data), relations-only
• 📅 Time Queries - Filter by relative (“7d”, “30d”) or absolute dates on any temporal field
• 🌐 Graph Traversal - Navigate networks in any direction with depth control

Architecture

• 🚀 MCP Native - Seamless integration with Claude Desktop and MCP clients
• 💾 Persistent Storage - Neo4j graph database with GDS plugin for vector operations
• ⚠️ Zero-Fallback - Explicit errors for reliable debugging, no silent failures

Technical Highlights

• Built on Neo4j for scalable graph operations
• Vector embeddings using sentence transformers (384 dimensions)
• Clean architecture with domain-driven design
• Supports GDS plugin for advanced vector operations (necessary)
• Unified Architecture - 4 comprehensive tools for complete memory operations

Quick Start

npm install @sylweriusz/mcp-neo4j-memory-server

Add to Claude Desktop config:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@sylweriusz/mcp-neo4j-memory-server"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Neo4j Setup

Working setup: DozerDB with GDS Plugin

For the database, use DozerDB with the Graph Data Science plug-in, GDS is not only recommended but necessary:

For current installation instructions, see: https://dozerdb.org/

Example setup:

# Run DozerDB container with latest version
docker run \
    -p 7474:7474 -p 7687:7687 \
    -v $HOME/neo4j/data:/data \
    -v $HOME/neo4j/logs:/logs \
    -v $HOME/neo4j/plugins:/plugins \
    --env NEO4J_AUTH=neo4j/password \
    --env NEO4J_dbms_security_procedures_unrestricted='gds.*' \
    graphstack/dozerdb:latest

# Install GDS plugin - see dozerdb.org for current instructions

# Verify GDS plugin works
# In Neo4j Browser (http://localhost:7474):
# RETURN gds.similarity.cosine([1,2,3], [2,3,4]) as similarity

Unified Tools

The server provides 4 unified MCP tools that integrate automatically with Claude:

• memory_store - Create memories with observations and immediate relations in ONE operation
• memory_find - Unified search/retrieval with semantic search, direct ID lookup, date filtering, and graph traversal
• memory_modify - Comprehensive modification operations (update, delete, observations, relations)
• database_switch - Switch database context for isolated environments

Memory Structure

{
  "id": "dZ$abc123",
  "name": "Project Alpha",
  "memoryType": "project",
  "metadata": {
    "status": "active",
    "priority": "high"
  },
  "observations": [
    {
      "id": "dZ$obs456",
      "content": "Started development",
      "createdAt": "2025-06-08T10:00:00Z"
    }
  ],
  "related": {
    "ancestors": [
      {
        "id": "dZ$def789",
        "name": "Initiative",
        "relation": "PART_OF",
        "distance": 1
      }
    ],
    "descendants": [
      {
        "id": "dZ$ghi012",
        "name": "Task",
        "relation": "INCLUDES",
        "distance": 1
      }
    ]
  }
}

System Prompt

The simplest use of the memory tool, the following usually is more than enough.

## Memory Tool Usage
- Store all memory for this project in database: 'project-database-name'
- Use MCP memory tools exclusively for storing project-related information
- Begin each session by:
  1. Switching to this project's database
  2. Searching memory for data relevant to the user's prompt

Troubleshooting

Vector Search Issues:

• Check logs for [VectorSearch] GDS Plugin detected
• GDS Plugin requires DozerDB setup (see Neo4j Setup section)

Connection Issues:

• Verify Neo4j is running: docker ps
• Test connection: curl http://localhost:7474
• Check credentials in environment variables

License

MIT