结合 Claude Code、Graphiti 和 Neo4j 构建 Agent 长记忆系统

安装与配置

安装 Neo4j Desktop： 从 Neo4j 官方网站下载并安装。Neo4j Desktop 提供直观的界面来管理本地数据库，适合入门使用。安装完成后启动它。

创建数据库实例并设置密码： 在 Neo4j Desktop 中创建一个新的本地图数据库（版本 5.x 或更高）。首次启动数据库时，系统会提示设置 neo4j 用户的密码。记住这个密码；Neo4j 的默认 Bolt 连接 URI 是 bolt://localhost:7687，Graphiti 将通过此 URI 连接。

克隆 Graphiti 并配置环境： 打开终端，克隆 Graphiti 仓库并进入目录：

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

仓库中提供了 .env.example 模板。复制为 .env 并填写 Neo4j 和 OpenAI 配置：

OPENAI_API_KEY=<你的OpenAI API密钥>
MODEL_NAME=gpt-4.1-mini        # 指定LLM模型名称，例如 OpenAI 的 GPT-4 mini 版本
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=<你的Neo4j密码>

OPENAI_API_KEY 是 Graphiti 调用 OpenAI 进行 LLM 推理和生成嵌入所用。MODEL_NAME 指定要使用的 OpenAI 模型（例如 gpt-3.5-turbo 或 gpt-4 系列；默认使用 GPT-4.1 mini）。在 Neo4j 部分填写上面创建的数据库连接信息和凭证。

安装所需工具： 需要三个工具：

uv： Graphiti 推荐使用 Astral 开发的 uv 工具来管理 Python 环境和依赖。通过 pip install uv 安装，然后在 graphiti/mcp_server 目录下执行 uv sync 从项目锁定文件安装依赖。如果不使用 uv，可以手动创建虚拟环境并运行 pip install -r requirements.txt。
uvicorn： 如果打算通过 HTTP SSE 方式运行服务，需要安装 ASGI 服务器 uvicorn（通常已在依赖中）。确保命令行下可以调用它。
claude-cli： 安装 Claude 命令行工具（例如 pip install anthropic；具体见 Anthropic 文档）。安装后应能运行 claude 命令来管理 MCP 服务器。

启动 Graphiti MCP Server 并在 Claude 中注册： Graphiti 包含 MCP Server 实现。有两种启动方式：

方法 A—通过 Claude CLI（stdio 模式）： 这种方式将 Graphiti 作为 Claude 的子进程，通过 stdin/stdout 通信。使用以下命令注册插件：

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": "<你的OpenAI密钥>",
    "MODEL_NAME": "gpt-4.1-mini",
    "NEO4J_URI": "bolt://localhost:7687",
    "NEO4J_USER": "neo4j",
    "NEO4J_PASSWORD": "<你的Neo4j密码>"
  }
}'

将路径和参数替换为实际值（uv 可执行路径、Graphiti 仓库位置等）。执行后，Claude 会注册一个名为 "graphiti-memory" 的 MCP 插件，并在需要内存操作时自动启动服务器。

方法 B—独立服务（SSE 模式）： 将 Graphiti 作为独立服务运行，通过 HTTP Server-Sent Events 访问。执行：

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

这会在 0.0.0.0:8000 上以 SSE 模式启动 Graphiti MCP Server。成功启动后，用以下命令注册到 Claude：

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

--scope user 标志使该插件对你的用户账户全局可用（用 --scope project 可指定为项目范围）。完成后，会在 Claude Code 的 MCP Servers 列表中看到 "graphiti-memory"。

安装配置完成后，Claude Agent 就拥有了 Graphiti 知识图谱作为长期持久化记忆。接下来可以与 Claude 对话、记录信息并验证内存功能。

验证与故障排查

要验证 Graphiti 是否正常工作，直接从 Neo4j 检查是否有写入的数据。打开 Neo4j Browser（Neo4j Desktop 内置），连接到你的数据库，执行以下 Cypher 查询：

MATCH (n:Episodic) RETURN n LIMIT 25;

Graphiti 将每条对话或信息片段存储为 "Episodic" 节点。如果看到节点列表，说明 Claude 已成功将内容存进 Neo4j。

如果未查询到任何 Episode 节点或 Graphiti 功能异常：

Bolt 连接问题： 确认 Graphiti MCP Server 能连接上 Neo4j 数据库。检查 .env 中的 NEO4J_URI 和端口是否正确（默认为 bolt://localhost:7687）。确保 Neo4j 已启动且防火墙未阻止本地 Bolt 连接。如果 Neo4j 使用非默认的数据库名称或用户名，也需要相应调整 Graphiti 配置。
OpenAI API Key： Graphiti 调用 OpenAI 模型提取实体并生成嵌入。如果提供的 API Key 无效或余额不足，Episode 解析和写入会失败。检查 Graphiti Server 的日志中是否有 OpenAI 错误或余额不足的信息。使用有效的 API Key 替换，或确保账户有足够额度。
Claude 插件启用： 确认 Graphiti MCP 插件已在 Claude 中启用。在 Claude Code 中，新添加的 MCP 服务器可能需要在对话界面中显式启用（例如在 Claude Desktop 中，检查对话窗口右上角的插件列表）。注意 Claude 默认不会自动调用 Resource 和 Prompt 类型的功能；见下一节的应对策略。

Graphiti MCP 接口的工作原理

Graphiti 提供三类 MCP 接口：Resources、Tools 和 Prompts。

Resources（资源） 从知识图谱或外部源检索信息，不修改数据。这些接口提供 Claude 访问历史信息的途径。例如 Graphiti 提供检索节点和事实的资源接口，支持时间感知的查询。

Tools（工具） 执行修改数据或外部环境的操作。Graphiti 的工具允许 Claude 将新知识写入图谱（例如通过 add_episode）并执行实时搜索和图操作。每当用户提供新信息，Claude 可以调用 Graphiti 的工具方法将其存为新节点，持续积累知识。

Prompts（提示模板） 是预定义的模板或工作流，封装了 Claude 和 Graphiti 之间的复杂交互模式，充当可重用的"技能脚本"。

在 Claude Desktop 目前的实现中，Tool 类型的接口可以根据对话上下文自动调用，但 Resources 和 Prompts 不会自动触发。Claude 不知道何时使用它们，除非你显式调用或附加它们。

实际使用策略

要让 Claude 可靠地利用 Graphiti 的长期记忆，需要一些引导：

用系统指令引导模型： 在对话开始时告诉 Claude Graphiti 记忆可用，并应在需要时先查询图谱。例如设定系统提示："请先搜索已有知识再回答"。
使用"引用"功能： 在 Claude Desktop 中，点击"+"号从 MCP Server 附加存储的记忆片段作为参考资料。
建立明确的对话约定： 通过显式提示鼓励 Claude 在遇到新的偏好或事实时调用 add_episode，在需要检索相关信息时调用 search_nodes 或 search_facts。这些显式提示能显著提高内存利用率。

调试 Graphiti 写入： 如果对话内容未写入 Neo4j，检查 Graphiti MCP Server 的控制台输出。Graphiti 启动时会打印使用的模型名和 Group ID；如果写入操作失败（例如 OpenAI 返回非预期的 JSON），异常跟踪会打印在日志中。为了隔离问题，可尝试直接调用 Graphiti 的 REST API 添加测试数据，或使用简短清晰的输入触发 add_episode。确保 .env 已加载（如有必要在启动命令中显式指定 --env-file .env）。如果 Graphiti 报告嵌入或 schema 错误，说明 LLM 输出不符合预期的 JSON 格式。

避免 schema 错误： Graphiti 要求 LLM 支持结构化输出以正确格式化实体关系。使用 OpenAI 的 GPT-4 或新版 GPT-3.5 等具备函数调用或严格 JSON 输出能力的模型。不支持结构化输出的模型可能无法解析响应且导致 Episode 写入失败（表现为日志报错 schema mismatch）。首次运行 Graphiti 会在 Neo4j 上创建必要的索引和约束；可忽略 "IndexAlreadyExists" 信息。调整 Graphiti 的实体或关系类型定义时，保持与 Neo4j 模式一致，避免模式不符导致的写入错误。

通过稳定配置这套工具链，Claude Code 与 Graphiti 和 Neo4j 能顺利集成，创建一个具备持久化长期记忆的 AI Agent。在实际使用中，应根据日志和对话表现持续优化提示策略，确保 Agent 既能记录用户提供的知识，也能在需要时准确想起并应用。