Graphiti：为 AI Agent 构建时间感知记忆层的开源方案

传统 RAG 检索的是静态文本块，用户问“他去年说过什么？”或“当前偏好是什么？”时，无法处理事实更新与矛盾。Graphiti 把信息组织为实体、关系与时间有效性窗口，知识变化时自动让旧事实失效，并保留来源。这样 Agent 能够基于历史上下文给出可溯源的答案，而不是简单拼接文档片段。

当前 RAG 大多把文本切片后做向量检索，但无法表达“某个事实在何时有效”“两个实体如何关联”。Graphiti 引入时间上下文图，让 AI Agent 能记住过去、区分新旧信息，回答时间敏感问题时更可靠。对构建长期记忆型 Agent 的团队来说，这是值得关注的基础设施选择。

Graphiti 使用 Apache 2.0 许可，允许商用、修改与再分发。仓库是独立的开源实现，与 Zep 托管平台明确区分：Graphiti 需要自己部署并自带图数据库。注意 README 说明该框架自托管，大规模生产（数百万图、低延迟检索）需要托管平台的自定义实现。同时，默认使用 OpenAI API，但可通过兼容端点接入 Ollama 等本地模型。遥测默认开启，可设置 GRAPHITI_TELEMETRY_ENABLED=false 关闭。另外，Kuzu 后端已被标记废弃，新项目建议 Neo4j/FalkorDB/Neptune。

这个项目不是为无代码用户准备的。如果你不会 Python 或没有 API 使用经验，直接使用门槛较高。不过，如果工程师部署好 REST 服务或 MCP 服务器，业务人员可以把它作为知识库后端来使用，通过聊天界面或现有 AI 应用访问。对非开发者而言，核心价值是“可追溯的时间感知记忆”，但需要等待技术团队封装。

部署前确认 Python 3.10+、图数据库（Neo4j/FalkorDB/Neptune）以及 LLM 访问。基本流程：1. 安装 graphiti-core；2. 创建 Neo4j 实例（本地/云端）；3. 设置 OPENAI_API_KEY 或兼容的本地 LLM 端点；4. 用 Pydantic 定义本体；5. 写一个脚本摄入文档/消息，然后调用混合检索查询。仓库提供 REST 服务与 MCP 服务器，可让 Agent 直接调用记忆接口。建议先在单个图规模验证，再考虑并发与性能。关闭遥测，避免把内部数据传给外部。

Graphiti 适合构建单个或有限数量的上下文图，功能上支持时间有效性、来源追踪、增量更新、混合检索。但 README 指出：管理数百万个图并保证受监管的低延迟检索，是 Zep 托管平台能力。自托管时，你需要自己处理数据分片、监控、缓存和检索加速。另外，没有自带的 Web UI，调试需要自己写查询或接入其他工具。

为什么需要时间感知记忆？

大部分 RAG 系统把文档切块后做向量索引，查询时返回相似片段。这种设计在“找到相关段落”上有效，但在需要追踪事实变化、实体关系和历史状态的场景里明显不足。例如，用户的收货地址改变了，旧的 RAG 索引里仍然保存着旧地址，AI Agent 无法自动理解“新地址已取代旧地址”。Graphiti 的出发点不是做一个更好的向量检索器，而是用时间知识图来表示“什么在什么时候为真”。

Graphiti 在实际项目中的适用位置

Graphiti 最合适的场景是：

• AI Agent 的长期记忆：跨会话记住用户偏好、项目状态、领域事实。
• 时间敏感问答：“这个客户上个月的续约条件是什么？”
• 动态 RAG：知识库不断更新，且需要知道旧信息在何时有效。
• 来源审计：答案需要追溯到原始文档或消息。

它的核心优势是自动管理事实有效期。当新事实与旧事实冲突时，旧事实会被标记为失效但不会删除，保留完整历史。这种设计在医疗、金融、客服等需要可解释性的领域会更有价值。

部署真实成本：不止一个 pip install

虽然安装命令很简单，但 Graphiti 不是一个单机库。你需要：

• Python 3.10+ 环境
• 一个图数据库后端，如 Neo4j 5.26+、FalkorDB 1.1.2+ 或 Amazon Neptune
• LLM 访问，默认是 OpenAI API，也可以配置本地兼容端点（如 Ollama、vLLM）

这意味着你的部署栈里至少多出一个有状态服务。Neo4j 如果跑在云上会持续产生费用，如果自托管则需要维护备份和监控。README 没有承诺 GPU，也不要求下载模型，但 LLM API 成本会随数据量上升。

仓库虽然提供了 REST 服务和 MCP 服务器，但 README 没有提到自带 Web UI。调试知识图时，你很可能需要自己写 Cypher 查询或接入 Neo4j Browser。

采用前核验清单

• 你的事件或文档流是否频繁出现“事实更新”而不是只追加？
• 你的应用是否需要知道“某个事实在何时有效”？
• 你是否愿意维护一个图数据库实例？
• 你是否能接受默认使用外部 LLM API，或者愿意配置本地模型？
• 你是否需要长期保存数据，且允许遥测关闭？
• 你的数据规模是否在单个图可以承载的范围内？

如果以上大多数是“是”，Graphiti 值得试点。如果只是需要一个简单易用的 RAG，它可能过度设计。

谁应该避开 Graphiti？

• 只需要把文档切成向量做相似度检索，不需要关系或时间维度的团队。
• 没有运维图数据库能力的团队，且不想为托管数据库付费。
• 需要开箱即用 Web UI 的非技术团队。
• 希望完全离线运行，且没有本地 LLM 推理资源。
• 数据规模极大（数百万级图实例）但团队没有分布式系统经验。

证据边界

本文分析基于仓库 README 和源码元数据。README 明确对比了 Graphiti 与 Zep 托管平台：Graphiti 自托管，需要自带第三方图数据库；托管平台才提供大规模下的受监管检索。README 还标注 Kuzu 后端已废弃，不应用在新项目。这些信息来自项目官方声明，但项目本身没有提供基准测试数字或用户数量，我们在评估时也应保持谨慎，尤其不要轻信任何“社区流行度”的直觉。

下一步行动

1. 克隆仓库，用 Docker 起一个 Neo4j。 2. 根据 README 的 quickstart，配置一个本地 OpenAI 兼容端点（如 Ollama）来避免真实 API 费用。 3. 摄入一小段有时间变化的文本，用画图工具或 Neo4j Browser 查看实体与时间边。 4. 尝试问一个需要“过去 vs 现在”的问题，检查返回结果是否区分时态。 5. 如果验证有效，再评估 REST 服务与 MCP 服务器如何嵌入你的 Agent 架构。

Graphiti 的优点在于把时间意识带入了知识图，但它不是低维护方案。它更接近一个需要专业维护的“记忆引擎”，而不是即插即用的插件。对愿意投入基础设施的团队来说，这是一个值得长期观察的开源资产。