一天一个开源项目（第28篇）：Graphiti - 为 AI Agent 构建实时知识图谱

冬奇Lab
0 阅读9分钟

引言

"传统 RAG 偏静态、批处理；当数据持续变化、需要「当时发生了什么」时，你需要的是时间感知的图。"

这是"一天一个开源项目"系列的第28篇文章。今天带你了解的项目是 Graphiti（GitHub），由 getzep 开源。

知识图谱用「实体—关系—实体」三元组表达事实，适合做结构化检索与推理。但多数方案要么批处理、要么时间语义弱，难以支撑持续更新的对话、业务数据与外部信息。Graphiti 面向的正是这类场景：为在动态环境中运行的 AI Agent 构建和查询时间感知（temporally-aware）知识图谱。它支持实时增量写入、双时间数据模型（事件发生时间与摄入时间）、混合检索（语义 + 关键词 BM25 + 图遍历），以及自定义实体（Pydantic），无需整图重算即可做历史查询。同时提供 MCP 服务（供 Claude、Cursor 等调用）、REST API（FastAPI），并支持 Neo4j、FalkorDB、Kuzu、Amazon Neptune 多种图库后端，是 Zep 上下文工程平台的核心开源组件。

你将学到什么

  • Graphiti 的定位：面向 AI Agent 的实时、时间感知知识图谱框架
  • 与传统 RAG、GraphRAG 的差异：增量 vs 批处理、双时间 vs 简单时间戳
  • 核心能力：Episode 写入、混合检索、自定义实体、多图库与多 LLM 支持
  • 安装、快速开始与 MCP/REST 集成方式
  • 驱动架构（11 个 Operations ABC）与 Zep 的关系

前置知识

  • 对知识图谱（节点、边、三元组）有基本概念
  • 了解 RAG、向量检索与图遍历的粗浅区别
  • 会使用 Python 3.10+、pip/uv；若自建图库需准备 Neo4j/FalkorDB/Kuzu/Neptune 之一

项目背景

项目简介

Graphiti 是一个用于构建与查询时间感知知识图谱的框架，专门面向在动态环境中运行的 AI Agent。它把用户交互、结构化与非结构化业务数据、外部信息持续整合进一张可查询的图中，支持增量更新与精确的历史（时间点）查询，而无需全图重算。与依赖批处理与静态摘要的传统 RAG 不同，Graphiti 强调实时写入、双时间建模、混合检索（语义 + 关键词 + 图），并支持通过 Pydantic 定义自定义实体类型。其核心能力被 Zep 的上下文工程与 Agent 记忆平台采用；Graphiti 以开源框架形式提供，便于自建图存储与检索层。

项目解决的核心问题：

  • 数据持续变化时，批处理 RAG 延迟高、难以反映「当前状态」与「当时状态」
  • 需要显式区分「事件发生时间」与「被系统摄入时间」，以支持审计与历史查询
  • 希望结合语义、关键词与图结构做检索，而不是单一向量或单一摘要
  • 需要可插拔的图后端（本地 Neo4j/FalkorDB/Kuzu 或云上 Neptune），便于按规模与合规选型

面向的用户群体：

  • 做 AI Agent 记忆、对话上下文、多轮推理的开发者
  • 需要「动态数据 + 图结构 + 时间查询」的 RAG/知识库场景
  • 希望自建图层、对接 Claude/Cursor 等 via MCP 的团队
  • 研究或实现「图 + 时间 + Agent」架构的工程师

作者/团队介绍

项目数据

主要功能

核心作用

Graphiti 的核心作用是为 AI Agent 提供「实时、可查询、时间感知」的知识图谱能力：

  1. Episode 写入：将文本或结构化 JSON 作为「片段」写入图，自动抽取实体与关系，支持增量、无需全图重跑
  2. 双时间模型：同时记录事件发生时间与摄入时间，支持按时间点/时间范围的历史查询
  3. 混合检索：语义嵌入 + 关键词（BM25）+ 图遍历，可结合图距离做 rerank，目标亚秒级延迟
  4. 自定义实体：通过 Pydantic 定义节点/边类型，适配业务本体
  5. 多后端：Neo4j、FalkorDB、Kuzu、Amazon Neptune（含 Neptune Analytics + OpenSearch Serverless），可插拔驱动
  6. 多 LLM：默认 OpenAI；支持 Azure OpenAI、Google Gemini、Anthropic、Groq、Ollama（本地）等，用于抽取与嵌入
  7. MCP 与 REST：MCP 服务供 Claude/Cursor 等调用；REST 服务（FastAPI）供自建前端或服务集成

使用场景

  1. Agent 长期记忆

    • 将对话与行为以 Episode 写入图，按时间与主题检索，支撑多轮推理与状态恢复

  2. 动态业务知识库

    • 订单、工单、文档等持续更新，用图 + 时间建模「谁在何时与何物关联」，支持审计与历史查询

  3. Graph RAG 替代批处理 RAG

    • 数据频繁变更时，用 Graphiti 做增量图构建与混合检索，替代「全量重跑 + 纯向量」的管道

  4. 与 Claude/Cursor 集成

    • 通过 Graphiti MCP Server 为助手提供「图记忆」：添加片段、实体管理、语义/混合搜索、分组与维护

  5. 研究与复现

    • 基于论文与开源实现复现「时间知识图谱 + Agent 记忆」，或扩展新驱动、新检索策略

快速开始

环境：Python 3.10+；Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune 之一；OpenAI API Key（默认 LLM/嵌入）。推荐使用支持 Structured Output 的模型（如 OpenAI、Gemini），以保证抽取质量。

安装：

pip install graphiti-core
# 或
uv add graphiti-core

# 使用 FalkorDB 时
pip install graphiti-core[falkordb]

# 使用 Kuzu 时
pip install graphiti-core[kuzu]

# 使用 Neptune 时
pip install graphiti-core[neptune]

# 多 LLM 可选
pip install graphiti-core[anthropic,google-genai,groq]

用 Docker 起 FalkorDB：

docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

最小示例（Neo4j）：设置 OPENAI_API_KEY 后，参考仓库 examples/quickstart，完成：连接图库 → 初始化索引与约束 → 添加 Episode（文本或 JSON）→ 混合搜索边/节点 → 按图距离 rerank → 使用搜索配方。完整步骤见 Quick Start 文档。

MCP 集成：见仓库 mcp_server/README，支持 Episode 增删查、实体与关系、语义/混合搜索、分组与图维护，可配合 Claude、Cursor 等 MCP 客户端使用。

核心特性

  1. 实时增量更新：新 Episode 写入即入图，无需批处理全量重算
  2. 双时间数据模型：事件时间 + 摄入时间，支持准确的时间点/范围查询
  3. 混合检索：语义 + BM25 + 图遍历，可选图距离 rerank，低延迟（亚秒级目标）
  4. 可插拔图驱动：GraphDriver ABC + 11 个 Operations 接口，支持 Neo4j、FalkorDB、Kuzu、Neptune，可自研新后端
  5. 自定义实体：Pydantic 定义节点/边类型，适配领域本体
  6. 多 LLM/嵌入：OpenAI、Azure、Gemini、Anthropic、Groq、Ollama 等，满足云端与本地部署
  7. MCP 与 REST：与 AI 助手（Claude、Cursor）及自建服务集成
  8. 遥测可关闭：匿名使用统计，可通过 GRAPHITI_TELEMETRY_ENABLED=false 关闭

Graphiti 与 GraphRAG、Zep 的对比

维度传统 GraphRAGGraphitiZep（商业平台）
主要用途静态文档摘要动态数据与时间感知图托管式上下文与记忆
数据更新批处理为主持续、增量托管，开箱即用
时间简单时间戳双时间（发生+摄入）平台内建
检索依赖 LLM 摘要链语义 + BM25 + 图 + rerank预配置、亚 200ms 级
查询延迟秒级到数十秒通常亚秒亚 200ms 级
自定义实体一般不支持支持（Pydantic）视产品能力
部署自建自建（多图库可选）托管或云上

为什么选 Graphiti？

  • 需要图 + 时间 + 增量且希望自控图库与检索时，Graphiti 提供完整开源实现
  • 与 Zep 同源（Zep 底层用 Graphiti），可先自建验证再考虑迁到 Zep 托管
  • MCP 与 多图库、多 LLM 便于嵌入现有 Agent 与基础设施

项目详细剖析

数据模型与流程简述

  • Episode：一次输入单元（一段文本或一条结构化 JSON），写入后经 LLM 抽取实体与关系，写入图并建立与时间相关的边（如 NextEpisode）。
  • 实体与边：实体节点（Entity）、Episode 节点、社区（Community）与 Saga 等；边类型包括实体间关系、Episode 与实体关联、Episode 顺序等。支持时间边失效（temporal edge invalidation）处理矛盾与变更。
  • 检索：语义检索（嵌入）、关键词（FTS/BM25）、图遍历与社区等结合；结果可按图距离 rerank，无需依赖长链 LLM 摘要。

图驱动架构（11 Operations）

Graphiti 用可插拔驱动隔离图库差异：

  • GraphDriver：抽象基类，定义连接、会话、索引/约束生命周期，并暴露 11 个 Operations 接口（以 @property 访问）。
  • 11 Operations：节点类（EntityNode、EpisodeNode、CommunityNode、SagaNode）、边类（EntityEdge、EpisodicEdge、CommunityEdge、HasEpisode、NextEpisode）、搜索与图维护。每个后端实现这 11 个接口；查询语句由共享的 query builder 根据 GraphProvider 枚举生成对应方言。
  • 扩展新后端：在 GraphProvider 中加枚举 → 实现 GraphDriver 子类与 11 个 Operations → 在 node_db_queries.py / edge_db_queries.py 中为新区块添加方言 → 在 pyproject.toml 中注册可选依赖。README 中以 Neo4j、FalkorDB、Kuzu、Neptune 为参考实现说明。

并发与限流

  • 摄入管道支持高并发；默认通过 SEMAPHORE_LIMIT（如 10）限制并发，避免 LLM 提供商 429。可适当调高以提升吞吐，或调低以应对限流。

文档与路线图

  • 文档：help.getzep.com/graphiti，含 Quick Start、与 LangGraph 构建 Agent 等。
  • 路线图：自定义图 schema、检索增强、MCP Server 已落地；持续扩展测试与稳定性。

项目地址与资源

官方资源

相关资源

适用人群

  • Agent 与记忆系统开发者：需要时间感知、可增量更新的图存储与检索
  • RAG/知识库进阶：从纯向量或批处理 GraphRAG 升级到动态图 + 混合检索
  • 图数据库使用者：已在用 Neo4j/FalkorDB/Kuzu/Neptune，希望接入 LLM 抽取与语义检索
  • Claude/Cursor 集成：通过 MCP 为助手提供「图记忆」与检索能力

欢迎来我中的个人主页找到更多有用的知识和有趣的产品

avatar
文章
阅读
粉丝