人工智能AI AgentAgent 记忆RAG后端MCP 服务【免费下载链接】honchoMemory library for building stateful agents项目地址https://gitcode.com/gh_mirrors/hon/honcho点击查看免费下载导读本文面向使用 CrewAI 编排多智能体的开发者讲解如何通过honcho-crewai集成包将 Honcho 作为 CrewAI 统一Memory的自定义存储后端让 Agent 在会话之间持久记忆、自动召回上下文并通过HonchoGetContextTool、HonchoDialecticTool、HonchoSearchTool三个显式记忆工具获得更深度的检索与推理能力。读完本文你将掌握从环境配置、存储后端接入、三种记忆工具的调用方式到自动记忆与显式工具组合使用的完整实战方案。背景为什么 CrewAI 智能体需要 HonchoCrewAI 原生提供了统一MemoryAPI但默认存储往往局限于单次运行或进程内状态无法在多次对话、多个用户、多个会话之间延续记忆。HonchoMemory library for building stateful agents提供的是持久化的、基于 peer/session 语义的存储模型它以 peer用户、助手或任意参与者和 session会话为基本单元组织消息支持语义搜索、会话上下文汇总、peer 级长期表征representation等能力。honcho-crewai这个集成包源码位于 examples/crewai/python版本 0.3.0充当两者之间的桥梁它实现 CrewAI 当前的StorageBackend协议把 CrewAI 的记忆记录写入 Honcho 消息并把 Honcho 的上下文、语义搜索、dialectic 推理能力包装成 CrewAI Agent 可直接调用的工具。CrewAI 负责编排 Agent、任务与记忆召回流程Honcho 负责记忆的持久化与高级检索。环境要求与安装集成包的依赖声明位于 examples/crewai/python/pyproject.toml关键约束如下Python 版本范围3.10,3.14与 CrewAI 当前支持的解释器范围一致crewai1.14.3,2.0.0包内使用 CrewAI 1.10 之后引入的统一记忆类型MemoryRecord、ScopeInfohoncho-ai2.1.1,3.0.0Honcho Python SDK提供Honcho客户端openai1.0.0、python-dotenv1.0.0模型调用与本地环境变量加载。推荐使用 uv 安装与仓库示例一致uv add honcho-crewai crewai python-dotenv或使用 pippip install honcho-crewai crewai python-dotenv接下来配置模型供应商密钥与 Honcho 服务信息。CrewAI 的 Agent 需要大模型供应商密钥Honcho 客户端需要 API Key 与工作区 IDOPENAI_API_KEYyour_openai_key HONCHO_API_KEYyour_honcho_key HONCHO_WORKSPACE_IDcrewai-demo本地开发时可以初始化Honcho(environmentlocal)指向本地运行的服务。本文代码统一假设密钥已通过.env文件或环境变量注入示例脚本开头均调用load_dotenv()。快速开始用 HonchoMemoryStorage 接入 CrewAI 统一记忆HonchoMemoryStorage是集成包的核心类它实现了 CrewAI 当前的StorageBackend协议可以直接传给Memory(storage...)。以下为 README 中的最小可运行示例from crewai import Agent, Crew, Memory, Process, Task from honcho import Honcho from honcho_crewai import HonchoMemoryStorage honcho Honcho(workspace_idcrewai-demo) storage HonchoMemoryStorage( peer_iduser-123, session_idsession-123, honcho_clienthoncho, ) memory Memory(storagestorage) memory.remember( The user is learning Python and wants to build web applications., scope/users/user-123, categories[preferences], metadata{source: onboarding}, ) agent Agent( roleProgramming Mentor, goalHelp users learn programming by remembering their interests and progress, backstoryYou are a patient programming mentor., ) task Task( descriptionSuggest a Python web project that matches the users interests., expected_outputA specific project suggestion with a brief explanation, agentagent, ) crew Crew( agents[agent], tasks[task], processProcess.sequential, memorymemory, ) result crew.kickoff() print(result.raw)几个关键点需要理解HonchoMemoryStorage构造参数peer_id标识记忆归属的主体默认crewai-memorysession_id标识会话省略时自动生成 UUIDhoncho_client可传入已配置的Honcho实例省略时内部新建Honcho()。源码见 storage.py。懒初始化 peer/session 句柄storage.session与storage.peer是惰性属性首次访问时才调用honcho.session(...)/honcho.peer(...)获取句柄匹配最新 Honcho SDK 的 get-or-create 行为——这意味着未实际写入记忆前不会产生多余的网络调用见 storage.py。memory.remember的三个维度scope如/users/user-123用于组织记忆的命名空间categories为记忆打标签便于后续按类别过滤metadata携带任意自定义附加信息例如记录来源。Crew 执行时自动召回CrewAI 会在 kickoff 过程中根据任务上下文自动检索相关记忆并注入 Agent 提示词无需手工拼接历史。存储后端的工作原理记录如何落入 Honcho从 storage.py 的类文档可以看出设计思路CrewAI 在把记录交给存储后端之前会先对记录做嵌入embedding本适配器把这些嵌入向量保存在 Honcho 消息的 metadata 中并在会话的活跃记忆记录上进行本地向量检索。具体的数据映射如下每次save(records)每条 CrewAIMemoryRecord会被转换成一个 Honcho 消息self.peer.message(record.content, metadata..., created_atrecord.created_at)随后批量调用session.add_messages(messages)见 storage.py。记录的全部字段被序列化进消息 metadata键前缀统一为crewai_包括honcho_crewai_kind crewai_memory_record类型标记用于过滤出本适配器写入的消息crewai_record_id、crewai_scope、crewai_categories、crewai_metadata原始记忆 metadatacrewai_importance重要度缺省 0.5、crewai_created_at、crewai_last_accessedcrewai_embeddingCrewAI 生成的向量、crewai_source、crewai_privatehoncho_crewai_deleted软删除墓碑标记。 映射实现见_record_metadatastorage.py。读取时通过session.messages(filters{metadata: {_KIND_KEY: _MEMORY_KIND}}, size100, reverseTrue)拉取本会话内所有 Honcho 记忆消息再经_message_to_record反向还原为 CrewAIMemoryRecord并跳过带删除标记的消息见_record_messages与_active_record_messagesstorage.py。检索策略由于 Honcho 服务端并不感知 CrewAI 的记录结构search采用本地余弦相似度计算——将查询向量与每条活跃记录中保存的crewai_embedding做点积归一化打分_cosine_similaritystorage.py并按分数降序返回前limit条。检索支持三种过滤维度且过滤在向量打分之前执行提升命中质量scope_prefix按 scope 前缀匹配_scope_matches空/None//表示不限定否则要求 scope 等于前缀或以其为父路径categories记录分类与请求分类存在交集即命中_category_matchesmetadata_filter要求记录 metadata 中所有键值完全相等_metadata_matches。删除与更新采用墓碑策略delete不物理移除消息而是把honcho_crewai_deleted置为True后调用session.update_message(message, metadata...)storage.pyupdate则是先按record_ids墓碑化旧记录、再保存新记录storage.py。这种设计保证了 Honcho 侧消息历史不被破坏同时让 CrewAI 侧永远只看到最新有效状态。其他协议方法get_record按 ID 返回最新活跃记录、list_records新→旧分页列出默认 200 条、get_scope_info聚合 scope 内记录数、分类、时间范围与子 scope、list_scopes枚举直接子 scope、list_categories统计各分类计数、count计数、reset墓碑化整个 scope 或全部记录。同时提供对应的异步版本asave/asearch/adelete内部通过asyncio.to_thread把同步实现放到线程池执行storage.py方便在异步 CrewAI 流程中调用而不阻塞事件循环。兼容旧接口HonchoStorage 适配器对于使用旧版 CrewAIExternalMemoryCrewAI ≤ 1.9 的接口的老项目包内保留了HonchoStorage兼容适配器。它的构造参数为user_id必填、session_id、honcho_client、assistant_id默认assistant并提供三个方法storage.pysave(value, metadata)根据 metadata 中的role/agent字段把消息挂到用户 peer 或助手 peer 名下再写入会话search(query, limit10, score_threshold0.5, filtersNone)走 Honcho 服务端语义搜索session.search返回的每条结果包含content、memory、context三个同值字段CrewAI 旧接口要求以及metadata含peer_id、created_at与自定义 metadatafilters支持 Honcho 的过滤语法如{peer_id: user123}、{metadata: {type: important}}或比较运算{created_at: {gte: 2024-01-01}}reset()轮换到一个全新的随机 session_id后续写入即进入新会话。官方文档的明确建议是新项目一律使用HonchoMemoryStorage搭配crewai.Memory(storage...)HonchoStorage仅用于存量代码迁移过渡对应 docs/v3/guides/integrations/crewai.mdx。此外包内还定义了HonchoDependencyError继承ImportError当 CrewAI 统一记忆类型缺失时抛出并附带安装命令提示见 exceptions.py。显式记忆工具让 Agent 自己决定如何检索除了由 CrewAI 自动召回的统一记忆集成包还提供三个继承自crewai.tools.BaseTool的工具源码见 tools.py让 Agent 在执行任务时主动、精准地查询记忆。三者的工具名、定位与输入参数如下表工具类注册名作用输入参数HonchoGetContextToolget_session_context按 token 预算拉取会话上下文含摘要、peer 表征、peer card、消息列表tokens0、peer_target、summary默认 True、peer_perspectiveHonchoDialecticToolquery_peer_knowledge向 Honcho 的 dialectic推理能力提问获取对某个 peer 的长期表征query必填、target、session_idHonchoSearchToolsearch_session_messages对会话消息做语义相似度搜索query必填、limit1–100默认 10、filtersHonchoGetContextTool带 token 预算的上下文注入该工具调用session.context(summary..., tokens..., peer_target..., peer_perspective...)获取上下文对象然后格式化为 Agent 友好的纯文本见 tools.py若有context.summary输出 Session Summary 段若有context.peer_representation输出 Peer Representation 段若有context.peer_card逐行输出 Peer Card 消息列表按peer_id: content格式输出为 Messages (N) 。tokens参数直接限制返回上下文的最大 token 数适合在 LLM 上下文窗口紧张时按预算截取最相关的历史。HonchoDialecticTool向 Honcho 询问对用户的认知该工具把问题交给peer.chat(queryquery, targettarget, sessionsession_id)也就是 Honcho 的 dialectic 推理链路——Honcho 会基于该 peer 的长期表征而非单纯的关键词匹配回答问题适合“用户喜欢什么”“用户的偏好是什么”这类需要推理归纳的提问。可选target用于查询一个 peer 对另一个 peer 的“局部表征”。返回空结果时给出兜底文案No relevant information found.tools.py。HonchoSearchTool会话消息语义搜索该工具调用session.search(queryquery, limitlimit, filtersfilters)进行语义检索结果按序号. [peer_id] 内容的格式返回并附带Created: 时间若消息带时间戳。filters复用 Honcho 的过滤语法例如{metadata: {priority: high}}只检索特定元数据的消息tools.py。工具接入示例以下代码来自 tools_example.py完整可运行先向会话写入 5 条关于日本旅行的历史消息再创建三个工具并挂到旅行规划 Agent 上最后让 Crew 执行“制定 3 天东京行程”的任务Agent 会自主调用工具检索饮食偏好、预算等信息from crewai import Agent, Crew, Process, Task from dotenv import load_dotenv from honcho import Honcho from honcho_crewai import ( HonchoDialecticTool, HonchoGetContextTool, HonchoSearchTool, ) load_dotenv() honcho Honcho() user_id demo-user-45 session_id tools-demo-session user honcho.peer(user_id) session honcho.session(session_id) for msg in [ Im planning a trip to Japan in March, I love trying authentic local cuisine, especially ramen and sushi, My budget is around $3000 for a 10-day trip, Im interested in visiting both Tokyo and Kyoto, I prefer staying in traditional ryokans over hotels, ]: session.add_messages([user.message(msg)]) context_tool HonchoGetContextTool( honchohoncho, session_idsession_id, peer_iduser_id ) dialectic_tool HonchoDialecticTool( honchohoncho, session_idsession_id, peer_iduser_id ) search_tool HonchoSearchTool(honchohoncho, session_idsession_id) travel_agent Agent( roleTravel Planning Specialist, goalCreate personalized travel recommendations using memory tools, backstory( You are an expert travel planner with access to conversation memory tools. Use the tools to understand the users preferences before making recommendations. ), tools[context_tool, dialectic_tool, search_tool], verboseTrue, allow_delegationFalse, ) task Task( description( Create a personalized 3-day Tokyo itinerary. Use the memory tools to understand food preferences, travel style, budget, and recent context, then create a detailed plan. ), expected_output( A 3-day Tokyo itinerary with daily activities matching user interests, restaurant recommendations, accommodation suggestions, and budget considerations ), agenttravel_agent, ) crew Crew( agents[travel_agent], tasks[task], processProcess.sequential, verboseTrue, ) crew.kickoff()注意该示例的 Crew 未挂memory——因为记忆历史是直接用 Honcho SDK 写入的Agent 完全通过工具按需检索。每个工具类的输入参数都通过 PydanticBaseModel声明GetContextInput、DialecticInput、SearchInputCrewAI 会据此自动生成工具调用 schema因此 LLM 能正确理解并填充参数。两种记忆模式的选型与组合三种使用方式各有适用场景官方集成文档 docs/v3/guides/integrations/crewai.mdx 给出了明确指引方案适用场景记忆获取方式仅HonchoMemoryStorage统一记忆希望 CrewAI 自动管理召回Agent 无需感知记忆细节Crew 执行时自动注入相关历史仅三个 Honcho 工具希望 Agent 自主决策何时、以何种方式查询记忆Agent 按需调用工具两者组合混合记忆既要有基线上下文又要支持针对性深挖自动基线 显式工具双通道混合方案的完整实现见 hybrid_memory_example.py它先把 7 条用户与助手的对话通过memory.remember(...)写入自动记忆通道同时创建HonchoSearchTool与HonchoDialecticTool挂到 Travel Advisor Agent 上任务描述中明确要求“用 search_tool 找预算与饮食偏好、用 query_peer_knowledge 了解旅行风格”Crew 在获得自动注入上下文的基础上还能做定向检索。另一个值得参考的实战形态是 interactive_chat.py 展示的多轮对话循环每一轮把用户输入memory.remember(...)存入 Honchorole 标记为user执行crew.kickoff()让 CrewAI 自动召回历史生成回答再立即把助手回答回写记忆role 标记为assistant并在循环中复用同一个HonchoMemoryStorage实例相同user_id/session_id从而保证跨轮次的上下文连续性。这正是“持久记忆”在真实聊天场景下的直接体现。完整可运行示例与测试佐证仓库在 examples/crewai/python/examples 下提供 4 个可直接运行的脚本simple_example.py最小演示写入三条学习 Python 的对话历史后让编程导师 Agent 推荐项目interactive_chat.py交互式多轮聊天展示记忆的写入与自动召回闭环tools_example.py三个显式记忆工具的接入与调用hybrid_memory_example.py统一记忆 显式工具的混合方案。运行方式在 examples/crewai/python 目录下uv run python examples/simple_example.py uv run python examples/interactive_chat.py uv run python examples/tools_example.py uv run python examples/hybrid_memory_example.py仓库的测试目录同样覆盖了本集成的主要行为可作为理解契约与自行验证的入口test_basic.py验证包可导入、__version__存在、__all__导出了HonchoStorage、HonchoMemoryStorage与三个工具类test_storage.py使用FakePeer/FakeSession桩件验证save、search、delete、update、reset、count、get_scope_info等存储后端协议的完整行为包括 scope 过滤、分类过滤、元数据过滤、软删除墓碑与向量相似度排序test_tools.py验证三个工具在给定输入下的输出格式与错误兜底分支。总结honcho-crewai让 CrewAI 智能体具备了真正的跨会话持久记忆HonchoMemoryStorage把 CrewAI 的统一记忆协议桥接到 Honcho 的 peer/session 消息模型并利用消息 metadata 保存嵌入向量实现本地向量检索同时以墓碑方式支持删除与更新HonchoStorage为旧版ExternalMemory用户提供迁移过渡三个记忆工具则把 Honcho 的上下文注入、dialectic 推理与语义搜索能力开放给 Agent 自主调用。实践中建议新项目直接选用HonchoMemoryStorage并在需要深度个性化时叠加显式工具形成“自动基线 定向检索”的混合记忆架构。赞分享人工智能AI AgentAgent 记忆RAG后端MCP 服务【免费下载链接】honchoMemory library for building stateful agents项目地址https://gitcode.com/gh_mirrors/hon/honcho点击查看免费下载相关推荐使用 Hindsight 为 LangGraph 智能体构建持久化记忆工具、节点与记忆注入完整实战指南使用 Hindsight 为 LangGraph 智能体构建持久化记忆工具、节点与记忆注入完整实战指南 本文以 hindsight langgraph 集成包人工智能AI AgentAgent 记忆MCP 服务Honcho Memory Skill为 Zo Computer 构建持久记忆的实战指南Honcho Memory Skill为 Zo Computer 构建持久记忆的实战指南 本篇技术指南围绕开源仓库 honcho 中的 examples/zo人工智能AI AgentAgent 记忆RAG后端MCP 服务Honcho实战为CrewAI和LangGraph Agent系统注入持久化记忆能力Honcho实战为CrewAI和LangGraph Agent系统注入持久化记忆能力 Honcho 是一款为 Agent 提供 持久化记忆 的基础设施mem人工智能AI AgentAgent 记忆RAG后端MCP 服务上一篇.NET MAUI 完整学习指南从零开始掌握跨平台开发下一篇终极产品经理成长指南Awesome Product Management 完全入门手册创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考