# https://github.com/getzep/zep 项目说明书
生成时间：2026-06-21 09:09:04 UTC
## 目录
- [仓库概览与目录结构](#page-overview)
- [框架集成包（Integrations）](#page-integrations)
- [多语言示例与 SDK 用法](#page-examples)
- [MCP 服务、评估工具与插件](#page-tools)
## 仓库概览与目录结构
### 相关页面
相关主题：[框架集成包（Integrations）](#page-integrations), [多语言示例与 SDK 用法](#page-examples)
相关源码文件
以下源码文件用于生成本页说明：
- [examples/python/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/chunking-example/README.md)
- [examples/typescript/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/typescript/chunking-example/README.md)
- [examples/go/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/go/chunking-example/README.md)
- [examples/python/user-summary-instructions-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/user-summary-instructions-example/README.md)
- [integrations/crewai/python/README.md](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)
- [integrations/autogen/python/README.md](https://github.com/getzep/zep/blob/main/integrations/autogen/python/README.md)
- [integrations/livekit/python/README.md](https://github.com/getzep/zep/blob/main/integrations/livekit/python/README.md)
- [integrations/adk/typescript/src/graph-search-tool.ts](https://github.com/getzep/zep/blob/main/integrations/adk/typescript/src/graph-search-tool.ts)
- [integrations/adk/python/src/zep_adk/graph_search_tool.py](https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/graph_search_tool.py)
- [zep-eval-harness/README.md](https://github.com/getzep/zep/blob/main/zep-eval-harness/README.md)
# 仓库概览与目录结构
## 一、项目定位与核心能力
`getzep/zep` 是一个面向 AI 助手应用的长期记忆服务仓库，核心目标是提供可被多种智能体框架调用的会话记忆与时序知识图谱能力。从 `examples/python/chunking-example/README.md` 中可以看到，Zep 通过 `ZEP_API_KEY` 接入 OpenAI 等大模型，实现文档分块、上下文增强检索（contextualized retrieval）并写入知识图谱 [资料来源：[examples/python/chunking-example/README.md:17-19]()](https://github.com/getzep/zep/blob/main/examples/python/chunking-example/README.md)。
仓库同时托管多语言示例（Python、TypeScript、Go）和多种第三方框架集成（CrewAI、AutoGen、LiveKit、Google ADK），并配套独立的 `zep-eval-harness` 评估工具，形成了"核心 SDK + 集成 + 示例 + 评测"四位一体的整体布局。最新的 `zep-crewai v1.1.1` 版本聚焦于与 CrewAI v0.186.0+ 的兼容性修复，说明项目对集成适配的迭代非常活跃 [资料来源：[integrations/crewai/python/README.md:1-15]()](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)。
## 二、顶层目录结构
仓库在顶层主要划分为 `examples/`、`integrations/` 和 `zep-eval-harness/` 三大模块，以及用于各 SDK 的配置和测试辅助文件。下表总结了主要子目录的职责划分：
| 目录 | 角色 | 典型内容 |
| --- | --- | --- |
| `examples/` | 跨语言用法样例 | `chunking-example/`、`user-summary-instructions-example/` |
| `integrations/` | 框架级适配包 | `crewai/`、`autogen/`、`livekit/`、`adk/` |
| `zep-eval-harness/` | 端到端评测流水线 | 用户/文档注入、评测运行、配置快照 |
| `examples/{python,typescript,go}/` | 多语言 SDK 示例 | 文档分块、上下文检索脚本 |
`zep-eval-harness/README.md` 中展示的目录树表明，评测工具内部还细分为 `config/`（用户/文档/分块/评测配置）、`data/`（样本数据）以及 `runs/`（带时间戳的运行产物），每一次运行都会冻结配置快照以保证可复现 [资料来源：[zep-eval-harness/README.md:17-42]()](https://github.com/getzep/zep/blob/main/zep-eval-harness/README.md)。
```mermaid
graph TD
A[getzep/zep 仓库] --> B[examples/]
A --> C[integrations/]
A --> D[zep-eval-harness/]
B --> B1[python/chunking-example]
B --> B2[typescript/chunking-example]
B --> B3[go/chunking-example]
B --> B4[user-summary-instructions-example]
C --> C1[crewai/]
C --> C2[autogen/]
C --> C3[livekit/]
C --> C4[adk/]
D --> D1[config/]
D --> D2[data/]
D --> D3[runs/]
```
## 三、集成模块
`integrations/` 目录集中托管 Zep 与主流智能体框架的桥接代码，每个子目录通常包含 Python 与 TypeScript 双语言实现。
### 3.1 CrewAI 集成
`integrations/crewai/python/README.md` 描述了 `ZepUserStorage` 与 `ZepGraphStorage` 两类存储抽象：`ZepUserStorage` 管理用户线程与个人图谱，提供并行搜索与 `thread.get_user_context()` 自动上下文装配；`ZepGraphStorage` 则用于管理共享知识图，支持自定义实体模型与多范围搜索（edges / nodes / episodes）[资料来源：[integrations/crewai/python/README.md:30-70]()](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)。同时提供了 `create_search_tool` 与 `create_add_data_tool` 工厂方法，可直接绑定到 `user_id` 或 `graph_id` 范围。
### 3.2 AutoGen 集成
`integrations/autogen/python/README.md` 通过 `ZepUserMemory` 把 Zep 注入到 AutoGen 的 `AssistantAgent` 中，仅需将 `memory=[memory]` 传入即可获得跨会话的持久记忆 [资料来源：[integrations/autogen/python/README.md:14-44]()](https://github.com/getzep/zep/blob/main/integrations/autogen/python/README.md)。同样暴露 `create_search_graph_tool` 与 `create_add_graph_data_tool` 以供模型按需调用。
### 3.3 LiveKit 集成
`integrations/livekit/python/README.md` 描述了两种图谱访问路径：`ZepUserAgent` 通过线程自动丰富统一图谱，适合客服、教学等场景；`ZepGraphAgent` 则绕过线程直接以事实、实体、关系的形式操作知识图，适合企业知识库与协作助手 [资料来源：[integrations/livekit/python/README.md:30-55]()](https://github.com/getzep/zep/blob/main/integrations/livekit/python/README.md)。
### 3.4 Google ADK 集成
ADK 集成在两个语言下都提供了"上下文自动注入"与"按需搜索"两条路径。`integrations/adk/typescript/src/graph-search-tool.ts` 中的 `ZepGraphSearchTool` 暴露在模型工具列表里，按 `graphId` 或运行时解析的 `userId` 进行知识图谱搜索 [资料来源：[integrations/adk/typescript/src/graph-search-tool.ts:18-40]()](https://github.com/getzep/zep/blob/main/integrations/adk/typescript/src/graph-search-tool.ts)。Python 版 `integrations/adk/python/src/zep_adk/graph_search_tool.py` 则更进一步，允许在构造时将查询参数"钉死"（pinned），剩余参数才暴露给模型 [资料来源：[integrations/adk/python/src/zep_adk/graph_search_tool.py:18-45]()](https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/graph_search_tool.py)。
## 四、示例模块与评测工具
`examples/` 提供可直接运行的最佳实践模板。`chunking-example` 演示了 Anthropic 提出的 contextualized retrieval：用 OpenAI 为每个分块生成上下文描述，再作为 Zep episode 注入知识图谱，默认 6000 字符的分块大小为上下文前缀留出余量，且严格低于 Zep 的 10K 字符 episode 限制 [资料来源：[examples/python/chunking-example/README.md:60-70]()](https://github.com/getzep/zep/blob/main/examples/python/chunking-example/README.md)。
`user-summary-instructions-example` 则聚焦于"用户摘要指令"，通过预定义"用户预算、卧室数、必选特征、地段偏好"等问题，确保关键信息无论检索上下文如何变化都会出现在上下文块中，并由 `RealEstateSalesAgent` 通过 `thread.get_user_context()` 拉取 [资料来源：[examples/python/user-summary-instructions-example/README.md:11-35]()](https://github.com/getzep/zep/blob/main/examples/python/user-summary-instructions-example/README.md)。
`zep-eval-harness/` 是仓库内独立维护的评测流水线，覆盖用户注入、文档注入（含自定义本体与指令）、分块与运行评估四个步骤，并要求在 `runs/` 中保留每次运行的时间戳、清单与配置快照，便于回溯实验结果 [资料来源：[zep-eval-harness/README.md:44-72]()](https://github.com/getzep/zep/blob/main/zep-eval-harness/README.md)。
## 五、版本与社区关注点
仓库的发布节奏以 Zep 服务版本（如 v1.0.0 社区版、v1.0.2 加入 PostgreSQL URL 转义）为主线，并按子包发布独立 tag，例如 `zep-crewai-v1.1.1` 修复了 CrewAI v0.186.0+ 的兼容性，搜索结果键从 `memory` 改为 `context` [资料来源：[integrations/crewai/python/README.md:1-15]()](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)。早期版本还曾围绕 OpenAI 模型切换（gpt-4o-mini 默认、Azure 嵌入修复）、元数据锁的指数退避重试等主题持续演进，这些都可以在 `zep-eval-harness` 的评测结果与 release notes 中交叉验证。
## See Also
- [examples/python/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/chunking-example/README.md)
- [integrations/crewai/python/README.md](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)
- [integrations/livekit/python/README.md](https://github.com/getzep/zep/blob/main/integrations/livekit/python/README.md)
- [integrations/adk/python/src/zep_adk/graph_search_tool.py](https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/graph_search_tool.py)
- [zep-eval-harness/README.md](https://github.com/getzep/zep/blob/main/zep-eval-harness/README.md)
---
## 框架集成包（Integrations）
### 相关页面
相关主题：[仓库概览与目录结构](#page-overview), [多语言示例与 SDK 用法](#page-examples)
相关源码文件
以下源码文件用于生成本页说明：
- [integrations/README.md](https://github.com/getzep/zep/blob/main/integrations/README.md)
- [integrations/crewai/python/README.md](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)
- [integrations/crewai/python/CHANGELOG.md](https://github.com/getzep/zep/blob/main/integrations/crewai/python/CHANGELOG.md)
- [integrations/autogen/python/README.md](https://github.com/getzep/zep/blob/main/integrations/autogen/python/README.md)
- [integrations/livekit/python/README.md](https://github.com/getzep/zep/blob/main/integrations/livekit/python/README.md)
- [integrations/adk/python/src/zep_adk/graph_search_tool.py](https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/graph_search_tool.py)
- [integrations/adk/typescript/src/graph-search-tool.ts](https://github.com/getzep/zep/blob/main/integrations/adk/typescript/src/graph-search-tool.ts)
- [examples/typescript/langgraph/README.md](https://github.com/getzep/zep/blob/main/examples/typescript/langgraph/README.md)
- [examples/python/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/chunking-example/README.md)
- [zep-eval-harness/README.md](https://github.com/getzep/zep/blob/main/zep-eval-harness/README.md)
# 框架集成包（Integrations）
## 一、概述与定位
Zep 的 `integrations/` 目录是一组与第三方智能体框架、语言模型应用编排库和实时通信平台对接的官方适配层。每一个集成包都遵循共同的设计目标：把 Zep 的"时序知识图谱 + 用户级上下文"能力，以最小代码改动的方式接入到目标框架的抽象里（如 CrewAI 的 `Storage`、AutoGen 的 `memory=`、LiveKit 的 `AgentSession`、ADK 的 `BaseTool`）。
社区近期最活跃的关注点集中在 `zep-crewai`，其中 `zep-crewai v1.1.1` 专门修复了与 CrewAI 0.186.0+ 的兼容性——将外部记忆搜索结果键名从 `"memory"` 改为 `"context"`，并同步更新了 `ZepUserStorage` / `ZepGraphStorage` / `ZepStorage` 的实现，这是目前用户升级集成包时最容易踩到的破坏性变更点。资料来源：[integrations/crewai/python/CHANGELOG.md:1-20]()。
## 二、集成包清单与覆盖范围
下表汇总了 `integrations/` 下目前可观察到的官方适配包及其典型用例（基于仓库 `README.md` 中的目录命名）：
| 集成包 | 语言 | 目标框架 | 主要组件 | 典型使用场景 |
| --- | --- | --- | --- | --- |
| `zep-crewai` | Python | CrewAI | `ZepUserStorage`、`ZepGraphStorage`、`create_search_tool`、`create_add_data_tool` | 多智能体协作、知识库维护、个人助理 |
| `zep-autogen` | Python | Microsoft AutoGen | `ZepUserMemory`、`create_search_graph_tool`、`create_add_graph_data_tool` | 持久化会话记忆、工具增强型 Agent |
| `zep-livekit`（目录名 `zep_livekit`） | Python | LiveKit Agents | `ZepUserAgent`、`ZepGraphAgent` | 语音 AI 助理、客服、知识图谱对话 |
| `zep-adk` | Python + TypeScript | Google ADK | `ZepGraphSearchTool`、`ZepContextTool` | 自动上下文注入、按需检索工具 |
| `examples/langgraph` | TypeScript | LangGraph.js | CLI Agent 示例 | 命令行 Agent + Tavily 搜索 + Zep 记忆 |
资料来源：[integrations/crewai/python/README.md:1-40]()、[integrations/autogen/python/README.md:1-30]()、[integrations/livekit/python/README.md:1-25]()、[integrations/adk/typescript/src/graph-search-tool.ts:1-25]()。
## 三、核心设计模式
### 3.1 双轨存储：`ZepUserStorage` 与 `ZepGraphStorage`
CrewAI 集成包把 Zep 的两类图谱（用户个人图 vs. 共享知识图）映射为两种独立但 API 对齐的存储对象。`ZepUserStorage` 把记忆绑定到 `(user_id, thread_id)`，最终拼装 Zep 的自动 Context Block；`ZepGraphStorage` 则面向 `(graph_id)`，支持通过 `set_ontology(...)` 注册实体/边类型后再写入。资料来源：[integrations/crewai/python/README.md:80-120]()。
### 3.2 工具化访问：搜索与写入
每个集成包都暴露一对"搜索 / 写入"工具函数，用于把 Zep 的图谱能力作为 LLM 可调用的工具暴露出来。例如 CrewAI 集成通过 `create_search_tool(zep_client, user_id=...)` 或 `create_search_tool(zep_client, graph_id=...)` 决定作用域，搜索范围支持 `edges / nodes / episodes / all`。资料来源：[integrations/crewai/python/README.md:30-70]()。
### 3.3 自动上下文注入 vs. 按需检索
ADK 集成明确区分了两种注入策略：`ZepContextTool` 在每一轮自动注入上下文，而 `ZepGraphSearchTool` 则出现在模型的工具列表里，由模型在需要时主动调用；其参数还支持在构造期"pin"——被锁定的参数将从模型可见的 schema 中移除，仅保留未锁定的参数供模型自行调整。资料来源：[integrations/adk/python/src/zep_adk/graph_search_tool.py:1-45]()、[integrations/adk/typescript/src/graph-search-tool.ts:1-50]()。
### 3.4 实时语音集成
LiveKit 集成通过 `ZepUserAgent` 将会话线程与用户绑定、把语音转写结果写入时序图谱；同时提供 `ZepGraphAgent` 直接对共享图谱进行语义检索，二者底层使用同一个时序知识图谱，但入口不同。资料来源：[integrations/livekit/python/README.md:15-60]()。
## 四、配套示例与评估
仓库在 `examples/` 与 `zep-eval-harness/` 中提供可直接运行的端到端样例：
- `examples/python/chunking-example/`、`examples/typescript/chunking-example/`、`examples/go/chunking-example/` 演示 Anthropic "Contextualized Retrieval" 思路：先用 LLM 为每个 chunk 生成上下文描述，再写入 Zep 图谱，以提升检索准确性。资料来源：[examples/python/chunking-example/README.md:1-30]()。
- `examples/typescript/langgraph/` 提供一个集成 Tavily 搜索与 Zep 记忆的 LangGraph.js CLI Agent，通过 `--user-id` / `--thread-id` 切换会话上下文。资料来源：[examples/typescript/langgraph/README.md:1-35]()。
- `zep-eval-harness/` 是一套可复现的评估流水线：依次执行 `zep_ingest_users.py → zep_chunk_documents.py → zep_ingest_documents.py → zep_evaluate.py`，每一步都把当时的 `*_config/` 配置快照写入 `runs/{N}_{timestamp}/`，便于对比不同本体（ontology）与 user-summary-instructions 对检索质量的影响。资料来源：[zep-eval-harness/README.md:40-120]()。
## 五、升级与兼容性注意事项
1. **CrewAI 1.x 适配**：`ZepUserStorage`、`ZepGraphStorage`、`ZepStorage` 已不再是 `crewai.memory.storage` 的子类，而是独立适配器，统一通过 `save / search / reset` 与 `ZepSearchTool` / `ZepAddDataTool` 配合使用；搜索结果键由 `memory` 改为 `context`。资料来源：[integrations/crewai/python/README.md:20-45]()、[integrations/crewai/python/CHANGELOG.md:1-20]()。
2. **API Key**：所有集成包都依赖 `ZEP_API_KEY`，部分示例还需要 `OPENAI_API_KEY`、`TAVILY_API_KEY` 等，应统一放入 `.env`。
3. **异步 vs. 同步**：CrewAI、AutoGen、ADK 都同时提供 `Zep`（同步）与 `AsyncZep`（异步）客户端；LiveKit 因基于事件循环，默认使用 `AsyncZep`。
4. **数据处理时延**：写入 Zep 后通常需要 10–20 秒才能完成实体/边的抽取与嵌入，建议在评测或回放场景中预留缓冲。资料来源：[integrations/crewai/python/README.md:130-150]()。
## See Also
- [Zep 主仓库与 SDK 概览](./README.md)
- [评估与基准测试（Harness）](./evaluation-harness.md)
- [上下文分块与 Contextualized Retrieval](./chunking-contextualized-retrieval.md)
- [LiveKit 实时语音集成](./integrations-livekit.md)
- [Google ADK 工具集成](./integrations-adk.md)
- [CrewAI 适配器与升级指南](./integrations-crewai.md)
---
## 多语言示例与 SDK 用法
### 相关页面
相关主题：[框架集成包（Integrations）](#page-integrations), [仓库概览与目录结构](#page-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [examples/typescript/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/typescript/chunking-example/README.md)
- [examples/python/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/chunking-example/README.md)
- [examples/go/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/go/chunking-example/README.md)
- [examples/python/user-summary-instructions-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/user-summary-instructions-example/README.md)
- [examples/typescript/langgraph/README.md](https://github.com/getzep/zep/blob/main/examples/typescript/langgraph/README.md)
- [zep-eval-harness/README.md](https://github.com/getzep/zep/blob/main/zep-eval-harness/README.md)
- [integrations/crewai/python/README.md](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)
- [integrations/autogen/python/README.md](https://github.com/getzep/zep/blob/main/integrations/autogen/python/README.md)
- [integrations/livekit/python/README.md](https://github.com/getzep/zep/blob/main/integrations/livekit/python/README.md)
- [integrations/adk/python/src/zep_adk/graph_search_tool.py](https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/graph_search_tool.py)
- [integrations/adk/typescript/src/graph-search-tool.ts](https://github.com/getzep/zep/blob/main/integrations/adk/typescript/src/graph-search-tool.ts)
# 多语言示例与 SDK 用法
Zep 仓库在 `examples/` 与 `integrations/` 目录下提供了覆盖 Python、TypeScript、Go 等多种语言的端到端示例，以及面向主流智能体框架（AutoGen、CrewAI、Google ADK、LiveKit、LangGraph）的集成包。本页梳理这些示例与集成 SDK 的功能定位、典型工作流和配置约定，帮助开发者根据目标语言与框架快速选择合适的入门路径。
## 一、官方语言示例（Examples）
### 1.1 文档分块与上下文增强检索（Contextualized Retrieval）
`examples/python/chunking-example`、`examples/typescript/chunking-example` 与 `examples/go/chunking-example` 三份 README 描述了同一模式：在将文档摄入 Zep 知识图谱前，先用 OpenAI 为每个文本块生成上下文描述，再将“上下文 + 原文”拼接后写入 Episode。默认块大小为 6000 字符，留出空间容纳上下文前缀，同时不超出 Zep 单条 Episode 的 10K 字符上限 资料来源：[examples/python/chunking-example/README.md:21-25]()。
```bash
python chunk_and_ingest.py sample_document.txt --user-id user123
```
脚本内置对 OpenAI 速率限制的指数退避重试，并将失败块单独计数，确保部分失败时仍能完成处理 资料来源：[examples/python/chunking-example/README.md:55-57]()。
### 1.2 User Summary Instructions（用户摘要指令）
`examples/python/user-summary-instructions-example` 通过房地产销售助手示例展示了“User Summary Instructions”特性：开发者向 Zep 注册一组必须始终出现在上下文中的关键问题（例如预算、卧室数量、必选设施），Zep 会在每次 `thread.get_user_context()` 调用时持续提炼并返回这些事实 资料来源：[examples/python/user-summary-instructions-example/README.md:11-19]()。
该示例还提供了一个 Streamlit 仪表盘（`ui.py`），可在“开启/关闭”用户摘要指令之间进行对比，便于直观评估记忆增强效果 资料来源：[examples/python/user-summary-instructions-example/README.md:34-36]()。
### 1.3 LangGraph CLI 代理（TypeScript）
`examples/typescript/langgraph` 提供一个基于 LangGraph.js 的命令行代理，通过 Commander.js 暴露 `--userId`、`--threadId`、`--system-message`、`--debug` 等参数，并在会话之间通过 Zep 持久化记忆 资料来源：[examples/typescript/langgraph/README.md:24-43]()。所需密钥包括 `OPENAI_API_KEY`、`TAVILY_API_KEY` 与 `ZEP_API_KEY` 资料来源：[examples/typescript/langgraph/README.md:12-17]()。
## 二、评估与流水线工具（Eval Harness）
`zep-eval-harness` 是一套独立的评估流水线，涵盖用户/文档摄入、文档分块、图谱查询与 LLM 打分等步骤。每个步骤在 `runs/{users|documents|chunk_sets|evaluations}/{N}_{timestamp}/` 下生成带时间戳的运行目录，并自动保存当时的配置快照以保证可复现性 资料来源：[zep-eval-harness/README.md:34-50]()。
```mermaid
flowchart LR
A[users.json] --> B[zep_ingest_users.py]
C[documents/] --> D[zep_chunk_documents.py]
D --> E[chunks.jsonl]
E --> F[zep_ingest_documents.py]
B & F --> G[(Zep Graph)]
G --> H[zep_evaluate.py]
H --> I[results.json]
```
所有步骤共享指数退避重试（最多 8 次、最大 5 分钟延迟），并且评估步骤可通过 `--concurrency` 控制并发 资料来源：[zep-eval-harness/README.md:78-86]()。运行目录下的 `manifest.json` 记录了图谱 ID、块集大小、本体类型与自定义指令名称等元数据 资料来源：[zep-eval-harness/README.md:24-32]()。
## 三、第三方框架集成 SDK
Zep 在 `integrations/` 目录下为常见智能体框架提供了官方集成包，核心抽象是对用户/图谱存储以及图谱搜索/添加工具的封装。
| 集成包 | 语言 | 主要组件 | 来源 |
| --- | --- | --- | --- |
| zep-crewai | Python | `ZepUserStorage`、`ZepGraphStorage`、`create_search_tool`、`create_add_data_tool` | [integrations/crewai/python/README.md:11-26]() |
| zep-autogen | Python | `ZepUserMemory`（接入 AutoGen `memory` 列表）、`create_search_graph_tool`、`create_add_graph_data_tool` | [integrations/autogen/python/README.md:15-38]() |
| zep-livekit | Python | LiveKit 代理中的 Zep 记忆桥接 | [integrations/livekit/python/README.md]() |
| zep-adk (Python) | Python | `ZepContextTool`（自动注入）、`ZepGraphSearchTool`（按需搜索） | [integrations/adk/python/src/zep_adk/graph_search_tool.py:1-29]() |
| zep-adk (TypeScript) | TypeScript | `ZepGraphSearchTool`，支持 `graphId` 固定与 `zep_user_id` 运行时解析 | [integrations/adk/typescript/src/graph-search-tool.ts:1-32]() |
### 3.1 CrewAI 集成
`zep-crewai` 提供两类存储与两类工具：`ZepUserStorage` 用于用户/线程级记忆，`ZepGraphStorage` 用于共享知识图谱；`create_search_tool` 与 `create_add_data_tool` 则将 Zep 的图谱读写能力包装为 CrewAI 可调用的工具，支持自然语言查询与 JSON / Message 数据写入 资料来源：[integrations/crewai/python/README.md:11-26]()。最新版本 `zep-crewai v1.1.1` 已修复与 CrewAI v0.186.0+ 的兼容性问题，将外部记忆搜索结果键从 `"memory"` 调整为 `"context"` 资料来源：[integrations/crewai/python/README.md](https://github.com/getzep/zep/releases/tag/zep-crewai-v1.1.1)。
### 3.2 AutoGen 集成
`zep-autogen` 通过 `ZepUserMemory` 直接挂入 AutoGen `AssistantAgent` 的 `memory` 列表，从而为代理启用跨会话持久记忆；额外提供的 `create_search_graph_tool` 与 `create_add_graph_data_tool` 让代理可对共享图谱进行查询与写入 资料来源：[integrations/autogen/python/README.md:17-38]()。
### 3.3 Google ADK 集成（Python & TypeScript）
ADK 集成区分两种工具语义：
- `ZepContextTool` 在每一轮自动注入上下文；
- `ZepGraphSearchTool` 暴露在模型的工具列表中，按需调用。
Python 实现支持在构造时**钉住（pin）**任意 `graph.search` 参数，被钉住的字段将从模型可见的 schema 中移除，其余字段附带默认值 资料来源：[integrations/adk/python/src/zep_adk/graph_search_tool.py:21-37]()。TypeScript 实现则使用 `resolveIdentity` 在 `graphId` → `zep_user_id` → ADK `userId` 的优先级链中解析目标用户/图谱 资料来源：[integrations/adk/typescript/src/graph-search-tool.ts:13-21]()。
### 3.4 LiveKit 集成
`integrations/livekit/python` 提供 `make test`、`make pre-commit`、`make ci` 等 Make 目标，并依赖 Zep 云服务的 API Key 与 LiveKit 项目凭证，将 Zep 的长期记忆接入实时语音/视频代理 资料来源：[integrations/livekit/python/README.md]()。
## 四、常见选择建议
- **快速原型**：从语言对应的 `examples//simple` 或 LangGraph CLI 示例入手，最少配置即可运行；
- **RAG 增强**：直接复用 `chunking-example` 三件套（Python/TypeScript/Go），仅需提供 `ZEP_API_KEY` 与 `OPENAI_API_KEY`；
- **多代理协作**：选择 `integrations/crewai` 或 `integrations/autogen`，通过其存储/工具抽象复用 Zep 的用户与图谱能力；
- **生产评估**：使用 `zep-eval-harness` 进行可复现的端到端评测，并通过 `--resume` 恢复中断的摄入作业 资料来源：[zep-eval-harness/README.md:62-75]()。
## See Also
- [Zep 文档总览（help.getzep.com）](https://help.getzep.com)
- [CrewAI v0.186.0+ 兼容性修复说明](https://github.com/getzep/zep/releases/tag/zep-crewai-v1.1.1)
- [Zep Community Edition v1.0.0 发布说明](https://github.com/getzep/zep/releases/tag/v1.0.0)
---
## MCP 服务、评估工具与插件
### 相关页面
相关主题：[仓库概览与目录结构](#page-overview), [框架集成包（Integrations）](#page-integrations)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/zep-mcp-server/README.md](https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/README.md)
- [zep-eval-harness/README.md](https://github.com/getzep/zep/blob/main/zep-eval-harness/README.md)
- [integrations/crewai/python/README.md](https://github.com/getzep/zep/blob/main/integrations/crewai/python/README.md)
- [integrations/autogen/python/README.md](https://github.com/getzep/zep/blob/main/integrations/autogen/python/README.md)
- [integrations/livekit/python/README.md](https://github.com/getzep/zep/blob/main/integrations/livekit/python/README.md)
- [integrations/adk/typescript/src/graph-search-tool.ts](https://github.com/getzep/zep/blob/main/integrations/adk/typescript/src/graph-search-tool.ts)
- [integrations/adk/python/src/zep_adk/graph_search_tool.py](https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/graph_search_tool.py)
- [examples/python/user-summary-instructions-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/user-summary-instructions-example/README.md)
- [examples/python/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/python/chunking-example/README.md)
- [examples/typescript/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/typescript/chunking-example/README.md)
- [examples/go/chunking-example/README.md](https://github.com/getzep/zep/blob/main/examples/go/chunking-example/README.md)
# MCP 服务、评估工具与插件
## 概述
Zep 项目围绕「时序知识图谱 + 长期记忆」提供了一组面向生产与工程化的辅助子系统，本页聚焦于以下三个方向：
- **MCP 服务**（Model Context Protocol Server）：把 Zep Cloud 的图谱与记忆能力以**只读**工具的形式暴露给 Claude Desktop、Cline 等 MCP 客户端。资料来源：[mcp/zep-mcp-server/README.md]()
- **评估工具**（zep-eval-harness）：提供可复现的「摄取 → 分块 → 评测」流水线，用于在自定义数据集上度量 Zep 的检索与摘要质量。资料来源：[zep-eval-harness/README.md]()
- **插件与集成**（CrewAI、AutoGen、LiveKit、ADK 等）：把 Zep 嵌入到主流智能体框架与实时通信栈中。资料来源：[integrations/crewai/python/README.md]()、[integrations/autogen/python/README.md]()、[integrations/livekit/python/README.md]()
## MCP 服务（zep-mcp-server）
`zep-mcp-server` 是一个用 Go 编写的**只读** MCP 服务器，目标是让 AI 助手在不修改 Zep 数据的前提下查询用户与图谱。资料来源：[mcp/zep-mcp-server/README.md]()
服务器内置 13 个只读工具，按职责可分为三组：
| 工具分组 | 典型工具 | 主要用途 |
|---------|---------|---------|
| 检索与上下文 | `search_graph`、`get_user_context`、`get_user`、`list_threads` | 提供按过滤器、重排序与自定义模板的上下文检索 |
| 图谱查询 | `get_user_nodes`、`get_user_edges`、`get_episodes` | 拉取实体节点、关系边、时间事件节点 |
| 细节获取 | `get_thread_messages`、`get_node`、`get_edge` | 按 UUID 精确定位消息、节点或边 |
资料来源：[mcp/zep-mcp-server/README.md]()
服务端构建在「Zep Go SDK v3 + MCP Go SDK + godotenv」之上，以 Apache 2.0 开源；支持 Docker 与 docker compose 部署，并配套有 `docs/TOOLS.md`（每个工具的详细文档）与 `docs/DOCKER.md`（容器化使用说明）。资料来源：[mcp/zep-mcp-server/README.md]()
```mermaid
flowchart LR
A[MCP 客户端
Claude Desktop / Cline] --> B[zep-mcp-server
Go MCP Server]
B --> C[Zep Go SDK v3]
C --> D[(Zep Cloud
时序知识图谱)]
B -.只读工具.-> A
```
## 评估工具 zep-eval-harness
`zep-eval-harness` 是一个面向「Zep 检索质量」的可复现评测流水线。其核心目录按配置与执行阶段划分：
- `config/user_ingestion_config/`：用户图谱的本体（`ontology.py`）与自定义指令（`custom_instructions.py`）；
- `config/document_ingestion_config/`：文档图谱的本体与指令；
- `config/document_chunking_config/constants.py`：包含 `CHUNK_SIZE`、`CHUNK_OVERLAP`、`LLM_CONTEXTUALIZATION_MODEL` 等常量；
- `config/evaluation_config/response_prompt.py`：通过 `get_response_system_prompt()` 注入响应系统提示，可在不动评测逻辑的情况下单独定制。
资料来源：[zep-eval-harness/README.md]()
每次执行会把产物写入 `runs/{users|documents|chunk_sets|evaluations}/{N}_{timestamp}/` 子目录，并在其中保存 **config 快照**（例如 `user_ingestion_config_snapshot/`），保证后续即便修改了配置也能复现历史结果。资料来源：[zep-eval-harness/README.md]()
典型流水线按以下顺序执行：
1. `zep_ingest_users.py`：把 `data/users.json` 写入 Zep 用户图谱，支持 `--custom-ontology`、`--custom-instructions`、`--user-summary-instructions`；
2. `zep_chunk_documents.py`（可选）：对文档做带上下文化的分块，写入 `chunks.jsonl`，支持 `--chunk-size`、`--concurrency` 与断点续传；
3. `zep_ingest_documents.py`：把分块结果摄取进共享文档图谱，可用 `--chunk-set` 复用历史分块，或用 inline 模式现分现取；
4. `zep_evaluate.py`：组合用户运行与文档运行，产出 `results.json`，支持 `--user-run`、`--doc-run`、`--concurrency`。
资料来源：[zep-eval-harness/README.md]()
## 插件与集成
### CrewAI 集成
`zep-crewai` 在 v1.1.1 中专门修复了与 CrewAI 0.186.0+ 的兼容性问题：外部记忆搜索结果改用 `context` 键替代 `memory` 键，并相应更新了 `ZepUserStorage`、`ZepGraphStorage`、`ZepStorage` 三个存储类与所有测试断言（共 60 个测试全部通过）。资料来源：[integrations/crewai/python/README.md]()
常用模式包括「个人助理」「共享知识库」「多模态记忆」三类，分别对应 `ZepUserStorage` 配合 `create_search_tool`、本体化知识图谱（通过 `graph.set_ontology` 定义 `EntityModel`），以及 user / graph 双域搜索。资料来源：[integrations/crewai/python/README.md]()
### AutoGen 集成
`zep-autogen` 通过 `ZepUserMemory` 把 Zep 客户端包装成 AutoGen `AssistantAgent` 的 memory 组件；并提供 `create_search_graph_tool` 与 `create_add_graph_data_tool`，让模型可按需读写图谱。资料来源：[integrations/autogen/python/README.md]()
### LiveKit 与 ADK 集成
- **LiveKit**：面向实时语音 / 视频智能体，依赖 LiveKit Agents 框架；项目使用 `make test`、`make pre-commit`、`make ci` 等 Makefile 目标管理测试与严格类型检查（MyPy）。资料来源：[integrations/livekit/python/README.md]()
- **ADK（Agent Development Kit）**：提供两种工具风格——`ZepContextTool` 在每轮自动注入上下文；`ZepGraphSearchTool` 把搜索暴露为模型可调用的工具，支持「固定 `graph_id`」或「运行时从 ADK `userId` / `zep_user_id` 解析」两种目标解析方式。Python 端通过 `_SEARCH_PARAMS` 字典在构造时把 `graph.search()` 的关键字参数标记为「pinned」或「暴露给模型」。资料来源：[integrations/adk/typescript/src/graph-search-tool.ts]()、[integrations/adk/python/src/zep_adk/graph_search_tool.py]()
## 共用模式与排错提示
- **用户摘要指令（User Summary Instructions）**：在示例中以「预算、卧室、必须功能、学区」等固定问题形式声明，使 Zep 持续提炼用户摘要，跨对话保留关键事实。资料来源：[examples/python/user-summary-instructions-example/README.md]()
- **上下文化分块（Contextualized Retrieval）**：Python、TypeScript、Go 三套示例共用同一种「6000 字符分块 + OpenAI 上下文补全」策略，并包含对 OpenAI 速率限制的指数退避重试；分块后的 episode 控制在 Zep 的 10K 字符限制内，失败的分块会在汇总中报告而不中断后续处理。资料来源：[examples/python/chunking-example/README.md]()、[examples/typescript/chunking-example/README.md]()、[examples/go/chunking-example/README.md]()
- **LLM 模型变更影响**：v0.27.0 加入 `gpt-4o-mini` 等新模型与 token 上限；v0.27.1 将默认 OpenAI 模型切换到 `gpt-4o-mini`；v0.27.2 又为 `gpt-4o-mini` 调整了 `MaxLLMTokensMap`。升级相关 SDK 与测试时需同步检查这些默认值。资料来源：[release: v0.27.0]()、[release: v0.27.1]()、[release: v0.27.2]()
## 另请参见
- 用户记忆与 Context Block：[examples/python/user-summary-instructions-example/README.md]()
- 文档上下文化摄取（Python）：[examples/python/chunking-example/README.md]()
- MCP 工具与部署详情：[mcp/zep-mcp-server/README.md]()
- 评测流水线与运行快照：[zep-eval-harness/README.md]()
---
---
## Doramagic 踩坑日志
项目：getzep/zep
摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/getzep/zep | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/getzep/zep | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/getzep/zep | no_demo; severity=medium
## 4. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/getzep/zep | no_demo; severity=medium
## 5. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/getzep/zep | issue_or_pr_quality=unknown
## 6. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/getzep/zep | release_recency=unknown