Graphiti教程：构建时序知识图谱，为AI Agent提供动态记忆

📌 评测日期：2026年8月 | 数据来源：GitHub官方仓库 | 星数：29,500+

📋 项目简介

Graphiti 是 getzep 团队开源的 Python 框架，专注于构建和查询时序上下文知识图谱（Temporal Context Graph）。它能自动将结构化数据（数据库、API）和非结构化数据（文档、对话）转化为动态知识图谱，并跟踪事实的时间有效性——即知道某件事在什么时间段是成立的。

传统知识图谱的痛点在于"静态"——它们记录事实，但不记录事实的时间范围。比如"张三是产品经理"这个事实，如果张三在2025年升职为产品总监，静态图谱会产生矛盾。Graphiti 通过时序建模，可以精确表示"张三在2023-2025年是产品经理，2025年后是产品总监"，为 AI Agent 提供准确的时间感知记忆。

对于构建需要长期记忆的 AI Agent，Graphiti 提供了比传统向量数据库更结构化的记忆方案。结合 代码库记忆MCP方案，可以构建更强大的Agent记忆系统。

🔧 核心功能

📦 安装部署

# 安装Graphiti (需要Python 3.10+, Neo4j 5.x)
pip install graphiti-core

# 启动Neo4j数据库 (使用Docker)
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5.26

# 配置Graphiti连接
export GRAPHITI_NEO4J_URI=bolt://localhost:7687
export GRAPHITI_NEO4J_USER=neo4j
export GRAPHITI_NEO4J_PASSWORD=password

# 配置LLM后端 (用于实体提取)
export OPENAI_API_KEY=your_key_here

# 初始化Graphiti
python -c "
from graphiti import Graphiti
graphiti = Graphiti()
await graphiti.build_index()
print('Graphiti initialized successfully!')
"

💡 使用示例

# 基本用法：从文本构建知识图谱
import asyncio
from graphiti import Graphiti, Episode

async def build_graph():
    graphiti = Graphiti()
    
    # 添加非结构化文本作为Episode
    await graphiti.add_episode(Episode(
        name="公司人事变动通知",
        episode_text="""
        2026年1月15日，张明被任命为产品部VP，直接向CTO李华汇报。
        张明之前担任产品经理3年，负责核心产品的0到1搭建。
        原产品VP王强转任战略顾问。
        """,
        reference_text="公司内部邮件",
        source_description="HR通知"
    ))
    
    # Graphiti自动提取实体、关系和时间信息
    # 查询当前产品部VP是谁
    results = await graphiti.search(
        query="产品部VP是谁",
        num_results=5
    )
    for r in results:
        print(f"事实: {r.fact}")
        print(f"有效期: {r.valid_from} 至 {r.valid_to or '至今'}")

asyncio.run(build_graph())

# 进阶：时序查询 - 查询某个时间点的事实
async def temporal_query():
    graphiti = Graphiti()
    
    # 查询2025年6月时的产品部VP
    results = await graphiti.search(
        query="产品部VP",
        center_time="2025-06-01",
        num_results=5
    )
    
    # 查询张明的职业履历时间线
    timeline = await graphiti.search(
        query="张明的职业经历",
        entity_name="张明",
        num_results=20
    )
    
    # 添加新的结构化数据更新事实
    await graphiti.add_episode(Episode(
        name="组织架构调整",
        episode_text="2026年8月，张明晋升为CTO，产品部VP由陈露接任",
        reference_text="CEO公告",
        source_description="官方公告"
    ))
    # Graphiti自动更新图谱：张明VP事实设为失效，新增CTO事实

asyncio.run(temporal_query())

🔄 竞品对比

📦 使用建议

推荐场景：

• 构建需要长期记忆和时间感知的AI Agent
• 企业知识管理，需要跟踪事实变更历史
• 对话系统的上下文记忆和用户画像构建
• 合规审计场景需要追溯事实时间线

不推荐场景：

• 简单的向量检索场景（用Pinecone/Weaviate即可）
• 无Neo4j运维能力的团队
• 实时性要求极高的在线查询（图谱查询延迟较高）