← Back to Blog

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

下面总结基于实践的安装与配置流程：

  1. 安装 Neo4j Desktop：从 Neo4j 官方网站下载 Neo4j Desktop 并安装。Neo4j Desktop 提供直观的界面来管理本地数据库，非常适合入门 。安装完成后启动 Neo4j Desktop。
  2. 创建数据库实例并设置密码：在 Neo4j Desktop 中创建一个新的本地图数据库（版本需 5.x 或更高）。首次启动数据库时会要求设置一个密码，请设定Neo4j 用户（默认用户名为 neo4j）的密码，并牢记此信息。默认情况下，Neo4j 的 Bolt 连接 URI 为 bolt://localhost:7687，后续 Graphiti 将通过此 URI 连接数据库。
  3. 克隆 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 部分填写刚才创建数据库的连接信息和凭证。

  1. 安装所需工具（uv、uvicorn、claude-cli）：
  • uv：Graphiti 推荐使用 Astral 开发的 uv 工具来管理Python环境和依赖。先通过 pip install uv 安装 uv 。然后在 graphiti/mcp_server 目录下执行 uv sync，该命令会根据项目的锁定文件安装所需的Python包。uv 类似于 pip，但能更快速地同步依赖。若不使用 uv，也可以手动创建虚拟环境并使用 pip install -r requirements.txt 安装依赖。
  • uvicorn：如果打算通过 HTTP SSE 方式运行服务，需要安装 ASGI 服务器 uvicorn（通常已在依赖中）。确保命令行下可以调用 uvicorn（例如 pip install uvicorn）。
  • claude-cli：Claude Code 提供了命令行工具来管理 MCP 插件。安装 claude CLI 工具（例如通过 pip install anthropic 或其他途径，具体可参考 Anthropic 文档）。安装后，命令行应能使用 claude 命令，用于添加MCP服务器等配置 。
  1. 启动 Graphiti MCP Server 并在 Claude 中注册插件：Graphiti 仓库自带 MCP Server 实现，用于充当 Claude 等前端与 Graphiti 后端之间的桥梁。启动步骤有两种方式：
  • 方法A：通过 Claude Code CLI 启动（stdio 模式）：这种方式将 Graphiti MCP Server 作为 Claude 的子进程，通过标准输入输出通信。在命令行执行以下命令将 Graphiti 插件添加到 Claude Code（user范围）：
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 Code 会登记一个名为 “graphiti-memory” 的 MCP 插件，Claude 在对话中需要用到记忆时会自动启动该Server并通过 stdio 通信。

  • 方法B：独立运行 Graphiti Server（SSE 模式）：这种方式下 Graphiti 作为独立服务，通过 HTTP Server-Sent Events (SSE) 接口供 Claude 访问。可以执行：
cd graphiti/mcp_server
uv run graphiti_mcp_server.py --transport sse --model gpt-4.1-mini

上述命令将 Graphiti MCP Server 以 SSE 模式跑在本地（默认监听 0.0.0.0:8000）。成功启动后，使用 Claude CLI 将此服务添加为 MCP 插件：

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

这样Claude就注册了一个名为 “graphiti-memory” 的远程MCP服务（通过HTTP连接）。--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” 标签的节点，可通过该查询查看最新写入的若干 Episode 节点及其属性。如果能看到节点列表，说明 Claude 已成功将对话内容存进 Neo4j。

如果未能查询到任何 Episode 节点或 Graphiti 功能异常，建议从以下方面排查：

  • Bolt 连接问题：确认 Graphiti MCP Server 能连接上 Neo4j 数据库。检查 .env 配置的 NEO4J_URI 和端口是否正确，本地默认应为 bolt://localhost:7687。确保 Neo4j 数据库已启动且未设置防火墙阻止本地 Bolt 连接。如果 Neo4j 使用了非默认的数据库名称或用户名，也需要相应调整 Graphiti 配置。
  • OpenAI API Key 状态：Graphiti 在写入对话时，会调用 OpenAI 的模型来抽取实体和生成 embeddings 。如果提供的 API Key 无效或者余额不足，Graphiti 可能无法完成 Episode 的解析写入。可以查看运行 Graphiti Server 的终端输出日志，若出现 OpenAI 接口报错或余额不足的信息，则需要更换有效的 API Key（OpenAI 如开启数据分享可每日获得一定免费额度）或者确保账户有足够额度。
  • Claude 插件启用：确认 Graphiti MCP 插件已在 Claude 前端启用。在 Claude Code 中，新添加的 MCP Server 可能需要在对话界面中开启（如Claude Desktop中需要在对话窗口右上角“插件”列表里勾选启用）。如果插件未启用，Claude将不会实际调用 Graphiti。另请注意，Claude 对资源和提示类型的 MCP 功能默认不会自动触发调用 （详见下文），因此在测试时可以先提出与已记录内容相关的问题，看看 Claude 是否能够利用之前存储的记忆进行回答。

Graphiti Memory 的功能类别

作为 MCP Server，Graphiti 提供了三类接口能力，对应 MCP 定义的Resources、Tools 和 Prompts 三种类型 。理解这三者有助于发挥 Graphiti 内存的作用：

  1. Resources（资源工具）：用于检索信息的接口。如从内部知识图谱或外部数据库获取内容。这类接口只读数据不产生副作用，作用是让 LLM 访问知识库中的历史信息。例如 Graphiti 提供检索节点、事实的资源接口，支持时间感知的查询，可以按时间或条件获取过往对话片段 。Claude 在需要引用记忆时，可以调用 Resource 类型的功能读取相关内容。
  2. Tools（工具）：用于执行操作的接口，会对外部环境或数据产生变化。如通过 API 写入数据、进行计算等。Graphiti 的工具接口允许 LLM 将新的知识添加到图谱，或调用实时的搜索和图操作，实现在线更新记忆 。每当用户提供新信息，Claude Agent 可以调用 Graphiti 的工具类方法（如 add_episode）将其存为新节点，从而持续积累知识。
  3. Prompts（提示模板）：指预定义的提示词模板或工作流，方便 LLM 和 MCP Server 之间复用复杂交互逻辑。例如 Graphiti 可能提供某些查询的模板，封装常用的多步操作 。这些 Prompt 模板可以视作Agent的一些“技能脚本”，当触发特定需求时调用。通过 Prompts，开发者可将标准查询模式固化，让 Claude 在需要时一键生成对 Graphiti 的查询请求。

需要注意，在 Claude Desktop 目前的实现中，Tools 类型的 MCP 接口（如Graphiti的写入/搜索功能）可以根据对话上下文自动调用，而 Resources 和 Prompts 类型则不会自动触发 。也就是说，即使 Graphiti 列出了可用的资源和提示模板，Claude 默认不知道何时用它们，除非用户主动附加。这一点在实际使用中尤为重要，下一节会讨论应对策略。

使用建议与踩坑记录

基于实际体验，这里总结一些使用Graphiti长记忆过程中值得注意的建议和可能遇到的坑：

  • 调试 Graphiti 写入：当发现对话内容没有写入Neo4j时，可以检查 Graphiti MCP Server 的控制台输出日志。Graphiti 启动时会打印使用的模型名、Group ID等信息，执行写入时如发生错误（例如 OpenAI 返回格式不符合预期），通常也会有异常堆栈打印在日志中。调试时，可尝试直接调用 Graphiti 的 API（例如 REST 接口）添加测试数据，或使用简短且结构清晰的输入触发 add_episode，以隔离问题。确保 .env 已正确加载（可以在启动命令中显式指定 --env-file .env 以防万一）。如果 Graphiti 提示embedding或解析schema错误，通常是模型输出不符合预期 JSON 格式导致的。
  • 避免 Schema 错误：Graphiti 要求所使用的 LLM 支持结构化输出，以确保提取实体关系时格式正确 。建议使用 OpenAI 的 GPT-4 或新版 GPT-3.5 等具备函数调用或严格JSON输出能力的模型。如果使用不支持结构化输出的模型（尤其是体量较小的模型），可能出现 Graphiti 无法解析返回内容、Episode 写入失败的情况（表现为日志报错 schema mismatch 等）。另外，第一次运行 Graphiti 会在 Neo4j 上创建所需索引和约束，如看到 IndexAlreadyExists 提示可忽略 。在调整 Graphiti 的实体/关系类型定义时，尽量保持与Neo4j模式一致，避免因为模式不符导致写入错误。
  • Claude 中正确触发 Memory：为了让 Claude 充分利用 Graphiti 长期记忆，需要在对话策略上进行一些引导。目前Claude对 Resource/Prompt 并非自动使用，因此用户或开发者需要主动触发。有几种实践技巧：其一，在对话最开始就提示Claude可以使用Graphiti记忆，并在需要时应先查询图谱。例如可以设定系统提示：“请先搜索已有知识再回答”。其二，熟练运用 Claude 界面提供的**“引用 (References)”** 功能：在 Claude Desktop 中，可点击“+”号从 MCP Server 附加存储的记忆片段作为参考资料 。其三，参考官方建议制定对话约定——例如 “先检索后回答” 和 “有新信息立即记录”。 上述规则可作为Claude的提示，让模型养成遇到新偏好/事实就调用 add_episode 保存，遇到问题先调用 search_nodes/search_facts 检索相关节点和关系的习惯。这种显式的提示能大大提高 Graphiti 内存的利用率。总之，目前需要一定人为引导，未来版本Claude可能会让AI自动意识到可用的记忆资源并调用。

通过以上工具链的稳定配置和调整，Claude Code 与 Graphiti + Neo4j 的集成可以顺利运行，一个具备长时记忆的 AI Agent 也就搭建完成了。在真实开发中，我们应不断根据日志和对话表现去优化提示策略，确保AI既“记得住”用户提供的知识，又能在需要时准确想起并加以利用。这套方案在复杂项目中能有效避免信息遗忘，大幅提升Agent长程任务的连贯性和智能水平。今后若Claude插件机制升级，实现自动利用Resource/Prompt，那么AI长记忆将更加得心应手。希望以上踩坑心得能帮助大家更容易地复现这一强大的长记忆Agent方案！