概述

Graphiti 是一个专为在动态环境中运行的 AI 智能体设计的时态感知知识图谱构建和查询框架。Graphiti 构建动态、时态感知的知识图谱，表明实体之间复杂、不断发展的关系。本质上，Graphiti 是一个用于建模和分析随时间演变的复杂关系的工具

Graphiti 的独特之处在于它能够自主构建知识图谱，同时处理变化的关系并维护历史上下文。它是一个实时、时态感知的知识图谱引擎，可以增量处理传入数据，立即更新实体、关系和社区，无需批量重新计算。

⭐ 核心特性

双时态数据模型

Graphiti 的双时态模型跟踪事件发生时间和摄取时间。每个图边（关系）包含明确的有效性区间（t_valid, t_invalid）。Graphiti 是时态的，捕获实际何时有效和无效。这让智能体能够推理状态变化，这是向量数据库无法做到的。

实时增量更新

Graphiti 的实时增量架构专为频繁更新而构建。它持续摄取新数据情节（事件或消息），提取并立即将实体和关系与现有节点进行解析。与传统 RAG 系统不同，工程师不再需要在数据变化时重新计算整个图谱。

混合搜索系统

结合语义嵌入、关键词（BM25）和图遍历，在检索期间无需 LLM 调用即可实现低延迟查询。这种混合搜索方法使用向量和 BM25 索引提供近乎恒定时间的节点和边访问，与图规模无关。

卓越性能

Zep 的 Graphiti 实现实现了极低延迟的检索，在 P95 延迟为 300ms 时返回结果。搜索结果一般在 100ms 以内，延迟主要由第三方嵌入 API 调用决定。

灵活的实体类型

通过简单的 Pydantic 模型支持开发者定义的实体，实现灵活的本体创建。支持定义特定领域的实体类型，为专业应用实现更准确的知识表明。

️ 系统架构

关键组件

• 数据摄取层
• 将数据作为离散情节摄取，维护数据来源并允许增量实体和关系提取
• 同时处理聊天历史、结构化 JSON 数据和非结构化文
• 知识图谱核心
• 支持 Neo4j、FalkorDB、Kuzu 等多种图数据库
• 在图构建期间生成人类可读、语义化和全文可搜索的边表明
• 检索引擎
• 语义搜索（向量嵌入）
• 关键词搜索（BM25）
• 图遍历算法
• 结果融合和重排序

️ 技术栈

• 编程语言: Python 3.10+
• 图数据库: Neo4j 5.26+ / FalkorDB 1.1.2+ / Kuzu 0.11.2+ / Amazon Neptune
• LLM 支持: OpenAI、Anthropic、Voyage 等兼容模型
• API 框架: FastAPI
• 嵌入模型: BGE-m3 等先进嵌入模型

代码示例

基本使用

from graphiti_core import Graphiti
from datetime import datetime

# 初始化 Graphiti
graphiti = Graphiti(
    llm_client=openai_client,
    graph_db_client=neo4j_client
)

# 添加数据情节
await graphiti.add_episode(
    name="用户交互",
    episode_body="Kendra 喜爱 Adidas 鞋子。她上周购买了三双。",
    source_description="客服对话",
    reference_time=datetime.now()
)

# 混合搜索
results = await graphiti.search(
    query="Kendra 的购物偏好",
    num_results=10,
    search_type="hybrid"
)

# 时间点查询
historical_graph = await graphiti.get_graph_at_time(
    timestamp=datetime(2024, 1, 1)
)

MCP 服务器集成

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

• 部署Graphiti服务

services:
  neo4j:
    image: neo4j:5.26.0
    ports:
      - "7474:7474" # HTTP
      - "7687:7687" # Bolt
    environment:
      - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-demodemo}
      - NEO4J_server_memory_heap_initial__size=512m
      - NEO4J_server_memory_heap_max__size=1G
      - NEO4J_server_memory_pagecache_size=512m
    volumes:
      - neo4j_data:/data
      - neo4j_logs:/logs
    healthcheck:
      test: ["CMD", "wget", "-O", "/dev/null", "http://localhost:7474"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  graphiti-mcp:
    image: zepai/knowledge-graph-mcp:latest
    build:
      context: .
      dockerfile: Dockerfile
    env_file:
      - path: .env
        required: false # Makes the file optional. Default value is 'true'
    depends_on:
      neo4j:
        condition: service_healthy
    environment:
      - NEO4J_URI=${NEO4J_URI:-bolt://neo4j:7687}
      - NEO4J_USER=${NEO4J_USER:-neo4j}
      - NEO4J_PASSWORD=${NEO4J_PASSWORD:-demodemo}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - MODEL_NAME=${MODEL_NAME}
      - PATH=/root/.local/bin:${PATH}
      - SEMAPHORE_LIMIT=${SEMAPHORE_LIMIT:-10}
    ports:
      - "8000:8000" # Expose the MCP server via HTTP for SSE transport
    command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse"]

volumes:
  neo4j_data:
  neo4j_logs:

• 配置 MCP 客户端

# MCP 服务器配置
{
    "mcpServers": {
        "graphiti": {
            "transport": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

性能对比

应用场景

1. AI 助手记忆层

从用户交互中学习的助手，将个人知识与来自 CRM 和计费平台等业务系统的动态数据融合。

2. 自主任务代理

自主执行复杂任务的代理，利用来自多个动态源的状态变化进行推理。

3. 企业应用

Graphiti 支持销售、客户服务、健康、金融等领域的广泛应用，为助手和智能体提供长期记忆和基于状态的推理。

4. MCP 客户端集成

为 Claude、Cursor 和其他 MCP 客户端提供强劲的基于知识图谱的记忆。

技术创新

冲突解决机制

当新实际与先前实际相矛盾时，Graphiti 使旧关系无效而不是删除它，为代理推理保留历史。

可扩展性设计

通过使用语义搜索和 BM25 检索相关子图，无论整体图规模如何，都能保持低检索延迟。

模式一致性

通过重用现有模式维护连贯的图结构，防止节点和边类型的不必要扩散

为什么选择 Graphiti？

1. 超越静态 RAG：当前的 RAG 方法在数据频繁更新时难以应对，限制了其在基于代理的系统中的有效性3。
2. 真正的实时性：Graphiti 实现了增量演进的知识图谱，让你的应用实时保持最新7。
3. 生产就绪：Graphiti 支撑着 Zep 的核心，这是一个用于 AI 代理的即插即用上下文工程平台。Zep 提供代理记忆、动态数据的图 RAG 以及上下文检索和组装1。
4. 开源生态：活跃的开源社区，持续的功能更新和改善。