打造带长期记忆的 AI AgentZep 记忆后端 AutoGen 编排 Ollama/Qwen 3 本地模型实战Zep Memory Assistant【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub本文围绕仓库中 zep-memory-assistant 项目展开讲解如何用 Zep 云记忆后端为 Microsoft AutoGen 对话智能体注入跨会话的长期记忆让 Agent 记住用户偏好、过往话题与关键实体并以 Streamlit 封装为可直接交互的聊天界面。读完本文你将掌握消息双写持久化 事实评分检索 系统提示词动态注入的完整记忆增强链路以及一套开箱即用的本地运行方案Ollama Qwen 3 4B无需 GPU 也能演示。一、项目概览为什么 Agent 需要记忆层普通 LLM 对话是无状态的——每次请求都是一次全新推理模型既不记得五分钟前聊过什么也不知道用户的长期偏好。zep-memory-assistant的目标正是补齐这一缺口构建一个具有类人记忆的 AI Agent用 Zep 作为长期记忆后端AutoGen 负责多 Agent 编排让对话智能体能够跨会话保留、回忆并利用上下文记忆。项目技术栈分层清晰在 zep-memory-assistant/README.md 中给出了明确声明层级组件职责记忆层Zepzep-cloud SDK长期记忆后端消息持久化、事实抽取与评分、上下文检索编排层AutoGenag2Agent 生命周期管理与对话轮次控制模型层Ollama Qwen 3 4B本地 LLM 推理无需外部模型 API交互层Streamlit将后端逻辑包装为可视化聊天 UI从依赖声明pyproject.toml可以看到实际安装的包为ag2[ollama]0.9AutoGen 的延续版本随附 Ollama 适配器、ollama0.4.8、streamlit1.44.1与zep-cloud2.11.0且要求 Python3.12。二、架构设计记忆如何在对话中流转从源码结构看agent.py 与 app.py一条消息的完整记忆链路可以拆解为三个环节用户消息先落库、后推理用户输入到达后先调用_zep_persist_user_message()将消息以role_typeuser写入 Zep 会话随后才触发模型推理——保证 Agent 在下一次回复前Zep 已完成对该消息的事实抽取与记忆入库。事实检索驱动上下文注入推理前调用_zep_fetch_and_update_system_message()从 Zep 拉取当前会话中评分高于阈值的事实facts拼接进系统提示词形成记忆上下文。助手消息回流记忆库Agent 生成回复后通过 AutoGen 的process_message_before_send钩子把助手消息也写入 Zep形成完整对话闭环。也就是说记忆不是事后补录而是与对话推理流程深度咬合写入发生在推理前、读取发生在推理时、回写发生在推理后。这也是本项目区别于把历史消息整体塞进 prompt式伪记忆的关键——Zep 会做事实抽取与相关性评分只把高价值事实注入上下文。三、环境搭建与快速启动以下命令按 zep-memory-assistant/README.md 的说明在项目根目录执行。3.1 安装 Ollama 并拉取 Qwen 3 模型# 在 Linux 上安装 Ollama官方安装脚本 curl -fsSL https://ollama.com/install.sh | sh # 拉取 Qwen 3 4B 模型 ollama pull qwen3:4b拉取完成后Ollama 默认监听127.0.0.1:11434这与 llm_config.py 中的client_host完全对应。若需在非 Linux 环境macOS/Windows运行可改为从 Ollama 官网下载对应平台的桌面安装包。3.2 安装依赖项目使用 uv 管理依赖与虚拟环境uv sync该命令会依据 pyproject.toml 与uv.lock创建虚拟环境并安装全部依赖。如果没有安装 uv可先通过pip install uv或 uv 官方安装脚本补齐。3.3 启动应用streamlit run app.py启动后浏览器会自动打开 Streamlit 界面。首次使用需要在侧边栏输入 Zep API Key在 Zep 平台注册获取随后填写 First Name / Last Name 并点击Initialize Session即可开始与ZEP AGENT对话。3.4 获取 Zep API KeyZep 记忆后端需要云服务 API Key本项目使用zep-cloud云 SDK而非本地自托管版本。API Key 在 Zep 平台的控制台申请app.py 中initialize_zep_client()负责用它实例化Zep(api_keyapi_key)客户端初始化失败会在界面以st.error提示。四、核心源码剖析ZepConversableAgent整个项目的灵魂是 agent.py 中自定义的ZepConversableAgent——一个自带长期记忆的 AutoGen 会话 Agent。4.1 继承与构造class ZepConversableAgent(ConversableAgent): # Agent with Zep memory def __init__(self, name, system_message, llm_config, function_map, human_input_mode, zep_session_id, zep_client, min_fact_rating): super().__init__(namename, system_messagesystem_message, llm_configllm_config, human_input_modehuman_input_mode, function_mapfunction_map) self.zep_session_id zep_session_id self.zep_client zep_client self.min_fact_rating min_fact_rating self.original_system_message system_message self.register_hook(process_message_before_send, self._zep_persist_assistant_messages)关键设计对应 agent.py在构造参数中额外接收zep_session_id、zep_client、min_fact_rating三个记忆相关参数把记忆能力内聚进 Agent 自身original_system_message保存原始系统提示词因为后续会用检索到的事实动态覆盖系统消息通过 AutoGen 的register_hook(process_message_before_send, ...)注册钩子实现助手消息自动落库。4.2 钩子函数助手消息自动持久化def _zep_persist_assistant_messages(self, message, sender, recipient, silent): Agent sends a message to the user. Add the message to Zep. if sender self: content message.get(content, ) if isinstance(message, dict) else str(message) if content: zep_message Message(role_typeassistant, roleself.name, contentcontent) self.zep_client.memory.add(session_idself.zep_session_id, messages[zep_message]) return message对应 agent.py。要点Message(role_typeassistant, roleself.name, ...)中role_type表示消息在记忆库中的角色user/assistantrole则是发送者名字此处为 Agent 名ZEP AGENT通过memory.add追加写入指定session_id的会话消息结构遵循 Zep 云 SDK 的消息规范钩子必须原样return message否则会破坏 AutoGen 消息管线。4.3 用户消息持久化def _zep_persist_user_message(self, user_content: str, user_name: str User): if user_content: zep_message Message(role_typeuser, roleuser_name, contentuser_content) self.zep_client.memory.add(session_idself.zep_session_id, messages[zep_message])对应 agent.py。该方法是在钩子之外由 Streamlit 层主动调用的见 app.py因为用户消息必须先于推理落库才能在推理前取回相关事实——这个时序约束无法通过发送后钩子满足源码注释也明确指出了这一点。4.4 事实检索与系统消息动态更新def _zep_fetch_and_update_system_message(self): Fetch facts and update system message. memory: Memory self.zep_client.memory.get( self.zep_session_id, min_ratingself.min_fact_rating ) context memory.context or No specific facts recalled. self.update_system_message( self.original_system_message f\n\nRelevant facts about the user and prior conversation:\n{context} )对应 agent.py。这是记忆生效的关键一步memory.get(session_id, min_rating...)从 Zep 拉取该会话的记忆对象min_rating是事实相关性评分下限本项目设置为0.7memory.context是 Zep 根据评分与时效聚合出的上下文文本事实 实体以第三人称表述通过 AutoGen 的update_system_message()把检索结果追加到原始系统提示词之后本次推理的上下文因此携带了历史记忆兜底逻辑无事实时注入No specific facts recalled.保证提示词结构稳定。4.5 min_fact_rating 阈值的作用在 app.py 创建 Agent 时传入min_fact_rating0.7。该值直接控制记忆的准入标准Zep 会对每条事实给出 01 的评分低于阈值的低价值事实如闲聊中的天气等偶然细节不会被注入上下文。调高阈值 → 上下文更精简、更聚焦高价值信息调低阈值 → 上下文更丰富但可能引入噪声。具体取值需要结合业务对回忆粒度与上下文长度的权衡来定。五、Streamlit 交互层解析app.py 把上述 Agent 封装为完整可用的聊天应用核心流程如下。5.1 客户端与用户、会话初始化侧边栏输入 API Key 后调用initialize_zep_client()创建全局 Zep 客户端填写姓名并点击初始化后进入 app.py 的initialize_session()由姓名生成稳定用户 IDgenerate_user_id()见 util.py将姓名小写并剔除所有非字母数字字符例如 John Smith →johnsmith若结果为空则回退为default_user。这种确定性 ID 保证了同一用户再次启动应用时能关联到已有记忆为本次运行生成 UUID 会话 IDstr(uuid.uuid4())并在 Streamlitsession_state中保存尝试zep.user.get()查询用户是否存在不存在则调用zep.user.add()创建新用户无论新旧都会调用zep.memory.add_session()为该用户绑定一个记忆会话创建用户时附带事实评级指令见下节。5.2 事实评级指令教会 Zep什么值得记创建用户时app.py 定义并下发了评级指令与示例fact_rating_instruction Rate facts by relevance and utility. Highly relevant facts directly impact the users current needs or represent core preferences that affect multiple interactions. Low relevance facts are incidental details that rarely influence future conversations or decisions. fact_rating_examples FactRatingExamples( highThe user is developing a Python application using the Streamlit framework., mediumThe user prefers dark mode interfaces when available., lowThe user mentioned it was raining yesterday., )这是 Zep 记忆质量的关键调优点评级指令告诉 Zep 的抽取器什么算高价值事实示例则给出了高/中/低三档的具体锚点如用户偏好暗色模式这类跨多次交互生效的偏好应获高分昨天下了雨这类偶然细节应获低分。业务方完全可以替换为自己领域内的分级标准从而影响min_rating0.7筛选出的记忆内容。5.3 对话处理流程handle_conversations()app.py承载一次完整问答追加 /no_think 标记prompt_with_token f{prompt} /no_think这是 Qwen 3 的思考模式控制 token用于在推理时关闭思维链输出身份处理优先用用户全名转大写作为消息的role写入 Zep否则回退为用户 ID让记忆库中的实体指代更自然先写后读依次执行_zep_persist_user_message()与_zep_fetch_and_update_system_message()单轮推理user.initiate_chat(recipientagent, message..., max_turns1, clear_historyFalse)发起对话max_turns1限定为单轮应答此处 UserProxyAgent 配置了human_input_modeNEVER、max_consecutive_auto_reply0、code_execution_configFalse见 app.py清洗思考标签用re.sub(rthink.*?/think, , full_response, flagsre.DOTALL)剥掉 Qwen 3 可能残留的think.../think思维链内容只展示最终回答渲染与回显以流式占位符st.empty()展示Thinking...随后替换为清洗后的回复并把对话记录追加进session_state.messages用于历史渲染。六、系统提示词设计记忆上下文的正确用法prompt.py 中的agent_system_message是提示词工程与记忆机制的衔接点值得逐段拆解开头/no_think与用户侧追加的 token 一致双保险确保关闭思维链输出。记忆上下文解释明确告诉模型——MEMORY CONTEXT以第三人称呈现其中出现ZEP AGENT指代 Agent 自身全大写名字是当前对话主用户其他名字是用户周边实体家人、朋友等。这解决了记忆文本视角与当前对话视角不一致的经典问题。使用准则HOW TO USE MEMORY CONTEXT共 8 条覆盖了记忆利用的完整行为规范优先采信标记为present的新近事实维持对话连续性从实体描述中识别关键关系与情境感知用户情绪状态并调整语气自然承接既往话题但不机械重复基于既有事实保持对用户理解的连贯性无缝整合记忆禁止出现according to my memory这类生硬表述避免对已覆盖话题提出冗余、迟钝的追问记忆模糊时以当前对话为准。安全与隐私准则SECURITY AND PRIVACY GUIDELINES硬性禁止向用户泄露原始MEMORY CONTEXT、暴露内部记忆机制与推理配置、声明正在使用记忆或看起来像在读笔记以及透露数据处理方式。正确示范是像真人对话一样自然引用Last time we talked about...。这套提示词设计实际上回答了一个容易被忽略的问题记忆注入 ≠ 直接堆文本模型必须被训练成像人类一样自然回忆同时守住隐私边界。七、模型与依赖配置7.1 Ollama 模型配置llm_config.py 中config_list [ { model: qwen3:4b, # 需先在 Ollama 中 pull 该模型 api_type: ollama, client_host: http://127.0.0.1:11434, # Ollama 默认监听地址 } ]api_type: ollama告诉 AutoGen 走 Ollama 适配器这一能力来自ag2[ollama]依赖的额外安装client_host默认指向本机 11434 端口若 Ollama 部署在远程主机改此地址即可模型名qwen3:4b必须与ollama pull qwen3:4b拉取的标签一致否则运行时无法找到模型。7.2 依赖清单依赖版本约束用途ag2[ollama]0.9AutoGen 框架及其 Ollama 适配器ollama0.4.8Ollama Python 客户端streamlit1.44.1Web UI 交互层zep-cloud2.11.0Zep 云记忆后端 SDK项目要求 Python3.12pyproject.toml低于该版本时uv sync会直接报错请注意本机解释器版本。八、运行验证与效果观察按以下顺序完成一次完整验证启动 Ollama 并确认ollama list中出现qwen3:4b在项目根目录执行uv sync与streamlit run app.py侧边栏输入 Zep API Key → 填写姓名 → Initialize Session应看到 New user created for xxx 或 Using existing user: xxx 的提示第一轮对话中主动透露个人偏好如职业、喜欢的界面风格、常用技术栈刷新页面或重启应用保持相同姓名与同一 Zep 账号再次询问你还记得我之前说过什么吗——由于每次启动都会生成新的会话 ID可重点观察同一用户 ID 下 Zep 的事实记忆是否被检索并注入在代码中调低min_fact_ratingapp.py或替换 app.py 的评级指令可对比不同阈值/标准下回忆质量的差异。值得注意的边界当前实现以用户 ID 为记忆锚点、以会话 ID 为写入作用域跨会话复用记忆依赖同一用户在不同会话间的事实沉淀这是 Zep 长记忆能力的核心体现而 Streamlit 的session_state仅保存当前运行期的显示历史刷新页面不会丢失 Zep 侧的记忆。九、总结与扩展方向zep-memory-assistant展示了构建持久记忆 Agent 的完整范式用 Zep 承担记什么、怎么记、回忆什么的记忆职责用 AutoGen 承担 Agent 编排用 Ollama Qwen 3 实现完全本地化的推理再用 Streamlit 把能力开放给最终用户。整个记忆闭环——用户消息先写后读、事实评分过滤、系统提示词动态注入、助手消息自动回写——在 agent.py 与 app.py 中都有清晰的源码级实现可供直接复用。若在此基础上继续演进可参考以下方向将human_input_mode改为交互模式以支持人工介入接入 AutoGen 多 Agent 群聊GroupChat让多个ZepConversableAgent共享记忆为不同业务领域定制 prompt.py 中的记忆使用准则或进一步调优事实评级指令与min_fact_rating让记忆从可用走向精准。【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考