Graphiti：LLM 驱动的时序知识图谱库

构建面向 AI 智能体的时序上下文图

我们正在招聘！构建上下文图，为可靠、个性化且快速的生产级 AI 智能体提供支持。欢迎加入我们——我们正在招聘工程师和开发者关系人才。查看开放职位。

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

来看看 Graphiti 全新的 MCP 服务器！为 Claude、Cursor 及其他 MCP 客户端提供基于强大上下文图、具备时序感知能力的记忆。

Graphiti 是一个用于为 AI 智能体构建和查询时序上下文图的框架。与静态知识图谱不同，Graphiti 的上下文图会跟踪事实如何随时间变化，保留其对源数据的溯源关系，并同时支持预定义本体和学习型本体——这使其专为处理不断演变的真实世界数据的智能体而打造。

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

构建随每次交互不断演变的上下文图——既跟踪当前为真的事实，也跟踪过去曾经为真的事实。

为智能体提供丰富的结构化上下文，而不是扁平的文档分块或原始聊天记录。

通过混合检索（语义 + 关键词 + 图遍历），跨时间、语义和关系进行查询。

什么是上下文图？

上下文图是由实体、关系和事实组成的时序图——例如，“Kendra 喜欢 Adidas 鞋（截至 2026 年 3 月）”。与传统知识图谱不同，上下文图中的每条事实都有一个有效期窗口：它何时开始为真，以及何时被取代（如果曾被取代）。实体会随着时间推移而演变，其摘要也会不断更新。所有内容都可以追溯到情节（episodes）——即产生这些内容的原始数据。

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

上下文图包含：

Graphiti 是开源的时序上下文图引擎，也是 Zep 面向 AI 智能体的上下文基础设施的核心。Zep 能够大规模管理上下文图，为生产环境中的智能体部署提供受治理、低延迟的上下文检索与组装能力。

在底层，Zep 由专有图数据库 Context Graph Engine 驱动。它专为数百万个上下文图和低延迟检索而构建，因此生产环境部署不需要单独使用第三方图数据库。

借助 Graphiti，我们已经证明 Zep 在智能体记忆领域达到了当前最佳水平。

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

我们很高兴将 Graphiti 开源，因为我们相信，它作为上下文图引擎的潜力远远超越记忆类应用。

如果你希望获得一个安全性、性能和支持能力均已内置的交钥匙企业级平台，请选择 Zep。

如果你希望使用灵活的开源核心，并且有能力自行构建和运维周边系统，请选择 Graphiti。

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

时序事实管理：事实具有有效期窗口。当信息发生变化时，旧事实会被标记为失效，而不是被删除。你可以查询当前为真的事实，也可以查询任意时间点曾经为真的事实。

情节与溯源：每个实体和关系都可以追溯到产生它们的情节（原始数据）。从派生事实到数据源，具备完整的数据血缘关系。

预定义本体与学习型本体：通过 Pydantic 模型预先定义实体和边的类型（预定义），或让结构从数据中自行涌现（学习型）。从简单结构开始，随着模式逐渐显现而持续演进。

增量图构建：新数据会立即完成整合，无需批量重新计算。随着情节被摄取，图会实时演变。

混合检索：结合语义嵌入、关键词（BM25）和图遍历，实现低延迟、高精度的查询，无需依赖 LLM 摘要。

可扩展性：通过并行处理和可插拔的图后端高效管理大型数据集，适合企业级工作负载。

Graphiti 与 GraphRAG 对比

Graphiti 专门用于应对动态且频繁更新的数据集所带来的挑战，因此特别适合需要实时交互和精确历史查询的应用。

Python 3.10 或更高版本

Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune Database Cluster，或 Neptune Analytics Graph + Amazon OpenSearch Serverless collection（用作全文搜索后端）/ Kuzu 0.11.2（已弃用，见下文）

OpenAI API key（Graphiti 默认使用 OpenAI 进行 LLM 推理和嵌入）

Graphiti 最适合与支持 Structured Output 的 LLM 服务配合使用，例如 OpenAI、Anthropic 和 Gemini。使用其他服务可能导致输出 schema 不正确及摄取失败。使用较小模型时，这一问题尤其严重。

Google Gemini、Anthropic 或 Groq API key（用于其他 LLM 提供商）

安装 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 extra 进行安装：

pip install graphiti-core[falkordb]

# or with uv
uv add graphiti-core[falkordb]

# or embedded version (requires Python 3.12+)
pip install graphiti-core[falkordblite]
# or with uv
uv add graphiti-core[falkordblite]

安装 Kuzu 支持

Kuzu 已被弃用，并将在未来版本中移除——上游 Kuzu 项目已不再维护。新项目应使用 Neo4j 或 FalkorDB。目前仍会随包提供该驱动，但会发出 DeprecationWarning。

如果你计划使用 Kuzu 作为图数据库后端，请通过 Kuzu extra 进行安装：

pip install graphiti-core[kuzu]

# or with uv
uv add graphiti-core[kuzu]

安装 Amazon Neptune 支持

如果你计划使用 Amazon Neptune 作为图数据库后端，请通过 Amazon Neptune extra 进行安装：

pip install graphiti-core[neptune]

# or with uv
uv add graphiti-core[neptune]

你还可以通过 extras 安装可选的 LLM 提供商支持：

# Install with Anthropic support
pip install graphiti-core[anthropic]

# Install with Groq support
pip install graphiti-core[groq]

# Install with Google Gemini support
pip install graphiti-core[google-genai]

# Install with multiple providers
pip install graphiti-core[anthropic,groq,google-genai]

# Install with FalkorDB and LLM providers
pip install graphiti-core[falkordb,anthropic,google-genai]

# Install with Amazon Neptune
pip install graphiti-core[neptune]

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

Graphiti 的摄取管线专为高并发而设计。默认情况下，并发度设置得较低，以避免出现 LLM 提供商的 429 速率限制错误。如果你发现 Graphiti 运行缓慢，请按照下文所述提高并发度。

并发度由 SEMAPHORE_LIMIT 环境变量控制。默认情况下，SEMAPHORE_LIMIT 被设置为 10 个并发操作，以帮助避免 LLM 提供商返回 429 速率限制错误。如果遇到此类错误，请尝试降低该值。

如果你的 LLM 提供商允许更高的吞吐量，可以增大 SEMAPHORE_LIMIT，以提升情节摄取性能。

Graphiti 默认使用 OpenAI 进行 LLM 推理和嵌入。请确保环境中已设置 OPENAI_API_KEY。它也支持 Anthropic、Gemini 和 Groq。其他 LLM 提供商——包括托管的 OpenAI 兼容 API（DeepSeek、Together、OpenRouter 等）以及本地服务器（Ollama、vLLM、llama.cpp、LM Studio）——也可以通过其 OpenAI 兼容端点使用；请参阅“通过 OpenAI 兼容提供商和本地 LLM 使用 Graphiti”。

如需查看完整且可运行的示例，请参阅 examples 目录中的快速入门示例。该快速入门演示了：

连接 Neo4j、Amazon Neptune、FalkorDB 或 Kuzu 数据库

初始化 Graphiti 索引和约束

向图中添加情节（包括文本和结构化 JSON）

使用混合搜索查找关系（边）

使用图距离对搜索结果重新排序

使用预定义的搜索方案查找节点

该示例提供了完整文档，对每项功能都有清晰说明，并包含一份全面的 README，其中提供了设置说明和后续步骤。

使用 Docker Compose 运行

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

Neo4j Docker：docker compose up。这将启动 Neo4j Docker 服务及相关组件。

docker compose up

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

FalkorDB Docker：docker compose --profile falkordb up。这将启动 FalkorDB Docker 服务及相关组件。

docker compose --profile falkordb up

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

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

MCP 服务器的主要功能包括：

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

MCP 服务器可以使用 Docker 与 Neo4j 一起部署，因此能够轻松地将 Graphiti 集成到 AI 助手工作流中。

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

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

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

可选环境变量

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

数据库配置

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

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

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

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

# Create a Neo4j driver with custom database name
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # Custom database name
)

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

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

# Create a FalkorDB driver with custom database name
driver = FalkorDriver(
    host="localhost",
    port=6379,
    username="falkor_user",  # Optional
    password="falkor_password",  # Optional
    database="my_custom_graph"  # Custom database name
)

# Or use embedded FalkorDB Lite (requires Python 3.12+)
# from redislite.async_falkordb_client import AsyncFalkorDB
# falkordb_client = AsyncFalkorDB(dbfilename='/path/to/database.db')
# driver = FalkorDriver(falkor_db=falkordb_client)

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

Kuzu 已弃用（上游项目已无人维护），并将在未来版本中移除。建议优先使用 Neo4j 或 FalkorDB。

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

# Create a Kuzu driver
driver = KuzuDriver(db="/tmp/graphiti.kuzu")

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

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

# Create a Neptune driver
driver = NeptuneDriver(
    host='<NEPTUNE_ENDPOINT>',
    aoss_host='<AMAZON_OPENSEARCH_SERVERLESS_HOST>',
    port=8182,      # Optional, defaults to 8182
    aoss_port=443,  # Optional, defaults to 443
)

# Pass the driver to Graphiti
graphiti = Graphiti(graph_driver=driver)

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

将 Graphiti 与 Azure OpenAI 配合使用

Graphiti 通过 Azure 的 OpenAI v1 API 兼容层，支持使用 Azure OpenAI 进行 LLM 推理和嵌入。

from openai import AsyncOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient

# Initialize Azure OpenAI client using the standard OpenAI client
# with Azure's v1 API endpoint
azure_client = AsyncOpenAI(
    base_url="https://your-resource-name.openai.azure.com/openai/v1/",
    api_key="your-api-key",
)

# Create LLM and Embedder clients
llm_client = AzureOpenAILLMClient(
    azure_client=azure_client,
    config=LLMConfig(model="gpt-5-mini", small_model="gpt-5-mini")  # Your Azure deployment name
)
embedder_client = AzureOpenAIEmbedderClient(
    azure_client=azure_client,
    model="text-embedding-3-small"  # Your Azure embedding deployment name
)

# Initialize Graphiti with Azure OpenAI clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=embedder_client,
)

# Now you can use Graphiti with Azure OpenAI

使用标准的 AsyncOpenAI 客户端，并采用 Azure 的 v1 API 端点格式：https://your-resource-name.openai.azure.com/openai/v1/

部署名称（例如 gpt-5-mini、text-embedding-3-small）应与你的 Azure OpenAI 部署名称一致。

完整的可运行示例请参阅 examples/azure-openai/。

请务必将占位值替换为你实际的 Azure OpenAI 凭据和部署名称。

将 Graphiti 与 Google Gemini 配合使用

Graphiti 支持使用 Google 的 Gemini 模型进行 LLM 推理、嵌入以及交叉编码/重排序。要使用 Gemini，你需要使用 Google API 密钥配置 LLM 客户端、嵌入器和交叉编码器。

uv add "graphiti-core[google-genai]"

# or

pip install "graphiti-core[google-genai]"

from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
from graphiti_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient

# Google API key configuration
api_key = "<your-google-api-key>"

# Initialize Graphiti with Gemini clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=GeminiClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.0-flash"
        )
    ),
    embedder=GeminiEmbedder(
        config=GeminiEmbedderConfig(
            api_key=api_key,
            embedding_model="embedding-001"
        )
    ),
    cross_encoder=GeminiRerankerClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.5-flash-lite"
        )
    )
)

# Now you can use Graphiti with Google Gemini for all components

Gemini 重排序器默认使用 gemini-2.5-flash-lite 模型，该模型针对经济高效且低延迟的分类任务进行了优化。它采用与 OpenAI 重排序器相同的布尔分类方法，并利用 Gemini 的对数概率功能对段落相关性进行排序。

将 Graphiti 与 OpenAI 兼容提供商和本地 LLM 配合使用

Graphiti 可以通过 OpenAIGenericClient 使用任何 OpenAI 兼容的 /v1 端点进行 LLM 推理，既支持托管提供商（DeepSeek、Together、OpenRouter、Fireworks 等），也支持本地服务器（Ollama、vLLM、llama.cpp、LM Studio）。本地服务器非常适合重视隐私或希望避免 API 成本的应用。下面的示例使用 Ollama；对于其他任何提供商，请将 base_url 指向其端点，并设置相应的 api_key 和模型。

注意：对于这些端点，请使用 OpenAIGenericClient（而不是 OpenAIClient）。它针对本地模型进行了优化，默认最大 token 限制更高（16K，而非 8K），并能处理不同兼容提供商的结构化输出。

ollama pull deepseek-r1:7b # LLM
ollama pull nomic-embed-text # embeddings

from graphiti_core import Graphiti
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Configure Ollama LLM client
llm_config = LLMConfig(
    api_key="ollama",  # Ollama doesn't require a real API key, but some placeholder is needed
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible endpoint
)

llm_client = OpenAIGenericClient(config=llm_config)

# Initialize Graphiti with Ollama clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",  # Placeholder API key
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
)

# Now you can use Graphiti with local Ollama models

请确保 Ollama 正在运行（ollama serve），并且已经拉取了你想使用的模型。

结构化输出与小模型

Graphiti 依赖结构化（JSON）输出来完成实体/边的提取和去重，因此最适合搭配能够可靠遵循结构化输出要求的模型和提供商（OpenAI、Anthropic、Gemini）。不同 OpenAI 兼容提供商的可靠性有所差异，在较小型或本地模型上尤其如此，因此 OpenAIGenericClient 提供了 structured_output_mode：

"json_schema"（默认）：通过 response_format 请求原生结构化输出。最适合能力较强的模型，以及通过受约束解码强制执行 schema 的提供商。

"json_object"：请求普通 JSON 模式，并改为将 schema 注入提示词。对于无法可靠遵循 json_schema 的提供商或模型，请使用此模式——其中包括一些本地服务器：它们虽然接受 json_schema 请求，但实际上并不会约束输出遵循该 schema，在这种情况下，json_object 可能更可靠。

使用较小型或本地模型时：

优先使用你能够运行的最强模型。非常小的模型经常会输出不符合所请求 schema 的 JSON，从而导致提取失败。

系统会自动移除包裹响应的 Markdown ```json 代码围栏。

将 SEMAPHORE_LIMIT 保持在较低水平（参见上文）——本地服务器和部分提供商的并发能力有限。

指南和 API 文档。

使用 LangChain 的 LangGraph 和 Graphiti 构建 AI 智能体

Graphiti 会收集匿名使用统计信息，以帮助我们了解该框架的使用方式，并为所有人改进它。我们认为透明度非常重要，因此下面将准确说明我们收集哪些信息以及收集这些信息的原因。

初始化 Graphiti 实例时，我们会收集：

匿名标识符：随机生成并存储在本地 ~/.cache/graphiti/telemetry_anon_id 中的 UUID

系统信息：操作系统、Python 版本和系统架构

Graphiti 版本：你正在使用的版本

配置选择：LLM 提供商类型（OpenAI、Azure、Anthropic 等）、数据库后端（Neo4j、FalkorDB、Kuzu、Amazon Neptune Database 或 Neptune Analytics）、嵌入模型提供商（OpenAI、Azure、Voyage 等）

LLM 提供商类型（OpenAI、Azure、Anthropic 等）

数据库后端（Neo4j、FalkorDB、Kuzu、Amazon Neptune Database 或 Neptune Analytics）

嵌入模型提供商（OpenAI、Azure、Voyage 等）

我们不会收集的信息

我们致力于保护你的隐私。我们绝不会收集：

个人信息或身份标识符

API 密钥或凭据

你的实际数据、查询或图内容

IP 地址或主机名

文件路径或系统特有的信息

你的 episode、节点或边中的任何内容

收集这些数据的原因

这些信息可以帮助我们：

了解哪些配置最受欢迎，以确定支持和测试工作的优先级

确定开发工作应重点关注哪些 LLM 和数据库提供商

跟踪采用模式，为我们的路线图提供指导

确保在不同 Python 版本和操作系统之间的兼容性

通过分享这些匿名信息，你可以帮助我们为社区中的所有人改进 Graphiti。

查看遥测代码

遥测代码可以在这里找到。

如何禁用遥测

遥测采用选择退出机制，可随时禁用。要禁用遥测数据收集：

选项 1：环境变量

export GRAPHITI_TELEMETRY_ENABLED=false

选项 2：在 shell 配置文件中设置

# For bash users (~/.bashrc or ~/.bash_profile)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc

# For zsh users (~/.zshrc)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc

选项 3：为特定 Python 会话设置

import os

os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'

# Then initialize Graphiti as usual
from graphiti_core import Graphiti

graphiti = Graphiti(...)

测试运行期间（检测到 pytest 时），遥测会自动禁用。

遥测使用 PostHog 收集匿名分析数据。

所有遥测操作都被设计为静默失败——它们绝不会中断你的应用程序，也不会影响 Graphiti 的功能。

匿名 ID 存储在本地，不与任何个人信息关联。

我们鼓励并感谢各种形式的贡献，无论是代码、文档、处理 GitHub Issue，还是在 GitHub 上帮助其他人。有关代码贡献的详细指南，请参阅 CONTRIBUTING。

请创建 GitHub Issue，以提出问题、报告错误或讨论 Graphiti。