Neo4j Agent Memory Management MCP Server

Overview

This MCP (Model Context Protocol) server connects AI agents to a Neo4j-based knowledge graph to manage agent memory. Instead of keeping memory in opaque vectors or ephemeral caches, the server persists memory as graph nodes and relationships and exposes an MCP-compliant API for storing, retrieving, and pruning context. That enables agents to reason over structured facts and relationships while retaining fast similarity search for recent or semantically related memories.

Using Neo4j for memory gives two main advantages: 1) graph queries let agents answer relational questions (who, what, when, how related) without reconstructing context from raw text; 2) graph-native indices (including vector extensions) support scalable semantic search for relevant memories. The server is intended for developers building multi-turn agents, RAG pipelines, or personalization systems that need both semantic retrieval and structured relationship reasoning.

Features

• MCP-compatible HTTP API for storing and retrieving agent memory
• Persist memory as Neo4j nodes with metadata, timestamps, and namespaces
• Semantic similarity search via embedding vectors (integrates with embedding providers)
• Graph queries to discover relationships between memories, entities, and sessions
• Memory lifecycle controls: time-to-live (TTL), namespace scoping, and pruning
• Lightweight, container-friendly deployment (Docker / Docker Compose)
• Configurable Neo4j connection and embedding provider (OpenAI or other)
• Example client usage and ready-to-integrate endpoints for agents

Installation / Configuration

Quick start using Docker Compose:

# docker-compose.yml
version: "3.8"
services:
  neo4j:
    image: neo4j:5.11.0
    environment:
      - NEO4J_AUTH=neo4j/testpassword
    ports:
      - "7474:7474"
      - "7687:7687"

  mcp-server:
    image: ghcr.io/knowall-ai/mcp-neo4j-agent-memory:latest
    environment:
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=testpassword
      - EMBEDDING_PROVIDER=openai
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    ports:
      - "8080:8080"
    depends_on:
      - neo4j

Environment variables (common)

Run locally:

# start services
docker compose up -d

# view logs
docker compose logs -f mcp-server

Available Tools / Resources

• REST API (MCP) endpoints:
  • POST /mcp/memory — store a memory item
  • POST /mcp/search — semantic search for memories
  • GET /mcp/memory/{id} — fetch a memory node by id
  • POST /mcp/query — execute a graph query across stored memories
  • POST /mcp/prune — run pruning policies (TTL, namespace)
• OpenAPI / Swagger: The server exposes an OpenAPI spec at /openapi.json and Swagger UI at /docs when enabled.
• Example clients: Minimal Python and Node.js snippets (see GitHub repo).
• GitHub: https://github.com/knowall-ai/mcp-neo4j-agent-memory

API Examples

Store a memory (curl):

curl -X POST "http://localhost:8080/mcp/memory" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sales-bot",
    "namespace": "user-123",
    "text": "User prefers email over phone.",
    "metadata": {"importance": 5}
  }'

Semantic search for relevant memories:

curl -X POST "http://localhost:8080/mcp/search" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sales-bot",
    "namespace": "user-123",
    "query": "How does this user prefer to be contacted?",
    "top_k": 5
  }'

Graph query example (find related memories about a topic):

curl -X POST "http://localhost:8080/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{
    "cypher": "MATCH (m:Memory)-[:RELATED_TO]->(e:Entity {name:$topic}) RETURN m LIMIT $limit",
    "params": {"topic":"pricing", "limit":10}
  }'

Use Cases

• Multi-turn conversational agents: Persist user-specific memories (preferences, past actions) so subsequent turns can combine semantic retrieval with explicit graph relations (e.g., “When did the user ask about refunds?”).
• Retrieval-Augmented Generation (RAG): Use semantic search to fetch relevant memory nodes, then expand retrieval with graph traversals to include related entities and context for better answers.
• Personalization: Store and query structured profile facts and behavioral memories; use TTL or pruning rules to forget stale data while keeping important long-term items.
• Compliance and auditing: Memory items are stored in Neo4j with metadata and timestamps, enabling traceability and selective removal according to data governance policies.
• Complex reasoning: Leverage relationships (edges) to infer indirect connections (e.g., customer -> product interest -> support tickets) without rebuilding knowledge from raw text each time.

Getting Help and Contributing

Refer to the repository for issues, feature requests, and contribution guidelines: https://github.com/knowall-ai/mcp-neo4j-agent-memory. Look for example agent integrations and community patterns in the repo to speed adoption.