graphiti

图1：Graphiti 将原始对话数据逐步构建为时序知识图谱的全流程 你有没有过这样的困惑——AI 助手聊着聊着就忘了之前说过什么？或者企业知识库里明明有数据，但每次问 AI 它都像第一次听说一样？这个问题正在催生一个全新的技术赛道：上下文记忆框架。Graphiti 就是其中最耀眼的一员。Graphiti 由美国 AI 基础设施公司 Zep AI 于 2023 年末开源，定位为「AI Agent 的时序知识图谱引擎」。其核心理念是：让 AI 不仅记住「是什么」，更能记住「什么时候变成这样的」，以及「这个结论是谁告诉我的」。这不是一个普通的 RAG 替代品——它从根本上重新设计了 Agent 与历史数据交互的方式，被超过 26,000 个 GitHub 项目的开发者认可，并在 2025 年初登上了 arXiv 学术论文平台。想象一个医疗 AI 助手：2024 年 3 月，患者告诉你他对青霉素过敏；2024 年 6 月，他告诉你过敏已经解除。传统的 RAG 系统要么存储所有对话让 LLM 自己判断，要么只保留最新一条让历史彻底丢失。Graphiti 做的，是给每条事实贴上「有效期」标签——「过敏（有效至 2024-06）」vs「不过敏（2024-06 起）」——让 AI 能随时回答「现在」是什么情况，也能查到「当时」是什么情况。这就像给 AI 安装了一个带时间戳的集体记忆硬盘。 图2：Graphiti 处理结构化和非结构化数据的能力对比 Graphiti 的架构分为三层：

Episode（事件层）：原始数据入口，支持对话消息、结构化 JSON、自由文本三种格式。每条数据进来后都会被打上时间戳，成为整条溯源链的起点。

Graph（知识图谱层）：核心引擎，将 Episode 自动解析为 Entity（实体节点）和 Fact/Relationship（关系边）。Entity 会随新数据不断更新摘要（summary），而旧的事实不会被删除——而是被标注「已失效」，形成一条完整的时间线。支持 Pydantic 模型自定义实体类型（prescribed ontology），也支持让 LLM 从数据中自动发现类型（learned ontology）。

Search（检索层）：查询接口，采用混合检索策略——语义向量搜索（embedding）+ 关键词 BM25 + 图谱遍历（graph traversal），不依赖 LLM 做摘要压缩，实现亚秒级查询延迟。这在传统 GraphRAG 需要等待 LLM 生成的场景下，是巨大的体验差距。Graphiti 提供三个主要接入方式：

Python 库（graphiti-core）：核心库，适合集成到现有 Agent 框架（如 LangChain/LangGraph）。通过 Pydantic v2 模型定义数据流，类型安全且可扩展。

FastAPI 服务（server）：开箱即用的 REST API 服务，暴露 /build_graph（构建图谱）、/search（检索）等端点，支持 OpenAPI 文档，适合快速原型验证。

MCP 服务器（MCP Server）：这是近期最热门的用法——Graphiti 通过 Model Context Protocol 暴露工具，让 Claude Desktop、Cursor 等 AI 助手直接读写知识图谱，无需编写代码。官方称每周已有数十万次调用。MCP Server 1.0 于 2025 年初随 20K Stars 里程碑同步发布。技术上，Graphiti 高度依赖以下组件：

图数据库：Neo4j 5.26（生产推荐）或 FalkorDB（轻量替代，支持 Redis 协议）。还支持 Kuzu 和 Amazon Neptune。

LLM Provider：OpenAI（默认）、Anthropic、Gemini、Groq、Azure OpenAI。官方明确建议使用支持 Structured Output 的模型（如 GPT-4o、Gemini），因为实体/关系抽取依赖 JSON Schema，小模型容易出错。

向量嵌入：OpenAI Embeddings（默认）、Voyage AI、Sentence Transformers。还内置 Gliner2 支持多实体联合提取（需 Python 3.11+）。

代码质量方面：项目使用 uv 管理依赖（现代高性能工具），Pyright 严格类型检查（python_version=3.10），完整测试套件 + Ruff lint + pre-commit hooks，遵循 Apache 2.0 许可证，CI 流水线覆盖 Lint、单元测试、类型检查。文档质量极高：README 超过 2000 行，涵盖架构图对比、安装指南、MCP 接入说明。 图3：Zep 团队发表的学术论文，阐述时序知识图谱架构 上手门槛取决于你的选择：

Python 库接入：适合有 LangChain/LangGraph 经验的开发者。核心 API 是 Graphiti.build_graph()（建图）和 Graphiti.search()（检索），上手路径平滑，但需要理解时序知识图谱的概念才能用好。

MCP Server 零代码方案：最友好——安装 Docker，一行 docker compose up，然后在 Claude Desktop 或 Cursor 的 MCP 配置里填入地址即可。不需要写 Python，不需要懂图数据库。FastAPI 服务：介于两者之间，有 REST API 但需要自行处理部署和监控。当前版本存在几个值得注意的局限：

LLM 依赖：实体抽取、关系解析、摘要生成全部依赖 LLM API 调用，意味着运行成本随数据量线性增长，且受制于模型供应商的可用性。

图数据库运维：Neo4j 是生产级选项，但需要独立部署和运维，对于没有图数据库经验的团队有额外学习曲线。FalkorDB 方案相对轻量，但生态较小。

时序一致性的复杂性：当多个 Episode 同时描述同一实体时，LLM 的事实解析结果可能存在不一致，需要应用层做额外的消歧处理。Graphiti 的出现代表了 AI Agent 基础设施的一个重要趋势：从「文档检索」到「结构化记忆」的范式转变。传统的 RAG 在处理动态、多轮、时序敏感的场景时天然受限，而知识图谱天然适合表达实体间的关系和演变。

GitHub Stars 从 0 到 26,000 的增长曲线背后，是整个 AI Agent 生态对「可靠记忆」的迫切需求。从医疗助手、客服机器人到金融分析，任何需要跨越时间理解用户/实体状态的 AI 应用，都能从 Graphiti 的时序图谱能力中受益。

其商业化路径也值得关注：Zep AI 同期提供 Zep Cloud（托管版），提供 SLA、企业安全、运维支持，而 Graphiti 则面向有能力 self-host 的技术团队，形成了清晰的开源→商业闭环。