1. 为什么你的 AI 智能体总是“失忆”从 Graphiti MCP 服务器说起做 AI 智能体开发的朋友大概率都遇到过这个场景你精心调教了一个助手昨天它还记得你偏好用 TypeScript、项目部署在 Kubernetes 上、数据库选的是 PostgreSQL今天再问它它一脸茫然地反问你“请问您使用什么技术栈”。这不是模型变笨了而是它压根没有一套能持续演进、能处理矛盾、能追溯历史的长期记忆系统。传统做法是往向量库里塞对话摘要检索时做相似度匹配。这套方案在静态文档问答里够用但一旦数据频繁变化——比如用户改了偏好、订单状态更新、项目配置调整——向量库就露馅了旧信息和新信息同时被召回模型拿到互相矛盾的两段上下文输出自然开始胡言乱语。更麻烦的是你没法问它“上周三这个字段的值是什么”因为向量检索没有时间维度。Graphiti 这个框架就是冲着这个痛点来的。它把智能体的记忆组织成一张时间感知的知识图谱每个事实都是一个三元组比如用户A偏好语言TypeScript并且每条边都带双时间戳事件实际发生的时间以及数据被写入图谱的时间。这意味着你可以做精确的时间点查询也能在信息变更时让旧边失效而不是删除历史上下文完整保留。而Graphiti MCP 服务器是这套能力对外的接口层。MCP 全称 Model Context Protocol你可以把它理解成 AI 客户端Claude Desktop、Cursor、Cline 等和外部工具之间的标准插座。Graphiti 把知识图谱的增删改查、混合检索、实体管理封装成 MCP 工具客户端只要连上这个服务器就能像调用本地函数一样往图谱里写记忆、查记忆。对智能体来说这相当于外挂了一个可查询、可更新、带时间轴的“海马体”。这篇文章面向的是想给智能体加长期记忆的开发者尤其是已经在用 Claude Code、Cursor、Cline 这类工具的人。我会从零讲清楚怎么把 Graphiti MCP 服务器跑起来、怎么配置客户端接入、怎么写入和查询图谱数据、以及踩过的坑怎么排。全程给可复制的配置和命令你跟着做就能跑通。需要提前说明的是Graphiti 默认用 OpenAI 做 LLM 推理和嵌入但它的 LLM 客户端是 OpenAI 兼容的所以你可以把 Base URL 指向任何兼容端点。国内开发者如果直连官方端点有网络波动可以用 TaoToken 这类兼容网关做中转后面配置章节我会给出具体写法。整个链路不涉及任何违规网络操作纯粹是 API 端点替换。2. Graphiti MCP 服务器前置准备环境、依赖与 TaoToken 接入配置在动手写配置之前先把依赖关系理清楚。Graphiti MCP 服务器不是一个独立二进制它是 graphiti-core 这个 Python 包里的一个模块运行时会连接图数据库和 LLM 服务。所以你需要三样东西Python 运行环境、一个图数据库、一个能用的 LLM API 端点。Python 版本要求 3.10 或更高。图数据库方面官方支持 Neo4j 5.26、FalkorDB 1.1.2、Kuzu 0.11.2以及 Amazon Neptune。对本地开发来说最省事的是用 Docker 跑 FalkorDB一条命令起来不需要额外装 Neo4j Desktop。如果你已经熟悉 Neo4j用 Neo4j 也行MCP 服务器的配置里改一下 driver 类型即可。LLM 端点这块是重点。Graphiti 的数据摄取管道会调用 LLM 做实体抽取、关系抽取、矛盾检测还会调用嵌入模型做向量化。默认走 OpenAI需要OPENAI_API_KEY。但它的OpenAIGenericClient支持自定义base_url这就给了我们替换端点的空间。我实测下来用 TaoToken 的兼容端点接 Graphiti 是可行的。TaoToken 提供 OpenAI 兼容的 API 格式你只需要把 base_url 指向https://taotoken.net/apiapi_key 换成在控制台申请的 key模型 ID 填你套餐里可用的模型即可。这样做的好处是端点稳定、计费透明而且不用改 Graphiti 的任何源码纯配置层面解决。具体来说你需要准备三个值配置项值说明Base URLhttps://taotoken.net/apiOpenAI 兼容端点不加 UTMAPI Key控制台申请在 API Keys 页面创建Model ID如gpt-4o-mini等以套餐实际可用为准申请 key 的入口在 TaoToken 控制台的 API Keys 页面模型对话功能可以用来先验证 key 是否可用。如果你打算长期跑编码类 AgentCoding Plan 的额度更适合高频调用场景。环境变量层面Graphiti 读取的是标准 OpenAI 变量名所以你可以这样设置export OPENAI_API_KEY你的TaoToken Key export OPENAI_BASE_URLhttps://taotoken.net/api export SEMAPHORE_LIMIT10SEMAPHORE_LIMIT控制数据摄取的并发量默认 10。如果你用的模型端点对并发限制较严调低到 5如果端点吞吐充足可以调到 20 加快写入。这个值直接决定你往图谱里灌数据时的速度后面排障章节会展开。图数据库用 FalkorDB 的话先拉起来docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest然后安装带 FalkorDB 扩展的 graphiti-corepip install graphiti-core[falkordb]如果你用 Neo4j安装基础包即可Neo4j 驱动是内置的pip install graphiti-core到这里前置准备就完成了。核心就三件事Python 3.10、图数据库跑起来、LLM 端点配好。接下来进入 MCP 服务器的实际配置。3. 可复制的 Graphiti MCP 服务器配置JSON 与 TOML 片段MCP 服务器的配置分两部分服务器自身的运行参数以及客户端的接入配置。服务器端我推荐用 Docker Compose 管理把图数据库和 MCP 服务编排在一起避免手动起多个进程。先看服务器端的目录结构。graphiti 仓库里mcp_server目录包含服务器实现你需要把它 clone 下来或者用 pip 安装后找到模块路径。用 Docker 部署时官方提供了 compose 文件核心是三个服务neo4j或 falkordb、graphiti-mcp、以及可选的监控。下面是一份我调整过的docker-compose.yml把 LLM 端点指向了 TaoToken图数据库用 FalkorDBversion: 3.8 services: falkordb: image: falkordb/falkordb:latest ports: - 6379:6379 - 3000:3000 volumes: - falkordb_data:/data graphiti-mcp: image: graphiti/mcp-server:latest depends_on: - falkordb environment: - OPENAI_API_KEY${OPENAI_API_KEY} - OPENAI_BASE_URLhttps://taotoken.net/api - MODEL_NAMEgpt-4o-mini - SMALL_MODEL_NAMEgpt-4o-mini - DB_TYPEfalkordb - FALKORDB_HOSTfalkordb - FALKORDB_PORT6379 - SEMAPHORE_LIMIT10 ports: - 8000:8000 command: [python, -m, mcp_server] volumes: falkordb_data:注意OPENAI_BASE_URL这里填的是https://taotoken.net/api不带任何查询参数。MODEL_NAME和SMALL_MODEL_NAME都填你套餐里可用的模型 IDGraphiti 会用 small_model 做轻量任务用 model 做主推理。如果你不确定模型 ID可以先用模型对话页面测一下。客户端接入配置以 Claude Desktop 为例编辑claude_desktop_config.json{ mcpServers: { graphiti: { command: docker, args: [ exec, -i, graphiti-mcp, python, -m, mcp_server, --transport, stdio ], env: { OPENAI_API_KEY: 你的TaoToken Key, OPENAI_BASE_URL: https://taotoken.net/api, MODEL_NAME: gpt-4o-mini, DB_TYPE: falkordb, FALKORDB_HOST: localhost, FALKORDB_PORT: 6379 } } } }如果你用 Cursor配置位置在~/.cursor/mcp.json结构类似。Cline 的话在 VS Code 设置里找 MCP Servers 配置项格式也是 JSON。这里有个关键点MCP 服务器支持两种传输模式stdio 和 SSE。stdio 模式下客户端会启动一个子进程通过标准输入输出通信适合本地开发。SSE 模式下服务器监听一个 HTTP 端口客户端通过 URL 连接适合服务器部署。上面 Claude Desktop 的配置用的是 stdio通过docker exec进入已运行的容器执行命令。如果你想让 MCP 服务器独立跑在 8000 端口用 SSE 模式python -m mcp_server --transport sse --port 8000然后客户端配置里写url: http://localhost:8000/sse即可。配置写完后重启客户端在 Claude Desktop 里应该能看到 graphiti 这个 MCP 服务器已连接工具列表里会出现add_episode、search_nodes、search_facts、delete_episode等工具。到这一步接入就完成了。4. 验证请求与成功结果写入图谱、混合检索与时间点查询配置连上只是第一步真正要验证的是数据能不能写进去、能不能查出来、时间维度对不对。我按顺序给你三个验证步骤每步都有预期结果。第一步写入一条数据事件。在 Claude Desktop 里直接对话让它调用 graphiti 的add_episode工具请用 graphiti 的 add_episode 工具把这段文本写入知识图谱“张工在 2026 年 3 月 10 日将项目的数据库从 MySQL 迁移到了 PostgreSQL迁移原因是需要更好的 JSON 支持和并发性能。”如果配置正确Claude 会调用工具并返回类似这样的结果{ status: success, episode_id: ep_abc123, entities_extracted: 4, relations_extracted: 3, message: Episode added successfully }entities_extracted表示抽取出的实体数量relations_extracted是关系数量。如果这两个值是 0说明 LLM 端点没正常工作或者模型不支持结构化输出。Graphiti 对结构化输出有要求OpenAI 和 Gemini 系列支持较好小模型容易输出格式错误导致摄取失败。第二步查询关系。调用search_facts工具用 graphiti 搜索关于“数据库迁移”的事实。预期返回{ facts: [ { source: 张工, relation: 迁移了, target: PostgreSQL, valid_at: 2026-03-10T00:00:00Z, invalid_at: null, fact: 张工在2026年3月10日将项目数据库迁移到PostgreSQL } ] }注意valid_at和invalid_at这两个字段这就是双时间模型。valid_at是事实生效时间invalid_at是事实失效时间。如果后续有更新旧事实的invalid_at会被填上而不是被删除。第三步验证时间点查询。先再写入一条更新事件用 graphiti 写入“2026 年 4 月 1 日张工又把数据库从 PostgreSQL 换回了 MySQL因为团队更熟悉 MySQL 的运维。”然后再查一次“数据库迁移”的事实。这次应该返回两条{ facts: [ { source: 张工, relation: 迁移了, target: PostgreSQL, valid_at: 2026-03-10T00:00:00Z, invalid_at: 2026-04-01T00:00:00Z, fact: 张工在2026年3月10日将项目数据库迁移到PostgreSQL }, { source: 张工, relation: 迁移了, target: MySQL, valid_at: 2026-04-01T00:00:00Z, invalid_at: null, fact: 张工在2026年4月1日将数据库换回MySQL } ] }第一条的invalid_at被自动填上了 4 月 1 日表示这条事实在那天失效。这就是 Graphiti 处理矛盾的方式不删除只标记失效。你问“3 月 15 日数据库是什么”它能准确回答 PostgreSQL问“4 月 15 日是什么”它回答 MySQL。向量库做不到这一点。如果这三步都跑通了说明你的 Graphiti MCP 服务器已经正常工作智能体的长期记忆底座搭好了。接下来可以把它接到你的 Agent 循环里每轮对话结束调add_episode写入每轮开始调search_facts检索。5. 本篇常见错误排查401、local proxy failed、reading choices 与 OAuth配置过程中最容易卡住的就是报错。我把几个高频错误和对应解法列出来你对照着排查。401 Unauthorized。这个最直接key 不对或者没传。检查三处环境变量OPENAI_API_KEY是否设置、客户端配置里的 key 是否和服务器端一致、key 是否已过期。如果你用的是 TaoToken去控制台 API Keys 页面确认 key 状态是 active。还有一种情况是 base_url 写错了比如多加了/v1后缀。TaoToken 的端点是https://taotoken.net/api不要自己拼/v1/chat/completions客户端库会自动补路径。local proxy failed / connection refused。这个报错通常出现在 MCP 服务器连不上图数据库的时候。检查 FalkorDB 或 Neo4j 容器是否在运行端口是否映射正确。如果你在 Docker 里跑 MCP 服务器FALKORDB_HOST要填容器名如falkordb不能填localhost因为容器内的 localhost 指向容器自己。反过来如果 MCP 服务器跑在宿主机、数据库在容器里那FALKORDB_HOST填localhost端口填映射出来的 6379。Error reading choices / invalid response format。这个报错来自 LLM 返回的内容不符合预期结构。Graphiti 要求模型支持结构化输出如果你用的模型不支持 function calling 或 JSON mode就会报这个。解法有两个换支持结构化输出的模型或者在 LLMConfig 里关掉结构化输出要求但抽取质量会下降。我实测下来用 TaoToken 接入时选支持 JSON mode 的模型最稳。如果持续报这个错把SEMAPHORE_LIMIT降到 5 试试并发太高有时会导致响应截断。OAuth / authentication failed。如果你用的是 Claude Desktop 或 Cursor 的云端同步功能可能会遇到 OAuth 相关报错。这通常和 MCP 服务器本身无关是客户端在尝试用 OAuth 连接远程服务。检查你的客户端配置里是不是误开了远程 MCP 选项。本地 stdio 模式不需要 OAuth把配置里的 url 字段删掉只保留 command 和 args。图谱写入成功但查询为空。数据写进去了search_facts却返回空数组。这种情况多半是嵌入模型没配好。Graphiti 的混合检索依赖向量相似度如果嵌入调用失败向量索引就是空的关键词匹配可能也命中不了。检查OPENAI_BASE_URL是否对嵌入模型也生效。有些兼容端点对 chat 和 embeddings 走不同路径需要确认你的端点两者都支持。可以在模型对话页面之外单独用 curl 测一下 embeddings 接口。SEMAPHORE_LIMIT 相关性能问题。默认 10 并发如果你灌大量数据发现特别慢可以调高到 20。但如果开始报 429 限速就调回 5 甚至 3。这个值没有万能解取决于你的端点吞吐。我一般先用 10 跑一批看有没有 429没有就往上加。排查的核心思路是分层定位先确认 LLM 端点通不通用模型对话测再确认图数据库通不通用 redis-cli 或 Neo4j Browser 测最后确认 MCP 服务器进程活着看日志。三层都通基本不会出问题。6. 把记忆接进你的 Agent从 MCP 工具到 Coding Plan 的完整链路MCP 服务器跑通之后真正的价值在于把它接进你的日常开发流。如果你用 Claude Code 做编码可以在项目根目录放一个.mcp.json把 graphiti 注册进去这样每次开新会话Claude Code 都能读写你的项目知识图谱。比如你让它记住“这个项目的 API 层用 Fastify不用 Express”下次它生成代码时就会自动遵守。对于长期跑的 Agent 任务比如自动修 bug、自动写测试记忆系统的作用更明显。Agent 每完成一个任务把结果和上下文写入图谱下一轮任务开始时先检索相关历史避免重复踩坑。Graphiti 的增量更新特性在这里很关键——你不需要每次重建整个图谱新数据直接追加旧数据自动失效。如果你打算把这条链路产品化Coding Plan 的额度模型比按次调用更适合高频 Agent 场景。接入文档里有完整的端点说明和鉴权方式API Keys 页面管理你的凭证。模型对话功能可以用来快速验证某个模型是否支持结构化输出避免配到 Graphiti 里才发现不兼容。最后给一个实用技巧Graphiti 的add_episode支持批量写入你可以把一轮对话的多条消息打包成一个 episode减少 LLM 调用次数。另外search_facts的num_results参数默认 10如果图谱很大调小到 5 能降低延迟。这些参数在 MCP 工具调用时直接传即可不需要改服务器配置。整套流程走下来你得到的是一个可演进、可追溯、能处理矛盾的智能体记忆系统。它不依赖某个特定客户端Claude、Cursor、Cline 都能接也不绑定某个 LLM 厂商OpenAI 兼容端点都能用。剩下的就是把它接进你的业务逻辑让 Agent 真正记住该记的东西。