Graphiti

为 AI 智能体构建时序上下文图谱

[!NOTE]
我们正在招聘！ 构建为可靠、个性化、快速的生产级 AI 智能体提供动力的上下文图谱。
加入我们，一起构建未来——我们正在招聘工程师和开发者关系专家。查看开放职位。

⭐ 帮助我们触达更多开发者，壮大 Graphiti 社区。给这个仓库点个星吧！

[!TIP]
快来体验全新的 Graphiti MCP 服务器！为 Claude、Cursor 及其他 MCP 客户端提供具备时序感知能力的强大上下文图谱记忆。

Graphiti 是一个用于为 AI 智能体构建和查询时序上下文图谱的框架。与静态知识图谱不同，Graphiti 的上下文图谱追踪事实如何随时间变化，维护数据来源的溯源信息，并支持预设和学习的本体论——使其专为处理不断演化的真实世界数据的智能体而设计。

与传统检索增强生成（RAG）方法不同，Graphiti 持续将用户交互、结构化和非结构化的企业数据以及外部信息整合到一个连贯、可查询的图谱中。该框架支持增量数据更新、高效检索和精确的历史查询，无需完整的图谱重新计算，适合开发交互式、上下文感知的 AI 应用。

使用 Graphiti 可以：

• 构建随每次交互演化的上下文图谱——追踪当前为真的事实以及过去为真的事实。
• 为智能体提供丰富、结构化的上下文，而非扁平的文档片段或原始的聊天记录。
• 通过混合检索（语义 + 关键词 + 图谱遍历）跨时间、跨含义、跨关系进行查询。

什么是上下文图谱？

上下文图谱 是一个由实体、关系和事实构成的时序图谱——例如 "Kendra 喜欢阿迪达斯鞋子（截至 2026 年 3 月）"。与传统知识图谱不同，上下文图谱中的每个事实都有一个有效时间窗口：它何时变为真，以及何时（如果存在）被取代。实体随时间演化，并带有更新的摘要。一切都追溯到 事件——产生它的原始数据。

Graphiti 的独特之处在于其能够从非结构化和结构化数据中自主构建上下文图谱，处理变化的关系，同时保留完整的时序历史。

一个上下文图谱包含：

Graphiti 与 Zep

Graphiti 是 Zep 为 AI 智能体提供的上下文基础设施核心的开源时序上下文图谱引擎。Zep 大规模管理上下文图谱，为生产级智能体部署提供受管控、低延迟的上下文检索和组装。

使用 Graphiti，我们已经证明 Zep 是 智能体记忆领域的 State of the Art。

阅读我们的论文：Zep: A Temporal Knowledge Graph Architecture for Agent Memory。

我们很高兴能开源 Graphiti，相信其作为上下文图谱引擎的潜力远不止于记忆应用。

Zep 与 Graphiti 对比

如何选择

选择 Zep，如果你想要一个开箱即用、企业级的平台，内置安全、性能和支持。

选择 Graphiti，如果你想要一个灵活的开源核心，并且愿意构建/运维周边系统。

为什么选择 Graphiti？

传统的 RAG 方法通常依赖于批处理和静态数据摘要，这使得它们在处理频繁变化的数据时效率低下。Graphiti 通过提供以下功能来解决这些挑战：

• 时序事实管理： 事实具有有效性窗口。当信息发生变化时，旧事实会被失效——而不是删除。查询当前为真的事实，或任何时间点为真的事实。
• 事件与溯源： 每个实体和关系都追溯到产生它的事件（原始数据）。从衍生事实到来源的完整谱系。
• 预设与学习本体论： 通过 Pydantic 模型预先定义实体和边类型（预设），或者让结构从你的数据中涌现（学习）。从简单开始，随着模式出现而演进。
• 增量图谱构建： 新数据立即集成，无需批处理重新计算。图谱随着事件摄入而实时演化。
• 混合检索： 结合语义嵌入、关键词（BM25）和图谱遍历，实现低延迟、高精度的查询，无需依赖 LLM 摘要。
• 可扩展性： 通过并行处理、可插拔的图谱后端高效管理大型数据集，适用于企业级工作负载。

Graphiti 与 GraphRAG 对比

Graphiti 专门设计用于应对动态和频繁更新数据集的挑战，使其特别适合需要实时交互和精确历史查询的应用。

安装

要求：

• Python 3.10 或更高版本
• Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune Database Cluster 或 Neptune Analytics Graph + Amazon OpenSearch Serverless collection（作为全文搜索后端）
• OpenAI API 密钥（Graphiti 默认使用 OpenAI 进行 LLM 推理和嵌入）

[!IMPORTANT]
Graphiti 与支持结构化输出（如 OpenAI 和 Gemini）的 LLM 服务配合效果最佳。
使用其他服务可能导致输出模式不正确和摄入失败。在使用较小模型时，这个问题尤其突出。

可选：

• Google Gemini、Anthropic 或 Groq API 密钥（用于替代 LLM 提供商）

[!TIP]
安装 Neo4j 最简单的方法是通过 Neo4j Desktop。它提供了一个用户友好的界面来管理 Neo4j 实例和数据库。
或者，你可以通过 Docker 在本地使用 FalkorDB，并立即开始快速入门示例：
docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

pip install graphiti-core

或

uv add graphiti-core

安装 FalkorDB 支持

如果你计划使用 FalkorDB 作为图谱数据库后端，请安装带有 FalkorDB 额外依赖的版本：

pip install graphiti-core[falkordb]

# 或使用 uv
uv add graphiti-core[falkordb]

安装 Kuzu 支持

如果你计划使用 Kuzu 作为图谱数据库后端，请安装带有 Kuzu 额外依赖的版本：

pip install graphiti-core[kuzu]

# 或使用 uv
uv add graphiti-core[kuzu]

安装 Amazon Neptune 支持

如果你计划使用 Amazon Neptune 作为图谱数据库后端，请安装带有 Amazon Neptune 额外依赖的版本：

pip install graphiti-core[neptune]

# 或使用 uv
uv add graphiti-core[neptune]

你也可以将可选的 LLM 提供商作为额外依赖安装：

# 安装 Anthropic 支持
pip install graphiti-core[anthropic]

# 安装 Groq 支持
pip install graphiti-core[groq]

# 安装 Google Gemini 支持
pip install graphiti-core[google-genai]

# 安装多个提供商
pip install graphiti-core[anthropic,groq,google-genai]

# 安装 FalkorDB 和 LLM 提供商
pip install graphiti-core[falkordb,anthropic,google-genai]

# 安装 Amazon Neptune
pip install graphiti-core[neptune]

默认低并发；LLM 提供商 429 速率限制错误

Graphiti 的摄入管道设计为高并发。默认情况下，并发设置较低，以避免 LLM 提供商的 429 速率限制错误。如果你觉得 Graphiti 速度慢，请按照以下说明增加并发。

并发由 SEMAPHORE_LIMIT 环境变量控制。默认情况下，SEMAPHORE_LIMIT 设置为 10 个并发操作，以帮助防止来自你的 LLM 提供商的 429 速率限制错误。如果遇到此类错误，请尝试降低此值。

如果你的 LLM 提供商允许更高的吞吐量，你可以增加 SEMAPHORE_LIMIT 以提高事件摄入性能。

快速开始

[!IMPORTANT]
Graphiti 默认使用 OpenAI 进行 LLM 推理和嵌入。请确保在你的环境中设置了 OPENAI_API_KEY。
也支持使用 Anthropic 和 Groq 进行 LLM 推理。其他 LLM 提供商可能通过 OpenAI 兼容的 API 得到支持。

有关完整的工作示例，请参阅示例目录中的 快速入门示例。该快速入门演示了：

1. 连接到 Neo4j、Amazon Neptune、FalkorDB 或 Kuzu 数据库
2. 初始化 Graphiti 索引和约束
3. 向图谱添加事件（包括文本和结构化 JSON）
4. 使用混合搜索查找关系（边）
5. 使用图谱距离对搜索结果进行重排序
6. 使用预定义的搜索方案搜索节点

该示例有完整的文档说明，清晰地解释了每个功能，并包含一个全面的 README，其中包含设置说明和后续步骤。

使用 Docker Compose 运行

你可以使用 Docker Compose 快速启动所需服务：

• Neo4j Docker:

bash docker compose up

这将启动 Neo4j Docker 服务及相关组件。

• FalkorDB Docker:

bash docker compose --profile falkordb up

这将启动 FalkorDB Docker 服务及相关组件。

MCP 服务器

mcp_server 目录包含 Graphiti 的模型上下文协议（MCP）服务器实现。该服务器允许 AI 助手通过 MCP 协议与 Graphiti 的上下文图谱功能进行交互。

MCP 服务器的关键功能包括：

• 事件管理（添加、检索、删除）
• 实体管理和关系处理
• 语义和混合搜索能力
• 用于组织相关数据的分组管理
• 图谱维护操作

MCP 服务器可以使用 Docker 与 Neo4j 一起部署，使得将 Graphiti 集成到你的 AI 助手工作流中变得容易。

有关详细的设置说明和使用示例，请参阅 MCP 服务器 README。

REST 服务

server 目录包含一个用于与 Graphiti API 交互的 API 服务。它是使用 FastAPI 构建的。

更多信息请参阅 服务器 README。

可选环境变量

除了 Neo4j 和 OpenAi 兼容的凭证外，Graphiti 还有一些可选的环境变量。
如果你正在使用我们支持的模型之一，例如 Anthropic 或 Voyage 模型，则必须设置必要的环境变量。

数据库配置

数据库名称直接在驱动程序构造函数中配置：

• Neo4j：数据库名称默认为 neo4j（在 Neo4jDriver 中硬编码）
• FalkorDB：数据库名称默认为 default_db（在 FalkorDriver 中硬编码）

从 v0.17.0 开始，如果你需要自定义数据库配置，可以实例化一个数据库驱动程序，并使用 graph_driver 参数将其传递给 Graphiti 构造函数。

Neo4j 自定义数据库名称

from graphiti_core import Graphiti
from graphiti_core.driver.neo4j_driver import Neo4jDriver

# 创建带有自定义数据库名称的 Neo4j 驱动程序
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # 自定义数据库名称
)

# 将驱动程序传递给 Graphiti
graphiti = Graphiti(graph_driver=driver)

FalkorDB 自定义数据库名称

from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver

# 创建带有自定义数据库名称的 FalkorDB 驱动程序
driver = FalkorDriver(
    host="localhost",
    port=6379,
    username="falkor_user",  # 可选
    password="falkor_password",  # 可选
    database="my_custom_graph"  # 自定义数据库名称
)

# 将驱动程序传递给 Graphiti
graphiti = Graphiti(graph_driver=driver)

Kuzu

from graphiti_core import Graphiti
from graphiti_core.driver.kuzu_driver import KuzuDriver

# 创建 Kuzu 驱动程序
driver = KuzuDriver(db="/tmp/graphiti.kuzu")

# 将驱动程序传递给 Graphiti
graphiti = Graphiti(graph_driver=driver)

Amazon Neptune

from graphiti_core import Graphiti
from graphiti_core.driver.neptune_driver import NeptuneDriver

# 创建 Neptune 驱动程序
driver = NeptuneDriver(
    host='<NEPTUNE_ENDPOINT>',
    aoss_host='<AMAZON_OPENSEARCH_SERVERLESS_HOST>',
    port=8182,      # 可选，默认为 8182
    aoss_port=443,  # 可选，默认为 443
)

# 将驱动程序传递给 Graphiti
graphiti = Graphiti(graph_driver=driver)

想要贡献一个新的图谱后端？请参阅 添加图谱驱动程序。