Zep Cloud 长期记忆功能集成实战指南

通过这些接口，Zep 可以为每个用户维护独立的记忆空间，避免不同用户之间的干扰。

存储与检索记忆

当用户和 AI 进行对话时，我们可以把消息存储到 Zep 中。例如将用户和 AI 的对话存入记忆：

def add_memory(user_id, bot_id, thread_id, user_message, bot_message):
    """将用户和 AI 的对话存入记忆"""
    messages = [
        Message(name=user_id, role="user", content=user_message),
        Message(name=bot_id, role="assistant", content=bot_message),
    ]
    client.thread.add_messages(thread_id, messages=messages)
    print(f"💾 已存入记忆：{user_message} -> {bot_message}")

Zep 的强大之处在于，它不只是单纯的对话存档，而是提供了结构化的长期记忆检索能力。我们可以通过以下方式获取某个对话线程的上下文摘要：

def get_user_context(thread_id, mode="summary"):
    """获取用户上下文（支持 summary/basic 两种模式）"""
    memory = client.thread.get_user_context(thread_id=thread_id, mode=mode)
    print(f"📌 用户上下文（{mode}）:\n", memory.context)
    return memory.context

Zep 会自动对历史对话进行摘要，提取用户的偏好和事实，从而在后续对话中帮助 AI 更好地理解用户。

同时，Zep 还支持基于 知识图谱（graph） 的检索，可以通过 search_in_graph 或 get_relevant_fact 找到和用户相关的事实和关系。这使得 AI 不仅能记住对话，还能推理出用户的兴趣、习惯和事实网络。

完整示例

下面是一个整合了上述功能的完整脚本，展示了从初始化到记忆检索的全流程：

import os
import uuid
from dotenv import load_dotenv
from zep_cloud.client import Zep
from zep_cloud import Message

# ======================
# 1. 初始化 Zep 客户端
# ======================
load_dotenv(override=True)
ZEP_API_KEY = os.getenv("ZEP_API_KEY")
client = Zep(api_key=ZEP_API_KEY)

# ======================
# 2. 用户管理
# ======================
def add_user(user_id, email, first_name, last_name):
    user = client.user.add(
        user_id=user_id, email=email, first_name=first_name, last_name=last_name,
    )
    print(f"✅ 用户 {user_id} 已创建:", user)
    return user

def get_user(user_id):
    user = client.user.get(user_id)
    print("ℹ️ 用户信息:", user)
    return user

# ======================
# 3. 会话管理（Thread）
# ======================
def create_thread(user_id):
    thread_id = uuid.uuid4().hex
    client.thread.create(thread_id=thread_id, user_id=user_id)
    print("🆕 新建线程:", thread_id)
    return thread_id

# ======================
# 4. 添加记忆
# ======================
def add_memory(user_id, bot_id, thread_id, user_message, bot_message):
    messages = [
        Message(name=user_id, role="user", content=user_message),
        Message(name=bot_id, role="assistant", content=bot_message),
    ]
    client.thread.add_messages(thread_id, messages=messages)
    print(f"💾 已存入记忆：{user_message} -> {bot_message}")

# ======================
# 5. 获取长期记忆摘要
# ======================
def get_user_context(thread_id, mode="summary"):
    memory = client.thread.get_user_context(thread_id=thread_id, mode=mode)
    print(f"📌 用户上下文（{mode}）:\n", memory.context)
    return memory.context

# ======================
# 6. 演示流程
# ======================
if __name__ == "__main__":
    # 定义两个用户：human user 和 bot user
    user_id = "harry_user"
    bot_id = "ai_bot"

    # 创建用户
    add_user(user_id, "[email protected]", "Harry", "Liu")
    add_user(bot_id, "[email protected]", "AI", "Assistant")
    get_user(user_id)
    get_user(bot_id)

    # 创建对话线程（以 human user 为主）
    thread_id = create_thread(user_id)

    # 模拟一次对话
    user_msg = "Hi, my name is Harry. I love watching movies and learning Python."
    bot_msg = "Nice to meet you Harry! 🎬🐍 Movies and Python are both great choices!"
    add_memory(user_id, bot_id, thread_id, user_msg, bot_msg)

    # 再来一次对话
    user_msg2 = "I want to learn Python basics, please teach me."
    bot_msg2 = "Sure! Let's start with printing text:\n```python\nprint('Hello, Harry!')\n```"
    add_memory(user_id, bot_id, thread_id, user_msg2, bot_msg2)

    # 获取用户记忆摘要
    get_user_context(thread_id, "summary")
    get_user_context(thread_id, "basic")

运行上述代码后，你会看到类似以下的输出结果，其中包含了用户画像的自动摘要：

✅ 用户 harry_user 已创建: ...
🆕 新建线程：b4cfdfa942f34c768e2b4348c31d32d9
💾 已存入记忆：Hi, my name is Harry... -> Nice to meet you Harry!
📌 用户上下文（summary）:
• Harry Liu introduced himself as someone who loves watching movies and learning Python
• Harry Liu requested to learn Python basics

知识图谱搜索（Graph Search）

在前面的例子里，我们通过 user_context 可以快速拿到用户的摘要信息。但在更复杂的 RAG 问答 场景下，仅靠摘要可能不够精确。这时候，Zep 提供的 知识图谱搜索（Graph Search）就派上用场了。

为什么需要知识图谱？

• 精确检索用户事实：比如用户喜欢的编程语言、职业、同事关系等。
• 关系推理：例如'Harry 和谁是同事？'、'他在哪家公司工作？'。
• 复杂问题处理：多个实体、多关系组合的问题。

图搜索代码示例

def search_in_graph(user_id, query_text, center_node_uuid=None):
    """在 Zep 知识图谱中搜索与 query_text 相关的节点或事实"""
    if center_node_uuid:
        results = client.graph.search(
            user_id=user_id, query=query_text,
            reranker="node_distance",
            center_node_uuid=center_node_uuid
        )
    else:
        results = client.graph.search(user_id=user_id, query=query_text)

    relevant_nodes = results.nodes
    relevant_edges = results.edges
    print("=== 节点 ===")
    if relevant_nodes:
        for node in relevant_nodes:
            print(node)
    print("=== 相关事实 ===")
    if relevant_edges:
        for edge in relevant_edges:
            print(edge.fact)

if __name__ == "__main__":
    search_in_graph(user_id, "what does harry like?")

执行结果会列出相关的节点和事实，例如：

=== 相关事实 ===
Harry Liu loves watching movies
Harry Liu loves learning Python
Harry wants to learn Python basics.

应对随机查询的策略

在实际 RAG 场景里，用户的问题往往是随机的，我们并不能提前知道要以哪个节点作为中心。这里有两种策略：

1. 全局搜索（不指定中心节点）

   search_in_graph(user_id, query_text)
   

   Zep 会在整个知识图谱里检索与问题相关的节点和事实。适合范围比较宽泛、问题不确定的场景。

2. 自动推断中心节点 我们可以先对用户问题做 关键词/实体抽取，再去匹配知识图谱节点。如果找到对应节点，就用它作为搜索中心；找不到，则 fallback 到全局搜索。

   def auto_graph_search(user_id, query_text):
       client = Zep(api_key=ZEP_API_KEY)
       nodes = client.graph.node.get_by_user_id(user_id=user_id)
       center_node_uuid = None
       for node in nodes:
           if node.label.lower() in query_text.lower():
               center_node_uuid = node.uuid
               break
       return search_in_graph(user_id, query_text, center_node_uuid)
   

此外，搜索图的范围有三种：edges, nodes, episodes。可以根据需求调整 scope 参数来限定搜索粒度。

知识图谱结构解析

Zep 的知识图谱是围绕 用户个性化事实 自动构建的。当用户和 bot 的对话中出现了新的事实（比如职业、爱好、关系等），Zep 会把这些事实提取出来，构造成 节点（Node） 和 边（Edge），存放到图数据库里。

节点（Node）

节点通常表示 实体，比如人物、组织、事物或概念。每个节点包含信息：

• uuid：节点唯一 ID
• labels：标签名称，比如 "User", "Entity"
• summary：关于这个实体的总结描述（可能是从多条对话中生成的）

边（Edge）

边表示 事实或关系，连接两个节点。边不仅仅是'连接'，它们包含了 关系语义，是知识图谱的核心价值。例如：

• "Harry 在百度工作"
• "Harry 的同事是小明"
• "Harry 喜欢 Python"

图的构建方式

Zep 会自动从对话中抽取事实。例如用户说：

我在百度工作，我的同事是小明。我喜欢 Python。

知识图谱中会自动生成：

• 节点：Harry, 百度，小明，Python
• 边：(Harry) —— [职业] ——> (百度), (Harry) —— [同事] ——> (小明), (Harry) —— [爱好] ——> (Python)

user_context 与 knowledge graph 的区别

• user_context：是 Zep 给出的一个 文本总结/提取块，方便直接放进 prompt，让 LLM 拿到用户背景。比如 Harry 是 25 岁的程序员，在百度工作，喜欢 Python 和篮球。
• knowledge graph：是一个结构化的 实体-关系图，方便做事实检索和推理。比如能回答：Harry 的同事是谁？Harry 的爱好和职业之间有没有联系？

小结：

• 节点（Node） 存放用户相关的实体。
• 边（Edge） 存放事实和关系，带有自然语言描述。
• 知识图谱 适合做结构化检索和推理（特别是关系类问题）。
• user_context 更适合当作 RAG 的输入上下文，直接提供背景信息给 LLM。

总结

从上面的例子可以看到，Zep 提供了以下几个层次的记忆能力：

1. 对话存储：保留用户与 AI 的消息。
2. 上下文总结：自动生成用户画像和对话摘要。
3. 图谱搜索：以结构化的方式组织知识，方便 AI 检索和推理。

这让 AI 不仅能「记住你说过的话」，还可以「理解你是谁」、「你关心什么」、「你曾经提过的事实」——这就是长期记忆的价值。

传统的聊天机器人往往是「短期记忆」：只记住本轮对话内容。而 Zep 则进一步赋予 AI 「长期记忆」：它能管理用户信息、保存对话线程、抽取知识图谱，并支持高效的检索和推理。

对于想要打造真正个性化 AI 助手的开发者来说，Zep 提供了一套非常实用的工具。未来我们还可以基于这些记忆能力，构建更加智能、持久且个性化的 AI 应用。

相关资源

• Zep GitHub
• Graphiti GitHub
• Zep Official Docs