框架定位与设计目标

Graphiti 是一个面向 AI Agent 的时态上下文图谱（Temporal Context Graph）构建框架。不同于依赖静态批处理与文档摘要的传统 RAG，Graphiti 持续整合用户交互、结构化与非结构化企业数据以及外部信息，形成可增量更新、可精确历史查询的统一图谱 资料来源：README.md:60-90。

其设计目标可归纳为四点：

• 时态事实管理：事实带有效期窗口，变更时旧边自动失效而非删除。
• 情节与溯源：每个实体与关系都可回溯到产生它的原始数据（Episode）。
• 可扩展本体：通过 Pydantic 模型自定义实体与边类型。
• 亚秒级混合检索：融合语义、关键词与图遍历三种策略。

相较于 GraphRAG，Graphiti 在数据处理（批处理→增量更新）、知识结构（实体聚类→带有效期事实）、时态精度（基础时间戳→显式双时态）与查询延迟（秒级→亚秒级）四个维度上具备显著优势 资料来源：README.md:1-15，特别适合需要实时交互与精确历史查询的智能体场景。

上下文图谱的核心概念

Graphiti 上下文图谱由四类核心组件构成 资料来源：README.md:100-120：

• 实体（节点）：人、产品、策略、概念等，摘要随时间持续演化。
• 事实/关系（边）：以三元组（实体→关系→实体）形式存在，并附带时态有效期窗口。
• 情节（Episodes）：摄入的原始数据，作为溯源根；任何派生事实都可回溯到具体情节 UUID。
• 自定义类型（本体）：开发者通过 Pydantic 模型自定义的实体与边类型。

在 MCP 服务器实现中，这些类型被具象化为 Person、Organization、Requirement、Preference、Procedure、Location、Event、Document 等内置 Pydantic 模型 资料来源：mcp_server/src/models/entity_types.py:1-80。每个模型都附带 description 字段作为 LLM 抽取指引，例如 Requirement 类规定"必须使用 'We need X' 等显式需求语句"作为识别启发式，从而约束 LLM 按预定本体进行结构化抽取。

系统架构与 MCP 扩展

Graphiti 的整体数据流可概括为「摄入 → 抽取 → 存储 → 检索」四阶段：

flowchart LR
    A[Episodes<br/>文本/消息/JSON] --> B[LLM 抽取<br/>实体+事实]
    B --> C[图存储<br/>Neo4j/FalkorDB/Neptune]
    B --> D[嵌入器<br/>OpenAI/Voyage/...]
    C --> E[混合检索<br/>语义+BM25+图遍历]
    D --> E
    E --> F[Agent 上下文]

默认 LLM 与嵌入器为 OpenAI 资料来源：README.md:30-45，但通过配置可切换至 Azure OpenAI、Anthropic、Gemini、Groq 等提供商 资料来源：examples/azure-openai/README.md:50-80。图存储后端当前支持 Neo4j、FalkorDB、Amazon Neptune 与 Kuzu（已弃用）资料来源：mcp_server/README.md:15-30，检索阶段融合语义相似度、BM25 与图遍历 资料来源：examples/quickstart/README.md:70-95。

通过 MCP（Model Context Protocol）服务器，Graphiti 向 Claude、Cursor 等客户端暴露图谱能力 资料来源：mcp_server/README.md:1-20。add_memory 工具支持 text、message、json 三种来源类型，并通过 reference_time 参数记录历史事件发生时间，实现双时态追踪——即"事件发生时间"与"系统认知时间"分离 资料来源：mcp_server/src/graphiti_mcp_server.py:60-95。其他关键工具涵盖 search_nodes、search_facts、get_episode_entities、delete_episode、clear_graph 等，覆盖从摄入到维护的全生命周期 资料来源：mcp_server/src/graphiti_mcp_server.py:20-55。

社区关注与发展方向

从社区反馈看，用户最关注的方向是后端与 LLM 的可扩展性。Issue #779 询问 PostgreSQL+pgvector 是否在路线图中，Issue #248 建议增加通用图存储接口，Issue #459 提议支持 Amazon Bedrock，Issue #642 请求 MemGraph 驱动，Issue #933 提议支持 RDF 以启用语义推理。这些请求反映出 Graphiti 当前与 Neo4j/FalkorDB 耦合较紧，社区正推动其向更通用的存储与模型接口演进。最近发布的 v0.29.2 主要修复了 FalkorDB 相关的若干 Bug（如空字节剥离、Docker 启动失败等），表明 FalkorDB 仍是当前重点维护的轻量级后端。

See Also

• Graphiti 安装与快速开始
• Graphiti MCP 服务器使用指南
• Zep: A Temporal Knowledge Graph Architecture for Agent Memory

概述

Graphiti 是一个面向 AI 智能体的时序感知知识图谱框架，其底层存储依赖可插拔的图数据库驱动层。该驱动层位于 graphiti_core/driver/ 目录下，通过统一的抽象接口对接多种图数据库后端，使得上层的数据提取、社区检测、混合检索等逻辑可以独立于具体后端实现。

根据 README.md 的安装说明，Graphiti 当前官方支持的图数据库包括：

• Neo4j（推荐版本 5.26）
• FalkorDB（推荐版本 1.1.2）
• Amazon Neptune：支持 Database Cluster 或 Neptune Analytics Graph，配套 Amazon OpenSearch Serverless 作为全文检索后端
• Kuzu（推荐版本 0.11.2，但已标记为 deprecated）

资料来源：README.md

支持的后端概览

下表汇总了各后端驱动的关键信息，便于开发者根据生产环境与功能需求进行选型。

资料来源：README.md、examples/quickstart/README.md、mcp_server/src/graphiti_mcp_server.py

驱动层架构

Graphiti 的驱动层采用了"抽象基类 + 后端实现"的经典模式：

graph LR
    A[Graphiti Core] --> B[GraphDriver 抽象接口<br/>driver.py]
    B --> C[Neo4jDriver<br/>neo4j_driver.py]
    B --> D[FalkorDBDriver<br/>falkordb_driver.py]
    B --> E[KuzuDriver<br/>kuzu_driver.py]
    B --> F[NeptuneDriver<br/>neptune_driver.py]
    B --> G[operations/<br/>__init__.py]
    G --> H[建索引/约束/查询]

GraphDriver 基类在 graphiti_core/driver/driver.py 中定义，统一了连接管理、查询执行、参数传递与索引维护等接口；具体后端在各自的 *_driver.py 文件中继承并实现 Cypher 或类 Cypher 方言。共享的图操作（例如索引创建、约束校验、批量导入）则集中在 graphiti_core/driver/operations/__init__.py 中，以避免在每个驱动中重复实现。

这种分层设计直接回应了社区中 #248 关于"框架与 Neo4j 耦合过紧、希望增加通用图存储接口"的诉求，使得后续接入 MemGraph（#642）或 Postgres+pgvector（#779）成为可演进的架构路径。

配置与连接

各后端通过环境变量进行连接配置，以下变量来自 examples/quickstart/README.md 与 examples/azure-openai/README.md：

Neo4j

export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your-password

URI 必须以 bolt:// 或 neo4j:// 开头。若遇到 Graph not found: default_db 错误，是因为 Neo4j 驱动默认使用 neo4j 数据库名，需在驱动构造时显式指定数据库。

FalkorDB

export FALKORDB_URI=falkor://localhost:6379

FalkorDB 是 mcp_server/src/graphiti_mcp_server.py 的默认后端，其优势在于轻量级与 Redis 协议兼容性。最近的 v0.29.2 版本针对 FalkorDB 修复了若干问题：

• 移除参数中的 NUL 字节（#1531）
• 修复 FalkorDB profile 在 docker-compose 中无法启动的问题（#1126）

Amazon Neptune

Neptune 需要额外配置 OpenSearch Serverless 集合作为全文检索后端，具体步骤参见 README.md。

Kuzu（已弃用）

虽然 graphiti_core/driver/kuzu_driver.py 仍保留在代码库中，但 README.md 已将其标记为 deprecated，新部署不应再选择此驱动。

社区反馈与扩展方向

驱动层是社区最关心的扩展点之一，以下是与本页直接相关的高频议题：

常见故障模式

1. Neo4j 数据库不存在：默认驱动连接名为 neo4j 的数据库，需在脚本中显式指定。
2. FalkorDB 参数异常：v0.29.2 之前可能因 NUL 字节导致写入失败，升级后可解决。
3. Neptune 全文检索缺失：未配置 OpenSearch Serverless 时，部分搜索功能不可用。
4. Kuzu 兼容性问题：0.11.2 以上版本可能不再兼容，建议迁移至 FalkorDB 或 Neo4j。

See Also

• 快速上手示例
• Azure OpenAI + Neo4j 示例
• Graphiti MCP Server
• 论文：Zep — A Temporal Knowledge Graph Architecture for Agent Memory

概述

Graphiti 的抽取与检索流程建立在三类可插拔的 AI 服务之上：LLM 客户端负责实体抽取、关系推断与自然语言回答；嵌入器（Embedder）将文本映射为向量以支撑语义检索；重排序器（Reranker）则在混合召回完成后对候选结果做精排。三者通过统一配置注入到 Graphiti 主体与 MCP Server 中，用户可在不修改业务代码的情况下替换供应商。

资料来源：README.md:1-30

支持的 LLM 提供商

Graphiti 在 mcp_server/README.md 的 config.yaml 中以 ${VAR_NAME} 形式暴露了多组环境变量，按需启用不同 LLM 供应商：

README.md 进一步提示，应选择支持结构化输出（structured outputs / JSON mode）的 LLM，以保障实体与关系抽取的稳定性。社区方面，Issue #459「Support for Amazon Bedrock」（12 条评论）反映出 Bedrock 仍是呼声较高的待集成项，目前的客户端矩阵尚未涵盖。

资料来源：mcp_server/README.md:18-41、README.md:96-100

嵌入器与混合检索召回

嵌入器负责把事实、节点和查询文本映射到统一的向量空间，是 Graphiti 混合检索的基础设施。examples/azure-openai/README.md 演示了通过 AsyncOpenAI(base_url=f"{azure_endpoint}/openai/v1/", ...) 接入 Azure OpenAI 后，分别实例化 AzureOpenAILLMClient 与对应的 Embedder 客户端——后者使用 AZURE_OPENAI_EMBEDDING_DEPLOYMENT 指定的部署名。examples/quickstart/README.md 进一步说明，节点级搜索直接基于嵌入向量的余弦相似度完成召回。

MCP Server 在 add_memory 工具的 docstring 中建议：写入情节（episode）时应「provide descriptive names and detailed content to improve search quality」，因为文本越具体，嵌入质量越高，后续语义检索与重排序效果越好。

资料来源：examples/azure-openai/README.md:1-90、examples/quickstart/README.md:18-32

重排序器与混合检索流水线

Graphiti 的检索结果来自多层信号的融合，定义在 graphiti_core/search/search_config_recipes.py 中，由 MCP Server 通过 search_config 透出：

flowchart LR
    Q[查询] --> SEM[语义召回<br/>Embedder 余弦相似度]
    Q --> KW[BM25 关键词召回]
    Q --> GR[图遍历<br/>以中心节点为锚]
    SEM --> RRF[RRF 融合 + Reranker 精排]
    KW --> RRF
    GR --> RRF
    RRF --> RES[排序后的边/节点结果]

examples/azure-openai/README.md 把这种策略概括为「Hybrid Search combines semantic similarity, BM25 retrieval, and graph traversal」。examples/quickstart/README.md 的「Node Search Using Recipes」章节展示了 NODE_HYBRID_SEARCH_RRF 等预置配方，对节点使用 RRF（Reciprocal Rank Fusion）做最终融合。

资料来源：examples/azure-openai/README.md:14-22、examples/quickstart/README.md:18-32

内容分块与上下文窗口管理

大段对话或长文档在送入 LLM 前会被切分，graphiti_core/utils/content_chunking.py 提供了 token 感知的切分器 _chunk_content：先用 estimate_tokens 估算 token 数（默认 CHARS_PER_TOKEN），超过 CHUNK_MIN_TOKENS 且实体密度较高时按 CHUNK_TOKEN_SIZE 与 CHUNK_OVERLAP_TOKENS 切分；should_chunk 还会依据 JSON 数组元素数或文本实体密度判断是否真正需要切分，避免对叙事散文过度切割。_chunk_speaker_messages 严格按「Speaker: message」边界切分，绝不在消息中间截断，确保 LLM 始终看到完整的发言单元。

资料来源：graphiti_core/utils/content_chunking.py:1-200

自定义类型对 LLM 抽取的影响

MCP Server 在 mcp_server/src/models/entity_types.py 中预置了 Requirement、Preference、Procedure、Location、Event、Object、Topic、Person、Organization、Document 十种富属性 Pydantic 模型（含 description 等字段），并将它们注册到 LLM 抽取提示中，使抽取结果天然携带结构化属性。mcp_server/README.md 指出，默认 config.yaml 已启用这些类型；如需关闭，可将 graphiti.entity_types 置空，恢复为无属性抽取的旧行为。mcp_server/src/services/queue_service.py 的入参 entity_types、edge_types、edge_type_map 也允许在每次 add_episode_task 调用时覆盖默认类型集合。

资料来源：mcp_server/src/models/entity_types.py:1-200、mcp_server/README.md:7-14、mcp_server/src/services/queue_service.py:1-80

常见失败模式

• Neo4j 默认数据库缺失：examples/quickstart/README.md 记录了 Neo.ClientError.Database.DatabaseNotFound: Graph not found: default_db 错误，原因是驱动默认连向 neo4j 数据库。解决方案是在 Neo4jDriver 构造时显式指定 database 参数。
• Azure 部署名错配：examples/azure-openai/README.md 强调必须确保 AZURE_OPENAI_DEPLOYMENT 与 Azure 门户中的实际部署名一致，否则会出现 404 / DeploymentNotFound。
• LLM 缺少结构化输出能力：README.md 提示应选用支持 JSON mode 或 function calling 的模型，否则抽取字段可能为空或格式异常。
• Bedrock 缺位：Issue #459 显示尚未提供 Bedrock 客户端，目前只能通过 openai_generic_client 这类通用客户端间接接入。

资料来源：examples/quickstart/README.md:48-65、examples/azure-openai/README.md:54-66、README.md:96-100

参见

• 数据库驱动与图存储后端（Neo4j、FalkorDB、Neptune、Kuzu）
• 实体、关系与情节（Episode）数据模型
• MCP Server 工具集（add_memory、search_*、build_communities）
• 自定义实体类型与提示工程

概述与核心能力

Graphiti MCP Server 是一个基于 Model Context Protocol（MCP） 的服务端实现，用于把 Graphiti 时序知识图谱的能力以标准协议形式暴露给 AI 助手（例如 Claude、Cursor、GitHub Copilot 等）。与传统的 RAG 不同，Graphiti 通过持续整合对话、企业数据与外部信息，构建可演化的、时序可追溯的上下文图谱。资料来源：mcp_server/README.md:1-15

该服务器通过 FastMCP 实例对外发布工具，核心入口位于 mcp_server/src/graphiti_mcp_server.py。MCP server 提供的能力覆盖五个主要领域：Episode 管理、实体管理、混合搜索、组（group）管理以及图谱维护。资料来源：mcp_server/src/graphiti_mcp_server.py:8-30

关键工具与 API 设计

MCP server 将 Graphiti 核心 API 包装成一组细粒度工具，例如 add_episode、search_nodes、search_facts、get_episode_entities、build_communities、delete_episode 等。add_episode 接受 source 参数，支持 text、message、json 三种内容形态，允许结构化数据进入提取流水线。资料来源：mcp_server/README.md:101-129

所有写入操作都通过 QueueService 异步执行，避免阻塞 MCP 请求循环。add_episode_task 方法接受组 ID 与处理协程，把任务投递到后台队列；add_episode 在调用前会先 parse_reference_time，将无效的时间戳在请求侧立即报错，而不是延迟到后台失败。资料来源：mcp_server/src/services/queue_service.py:15-60，资料来源：mcp_server/src/graphiti_mcp_server.py:75-105

配置体系与后端选项

服务通过 config.yaml、环境变量和命令行参数三层配置（后者优先级最高）。config.yaml 支持 ${VAR_NAME:default} 形式的变量展开，关键变量包括 NEO4J_URI、OPENAI_API_KEY、ANTHROPIC_API_KEY、AZURE_OPENAI_* 系列等。资料来源：mcp_server/README.md:39-58

数据库后端默认是 FalkorDB（与 MCP 服务单容器打包），同时支持 Neo4j。用户可通过 database.provider 切换，并分别配置 falkordb 或 neo4j 段。社区中也出现对 MemGraph、Postgres+pgvector 以及 RDF 三元组存储的需求，目前核心仍以 labeled property graph 为主。资料来源：mcp_server/README.md:175-205，资料来源：community context: Issue #642, #779, #933

LLM 提供方支持 OpenAI、Anthropic、Gemini、Groq、Azure OpenAI，也可通过 OpenAI 兼容协议对接 Ollama 等本地模型。但官方明确建议：Graphiti 依赖结构化 JSON 输出做实体/边提取与去重，小模型常常产生 schema 不匹配的输出，导致摄取失败。资料来源：mcp_server/README.md:225-241

内置的丰富实体类型（Preference、Requirement、Procedure、Location、Event、Person、Organization、Document 等）以 Pydantic 模型注册，并携带提取指令字段（如 description），可通过 graphiti.entity_types 配置启用或禁用。资料来源：mcp_server/src/models/entity_types.py:1-30

部署、并发调优与集成

部署方式有两条路径：通过 uv run main.py 直接运行，或使用 docker compose up 启动预打包的 FalkorDB + MCP 组合容器。默认 HTTP 端点为 http://localhost:8000/mcp/，同时支持 stdio 传输，便于 VS Code、Cursor 等客户端通过 JSON 片段直接接入。资料来源：mcp_server/README.md:73-100，资料来源：mcp_server/README.md:255-280

并发通过 SEMAPHORE_LIMIT 控制同时处理的 episode 数；由于单个 episode 涉及多轮 LLM 调用，实际 LLM 并发请求会更高。代码注释里给出了按 OpenAI Tier 与 Anthropic 配额的经验值（例如 Tier 1 用 1-2，Tier 4 可放宽到 20-50），便于运维按配额调优。资料来源：mcp_server/src/graphiti_mcp_server.py:55-80

对于长对话或长文档，核心库使用 content_chunking.py 提供按 message 边界切分的逻辑，避免在消息中间截断；切分粒度受 CHUNK_TOKEN_SIZE 与 CHUNK_OVERLAP_TOKENS 两个环境变量控制。资料来源：graphiti_core/utils/content_chunking.py:1-50

输出侧，utils/formatting.py 中的 to_node_result 与 to_edge_result 会从实体节点中剥离 embedding 字段，减少响应体积并避免向客户端暴露内部向量。资料来源：mcp_server/src/utils/formatting.py:1-25

下表汇总了部署相关的核心配置项与含义：

See Also

• Graphiti 核心库架构与时序模型：README.md
• Azure OpenAI 集成示例：examples/azure-openai/README.md
• 社区讨论：Amazon Bedrock 支持（Issue #459）、多数据库驱动（#642、#779、#248）、RDF 集成（#933）

Pitfall Log / 踩坑日志

项目：getzep/graphiti

摘要：发现 10 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] ArcadeDB backend support。

1. 安装坑 · 来源证据：[Feature] ArcadeDB backend support

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] ArcadeDB backend support
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/getzep/graphiti/issues/1259 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：[BUG] Cannot get minimal example to work with Ollama

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Cannot get minimal example to work with Ollama
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/getzep/graphiti/issues/868 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:840056306 | https://github.com/getzep/graphiti | host_targets=mcp_host, claude, cursor

4. 配置坑 · 来源证据：MCP server: queue worker silently garbage-collected under streamable-http — add_memory queues but never processes

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：MCP server: queue worker silently garbage-collected under streamable-http — add_memory queues but never processes
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/getzep/graphiti/issues/1574 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:840056306 | https://github.com/getzep/graphiti | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:840056306 | https://github.com/getzep/graphiti | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:840056306 | https://github.com/getzep/graphiti | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:840056306 | https://github.com/getzep/graphiti | no_demo; severity=medium

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:840056306 | https://github.com/getzep/graphiti | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:840056306 | https://github.com/getzep/graphiti | release_recency=unknown