Graphiti

为AI智能体构建实时知识图谱

GitHub仓库星标

:star: 助力我们触达更多开发者，壮大Graphiti社区。请为本仓库加星！

[!提示] 查看全新的Graphiti MCP服务器！为Claude、Cursor等MCP客户端提供基于知识图谱的强大记忆功能。

Graphiti是一个专为动态环境中运行的AI智能体设计的时序感知知识图谱构建与查询框架。与传统检索增强生成(RAG)方法不同，Graphiti持续将用户交互、结构化与非结构化企业数据以及外部信息整合成可查询的连贯图谱。该框架支持增量数据更新、高效检索和精确历史查询，无需完整图谱重计算，非常适合开发具有情境感知能力的交互式AI应用。

使用Graphiti可以：

整合并维护动态用户交互与业务数据
为智能体提供基于状态的推理与任务自动化支持
通过语义、关键词和图遍历等混合搜索方法查询复杂演进数据

Graphiti时序演示

知识图谱是由相互关联的事实构成的网络，例如"Kendra喜爱阿迪达斯运动鞋"。每个事实都是"三元组"，由两个实体节点("Kendra"、"阿迪达斯运动鞋")及其关系边("喜爱")组成。知识图谱在信息检索领域已有广泛应用。Graphiti的独特之处在于能自主构建知识图谱的同时，处理变化的关系并保持历史上下文。

Graphiti与Zep情境工程平台

Graphiti是Zep情境工程平台的核心引擎，为AI智能体提供记忆功能、动态数据的图RAG以及情境检索与组装服务。借助Graphiti，我们已证明Zep在智能体记忆领域处于领先地位。

阅读我们的论文：Zep：面向智能体记忆的时序知识图谱架构。

我们很荣幸能将Graphiti开源，相信其潜力远不止于AI记忆应用。

Zep与Graphiti对比

维度	Zep	Graphiti
产品形态	情境工程与AI记忆的全托管平台	开源图谱框架
用户与会话管理	内置用户、会话线程和消息存储	需自行构建
检索与性能	预配置生产级检索，大规模下延迟<200ms	需自定义实现，性能取决于部署方案
开发者工具	含图谱可视化、调试日志、API日志的仪表盘；支持Python/TypeScript/Go的SDK	需自行开发工具
企业功能	提供SLA、技术支持与安全保证	需自行维护
部署方式	全托管或私有云部署	仅支持自托管

选择建议

选择Zep：如果您需要开箱即用的企业级平台，具备安全保障、性能保证和技术支持。

选择Graphiti：如果您需要灵活的OSS核心框架，并有能力构建/运维周边系统。

为什么选择Graphiti？

传统RAG方法通常依赖批处理和静态数据摘要，难以应对频繁变更的数据。Graphiti通过以下特性解决这些问题：

实时增量更新：无需批处理重计算即可即时整合新数据片段
双时序数据模型：明确追踪事件发生时间和入库时间，支持精确时间点查询
高效混合检索：结合语义嵌入、关键词(BM25)和图遍历，实现不依赖LLM摘要的低延迟查询
自定义实体类型：通过简洁的Pydantic模型灵活创建本体和开发者定义实体
可扩展性：通过并行处理高效管理海量数据集，适合企业级环境

Graphiti结构化与非结构化数据演示

Graphiti与GraphRAG对比

特性	GraphRAG	Graphiti
主要用途	静态文档摘要	动态数据管理
数据处理方式	批处理导向	持续增量更新
知识结构	实体聚类与社区摘要	片段化数据、语义实体、动态社区
检索方法	依赖LLM的顺序摘要	语义/关键词/图遍历的混合搜索
适应性	低	高
时序处理	基础时间戳追踪	显式双时序追踪
矛盾处理	依赖LLM的摘要判断	时序边失效机制
查询延迟	数秒至数十秒	通常亚秒级延迟
自定义实体类型	不支持	支持
可扩展性	中等	高，针对大数据集优化

Graphiti专为解决动态和频繁更新数据集的挑战而设计，特别适合需要实时交互和精确历史查询的应用场景。

安装指南

系统要求：

Python 3.10或更高版本
Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune数据库集群或Neptune Analytics图数据库 + Amazon OpenSearch Serverless集合(作为全文检索后端)
OpenAI API密钥(Graphiti默认使用OpenAI进行LLM推理和嵌入)

[!重要] Graphiti最适配支持结构化输出的LLM服务(如OpenAI和Gemini)。使用其他服务可能导致输出模式错误和数据摄入失败，尤其在使用较小模型时更为明显。

可选配置：

Google Gemini、Anthropic或Groq API密钥(作为替代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扩展：

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`来提升数据摄取性能。

## 快速入门

> [!重要提示]
> Graphiti默认使用OpenAI进行LLM推理和嵌入。请确保在环境中设置了`OPENAI_API_KEY`。
> 同时支持Anthropic和Groq的LLM推理。其他LLM提供商可通过OpenAI兼容API获得支持。

完整示例请查看示例目录中的[快速入门示例](./examples/quickstart/README.md)。该示例展示：

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

示例包含详细文档，清晰解释各项功能，并附有完整的README说明设置步骤和后续操作。

### 使用Docker Compose运行

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

- **Neo4j Docker:**
  ```sh
  docker compose up

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

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

MCP服务器

mcp_server目录包含Graphiti的模型上下文协议(MCP)服务器实现。该服务器允许AI助手通过MCP协议与Graphiti的知识图功能交互。

MCP服务器主要功能包括：

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

MCP服务器可与Neo4j一起通过Docker部署，便于将Graphiti集成到AI助手工作流中。

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

REST服务

server目录包含用于与Graphiti 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

# 创建带自定义数据库名的FalkorDB驱动
driver = NeptuneDriver(
    host=<NEPTUNE端点>,
    aoss_host=<Amazon OpenSearch无服务器主机>,
    port=<端口>,  # 可选，默认为8182
    aoss_port=<端口>  # 可选，默认为443
)

driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)

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

将Graphiti与Azure OpenAI结合使用

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

快速开始

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

# 使用标准OpenAI客户端初始化Azure OpenAI
# 使用Azure v1 API端点
azure_client = AsyncOpenAI(
    base_url="https://your-resource-name.openai.azure.com/openai/v1/",
    api_key="your-api-key",
)

# 创建LLM和嵌入客户端
llm_client = AzureOpenAILLMClient(
    azure_client=azure_client,
    config=LLMConfig(model="gpt-5-mini", small_model="gpt-5-mini")  # 您的Azure部署名称
)
embedder_client = AzureOpenAIEmbedderClient(
    azure_client=azure_client,
    model="text-embedding-3-small"  # 您的Azure嵌入部署名称
)

# 使用Azure OpenAI客户端初始化Graphiti
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=embedder_client,
)

# 现在您可以使用Azure OpenAI运行Graphiti

关键点：

使用标准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需要配置LLM客户端、嵌入器和交叉编码器，并提供Google API密钥。

安装Graphiti：

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

# 或

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密钥配置
api_key = "<您的google-api-key>"

# 使用Gemini客户端初始化Graphiti
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"
        )
    )
)

# 现在您可以使用Google Gemini运行Graphiti的所有组件

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

将Graphiti与Ollama（本地LLM）结合使用

Graphiti支持通过Ollama的OpenAI兼容API运行本地LLM和嵌入模型。这非常适合注重隐私的应用或希望避免API成本的场景。

注意： 对于Ollama和LM Studio等其他OpenAI兼容提供商，请使用OpenAIGenericClient（而非OpenAIClient）。OpenAIGenericClient针对本地模型优化，具有更高的默认最大令牌限制（16K vs 8K），并完全支持结构化输出。

安装模型：

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

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

配置Ollama LLM客户端

llm_config = LLMConfig( api_key="ollama", # Ollama不需要真实API密钥，但需要占位符 model="deepseek-r1:7b", small_model="deepseek-r1:7b", base_url="http://localhost:11434/v1", # Ollama的OpenAI兼容端点 )

llm_client = OpenAIGenericClient(config=llm_config)

使用Ollama客户端初始化Graphiti

graphiti = Graphiti( "bolt://localhost:7687", "neo4j", "password", llm_client=llm_client, embedder=OpenAIEmbedder( config=OpenAIEmbedderConfig( api_key="ollama", # 占位API密钥 embedding_model="nomic-embed-text", embedding_dim=768, base_url="http://localhost:11434/v1", ) ), cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config), )

现在您可以使用本地Ollama模型运行Graphiti


请确保Ollama正在运行(`ollama serve`)且已拉取所需模型。

## 文档

- [指南和API文档](https://help.getzep.com/graphiti)
- [快速入门](https://help.getzep.com/graphiti/graphiti/quick-start)
- [使用LangChain的LangGraph和Graphiti构建代理](https://help.getzep.com/graphiti/integrations/lang-graph-agent)

## 遥测数据

Graphiti收集匿名使用统计数据，以帮助我们了解框架使用情况并改进产品。我们重视透明度，以下是具体收集内容及原因。

### 收集内容

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

- **匿名标识符**：本地存储的随机生成UUID（位于`~/.cache/graphiti/telemetry_anon_id`）
- **系统信息**：操作系统、Python版本和系统架构
- **Graphiti版本**：您使用的版本
- **配置选择**：
    - LLM提供商类型（OpenAI、Azure、Anthropic等）
    - 数据库后端（Neo4j、FalkorDB、Kuzu、Amazon Neptune Database或Neptune Analytics）
    - 嵌入器提供商（OpenAI、Azure、Voyage等）

### 不收集内容

我们承诺保护您的隐私，绝不收集：

- 个人信息或标识符
- API密钥或凭据
- 您的实际数据、查询或图内容
- IP地址或主机名
- 文件路径或系统特定信息
- 任何事件、节点或边的内容

### 数据收集目的

这些信息帮助我们：

- 了解流行配置以优先支持
- 确定重点开发的LLM和数据库提供商
- 追踪采用模式以指导路线图
- 确保跨Python版本和操作系统的兼容性

您的匿名信息共享将助力我们为社区打造更好的Graphiti。

### 查看遥测代码

遥测代码[可在此处查看](graphiti_core/telemetry/telemetry.py)。

### 禁用遥测

遥测功能默认启用，可随时禁用：

**选项1：环境变量**

```bash
export GRAPHITI_TELEMETRY_ENABLED=false

选项2：Shell配置文件设置

# bash用户(~/.bashrc或~/.bash_profile)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc

# zsh用户(~/.zshrc)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc

选项3：Python会话中设置

import os

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

# 然后正常初始化Graphiti
from graphiti_core import Graphiti

graphiti = Graphiti(...)

检测到pytest时会自动禁用遥测。

技术细节

使用PostHog进行匿名分析收集
所有遥测操作设计为静默失败——不会中断应用或影响功能
匿名ID本地存储，不与任何个人信息关联

状态与路线图

Graphiti正在积极开发中。我们在保持API稳定性的同时致力于：

[x] 支持自定义图模式：
- 允许开发者提供自定义节点和边类
- 支持针对特定用例的灵活知识表示
[x] 增强检索能力，提供更健壮可配置的选项
[x] Graphiti MCP服务器
[ ] 扩展测试覆盖以确保可靠性

贡献指南

我们欢迎各种形式的贡献，包括代码、文档、处理GitHub问题或在Graphiti Discord频道答疑。详细指南请参阅贡献说明。

支持

加入Zep Discord服务器并进入**#Graphiti**频道！