Building Agent Long-term Memory with Claude Code, Graphiti, and Neo4j

Installation and Setup

Install Neo4j Desktop: Download and install from the official Neo4j website. Neo4j Desktop provides an intuitive interface for managing local databases and is suitable for initial setup. Start it after installation.

Create a database instance and set the password: In Neo4j Desktop, create a new local graph database (version 5.x or higher). When starting the database for the first time, you will be prompted to set a password for the neo4j user. Remember this password; Neo4j's default Bolt connection URI is bolt://localhost:7687, which Graphiti will use to connect.

Clone Graphiti and configure the environment: Open a terminal, clone the Graphiti repository, and enter the directory:

git clone https://github.com/getzep/graphiti.git
cd graphiti/mcp_server

The repository includes a .env.example template. Copy it to .env and fill in your Neo4j and OpenAI configuration:

OPENAI_API_KEY=<your OpenAI API key>
MODEL_NAME=gpt-4.1-mini        # Specify LLM model name, such as OpenAI's GPT-4 mini version
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=<your Neo4j password>

OPENAI_API_KEY is used by Graphiti to call OpenAI for LLM inference and embeddings. MODEL_NAME specifies which OpenAI model to use (e.g., gpt-3.5-turbo or gpt-4 series; the default uses GPT-4.1 mini). Fill in the Neo4j section with the connection details and credentials you created above.

Install required tools: Three tools are needed:

uv: Graphiti recommends the uv tool (by Astral) for managing Python environments and dependencies. Install it with pip install uv, then run uv sync in the graphiti/mcp_server directory to install dependencies from the project lock file. If you prefer not to use uv, create a virtual environment manually and run pip install -r requirements.txt.
uvicorn: If you plan to run the service via HTTP SSE, install the ASGI server uvicorn (usually already in dependencies). Ensure it can be called from the command line.
claude-cli: Install the Claude command-line tool (e.g., pip install anthropic; see Anthropic documentation for details). After installation, you should be able to run claude commands to manage MCP servers.

Start Graphiti MCP Server and register it with Claude: Graphiti includes an MCP Server implementation. Two startup methods are available:

Method A—via Claude CLI (stdio mode): This runs Graphiti as a subprocess of Claude, communicating via stdin/stdout. Register the plugin with:

claude mcp add-json graphiti-memory '{
  "type": "stdio",
  "command": "/usr/local/bin/uv",
  "args": [
    "run", "--directory", "/path/to/graphiti/mcp_server", 
    "graphiti_mcp_server.py", "--transport", "stdio"
  ],
  "env": {
    "OPENAI_API_KEY": "<your OpenAI key>",
    "MODEL_NAME": "gpt-4.1-mini",
    "NEO4J_URI": "bolt://localhost:7687",
    "NEO4J_USER": "neo4j",
    "NEO4J_PASSWORD": "<your Neo4j password>"
  }
}'

Replace paths and parameters with actual values (uv executable path, Graphiti repository location, etc.). After execution, Claude registers an MCP plugin called "graphiti-memory" and automatically starts the server when memory operations are needed.

Method B—independent service (SSE mode): Run Graphiti as a standalone service accessible via HTTP Server-Sent Events. Execute:

cd graphiti/mcp_server
uv run graphiti_mcp_server.py --transport sse --model gpt-4.1-mini

This starts Graphiti MCP Server in SSE mode on 0.0.0.0:8000. After successful startup, register it with Claude:

claude mcp add --transport sse --scope user graphiti-memory http://localhost:8000/sse

The --scope user flag makes the plugin globally available for your user account (use --scope project for project-specific registration). After completion, you will see "graphiti-memory" in Claude Code's MCP Servers list.

Once installation and configuration are complete, Claude Agent has Graphiti's knowledge graph available as long-term persistent memory. You can now test the integration with Claude by recording information and verifying memory functionality.

Verification and Troubleshooting

To verify that Graphiti is working, check Neo4j directly for written data. Open Neo4j Browser (built into Neo4j Desktop), connect to your database, and execute this Cypher query:

MATCH (n:Episodic) RETURN n LIMIT 25;

Graphiti stores each conversation or information fragment as an "Episodic" node. If you see a list of nodes, Claude has successfully stored content in Neo4j.

If no Episode nodes appear or Graphiti is not functioning:

Bolt connection issues: Verify that Graphiti MCP Server can reach the Neo4j database. Check that the NEO4J_URI and port in .env are correct (bolt://localhost:7687 by default). Ensure Neo4j is running and no firewall blocks local Bolt connections. If Neo4j uses a non-default database name or username, update Graphiti's configuration accordingly.
OpenAI API Key: Graphiti calls OpenAI models to extract entities and generate embeddings. If your API Key is invalid or lacks sufficient balance, Episode parsing and writing will fail. Check the Graphiti Server logs for OpenAI errors or insufficient balance messages. Replace the API Key with a valid one or ensure your account has sufficient quota.
Claude plugin enablement: Confirm that the Graphiti MCP plugin is enabled in Claude. In Claude Code, new MCP servers may require explicit enabling in the conversation interface (e.g., in Claude Desktop, check the plugins list in the upper right corner of the conversation window). Note that Claude does not automatically call Resource and Prompt type functionality by default; see the next section for strategies to work around this.

How Graphiti's MCP Interfaces Work

Graphiti provides three types of MCP interface: Resources, Tools, and Prompts.

Resources retrieve information from the knowledge graph or external sources without modifying data. These provide Claude with access to historical information. For example, Graphiti offers resource interfaces for retrieving nodes and facts with time-aware queries.

Tools execute operations that modify data or the external environment. Graphiti's tools allow Claude to write new knowledge to the graph (e.g., via add_episode) and perform real-time searches and graph operations. Each time users provide new information, Claude can call Graphiti's tool methods to store it as new nodes, continuously accumulating knowledge.

Prompts are predefined templates or workflows that encapsulate complex interaction patterns between Claude and Graphiti, functioning as reusable "skill scripts."

In Claude Desktop's current implementation, Tool-type interfaces can be automatically called based on conversation context, but Resources and Prompts are not automatically triggered. Claude does not know when to use them unless you actively invoke them or attach them.

Practical Usage Strategies

To make Claude reliably use Graphiti's long-term memory, some guidance is needed:

Prime the model with system instructions: At the beginning of conversations, tell Claude that Graphiti memory is available and should be queried first when needed. For example, set a system prompt like: "Please search existing knowledge before answering."
Use the References feature: In Claude Desktop, click the "+" sign to attach stored memory fragments from MCP Server as reference materials.
Establish clear conversation conventions: Use explicit prompts to encourage Claude to call add_episode whenever it encounters new preferences or facts, and to call search_nodes or search_facts whenever it needs to retrieve relevant information. These explicit prompts significantly improve memory utilization.

Debugging Graphiti writes: If conversation content is not written to Neo4j, check the console output of Graphiti MCP Server. Graphiti prints the model name and Group ID at startup; if write operations fail (e.g., OpenAI returns unexpected JSON), exception traces appear in the logs. For isolated debugging, try calling Graphiti's REST API directly to add test data, or use short, clearly structured inputs to trigger add_episode. Ensure .env is loaded (explicitly specify --env-file .env in the startup command if needed). If Graphiti reports embedding or schema errors, the LLM output likely does not conform to the expected JSON schema.

Avoiding schema errors: Graphiti requires that the LLM supports structured output to format entity relationships correctly. Use OpenAI's GPT-4 or newer GPT-3.5 models with function calling or strict JSON output capabilities. Models without structured output support may fail to parse responses and write episodes (manifest as logs reporting schema mismatch). On first run, Graphiti creates necessary indexes and constraints on Neo4j; you can ignore "IndexAlreadyExists" messages. When modifying Graphiti's entity or relationship type definitions, keep them consistent with the Neo4j schema to avoid write errors due to schema mismatches.

With stable configuration of this toolchain, Claude Code integrates smoothly with Graphiti and Neo4j, creating an AI agent with persistent long-term memory. In practice, continually optimize prompt strategies based on logs and conversation performance to ensure the agent both records knowledge provided by users and accurately recalls and applies it when needed.