Hindsight × SmolAgents 持久记忆集成实战Retain、Recall、Reflect 三大记忆工具详解【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightSmolAgents 擅长构建轻量、可组合的智能体但默认情况下每个任务都从零开始无法跨会话积累知识。Hindsight 通过提供hindsight_retain、hindsight_recall、hindsight_reflect三个原生 SmolAgents 工具为智能体注入长期记忆能力使其从单次执行进化为持续学习的系统。本文以官方博客 2026-04-29-smolagents-memory-tools.md 为主体结合仓库中 hindsight-smolagents 集成 的源码与测试完整讲解安装配置、工具原理、实战场景与最佳实践。为什么 SmolAgents 需要长期记忆SmolAgents 擅长构建最小化、可组合的智能体用于推理代码、数据和系统问题。但传统智能体彼此孤立运行每个任务从零开始对之前的运行一无所知智能体无法从过去的错误或成功中学习一个任务的洞察无法指导下一个任务用户不得不反复重复解释和上下文Hindsight 通过三个记忆工具解决这一问题Retain存储把事实、决策与观察写入长期记忆Recall检索按查询召回最相关的记忆上下文Reflect反思对已存事实做高层综合提炼学习成果三者协同工作让智能体记住 → 想起 → 反思 → 改进实现跨会话、跨任务的知识累积。Hindsight 如何与 SmolAgents 集成Hindsight 的 SmolAgents 集成本质上是三个继承自 SmolAgents 原生Tool基类的工具子类见 tools.py因此智能体可以像调用内置工具一样调用它们。hindsight_retain—— 存储事实与观察由智能体在代码中显式调用或按系统提示词约定自动调用从非结构化的推理文本中保存结构化事实支持按主题、日期或上下文打标签tagshindsight_recall—— 检索相关上下文用问题式查询召回记忆如 What did I learn about database indexing?返回按相关性排序的事实列表带有编号可直接融入推理循环支持budget、max_tokens、标签过滤等参数控制召回质量hindsight_reflect—— 综合学习成果与模式分析已存事实提炼高层洞察生成智能体学到了什么的总结帮助识别知识缺口或重复犯过的错误安装与基础配置先安装集成包pip install hindsight-smolagents依赖要求见 pyproject.tomlPython 3.10、smolagents、hindsight-client 0.4.0以及一个可访问的 Hindsight API 服务。然后在你的智能体中配置并注册工具from hindsight_smolagents import configure, create_hindsight_tools from smolagents import CodeAgent, DuckDuckGoSearchTool # 配置 Hindsight全局一次性配置 configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyyour-hindsight-key ) # 创建三个记忆工具 memory_tools create_hindsight_tools(bank_idmy-agent-memory) # 创建带记忆的智能体 agent CodeAgent( tools[DuckDuckGoSearchTool()] memory_tools, model_idopenai/gpt-4 ) # 现在你的智能体拥有记忆了 result agent.run(Search for Python async patterns and remember what you learn)create_hindsight_tools()返回三个Tool实例hindsight_retain、hindsight_recall、hindsight_reflect。API key 也可以不显式传入而是通过环境变量HINDSIGHT_API_KEY提供——configure()在 config.py 中会优先取显式参数否则回退到该环境变量。本地自托管如果使用./scripts/dev/start-api.sh在本地运行 Hindsight只需把hindsight_api_url指向本地服务地址即可无需其他改动。三个记忆工具的源码视角理解底层实现有助于正确使用。三个工具都通过_resolve_client()解析 Hindsight 客户端见 tools.py解析优先级为显式传入的client→ 显式的hindsight_api_url/api_key→ 全局configure()配置若三者都未提供则抛出HindsightErrorNo Hindsight API URL configured...。客户端创建时使用Hindsight(base_urlurl, timeout30.0)。hindsight_retain写入记忆tool HindsightRetainTool(bank_idmy-bank, tags[topic:async]) tool.forward(Python async/await allows concurrent execution without threads)其forward()实现要点首次调用时通过_ensure_bank()自动调用client.create_bank(bank_id..., namebank_id)创建记忆库且同一会话内只创建一次见 tools.py传入tags时client.retain(bank_id, content, tags...)会一并存储标签成功返回Memory stored successfully.失败时记录 error 日志并包装为HindsightError抛出hindsight_recall检索记忆tool HindsightRecallTool(bank_idmy-bank, budgetmid, max_tokens4096) tool.forward(What have I learned about Python async patterns?)其forward()实现要点调用client.recall(bank_id, query, budget, max_tokens)可选携带tags与tags_match匹配模式为any/all/any_strict/all_strict无结果时返回No relevant memories found.有结果时输出带编号的列表例如1. fact1\n2. fact2\n3. fact3便于智能体引用测试用例 test_tools.py 覆盖了编号输出、空结果回退、budget/max_tokens 透传、标签可选传递等行为hindsight_reflect综合反思tool HindsightReflectTool(bank_idmy-bank, budgetmid) tool.forward(What are the main themes in everything Ive learned about ML?)其forward()实现要点调用client.reflect(bank_id, query, budget)返回的是服务端基于记忆综合生成的连贯回答而非原始事实列表返回文本为空或为None时回退为No relevant memories found.工厂函数与工具裁剪create_hindsight_tools()是推荐的入口支持共享配置并灵活选择工具参数默认值说明bank_id必填Hindsight 记忆库 IDclientNone预先配置好的 Hindsight 客户端优先hindsight_api_urlNoneAPI 地址未提供 client 时使用api_keyNoneAPI key未提供 client 时使用budgetmidRecall/Reflect 的预算级别low/mid/highmax_tokens4096Recall 结果的最大 token 数tagsNone存储记忆时附加的标签recall_tagsNone检索记忆时用于过滤的标签recall_tags_matchany标签匹配模式enable_retainTrue是否包含 retain 工具enable_recallTrue是否包含 recall 工具enable_reflectTrue是否包含 reflect 工具例如只需保留与检索、不需要反思时tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, enable_retainTrue, enable_recallTrue, enable_reflectFalse, # 省略 reflect )也可以直接实例化工具类按需组合from hindsight_smolagents import HindsightRetainTool, HindsightRecallTool agent CodeAgent( tools[ HindsightRetainTool(bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io), HindsightRecallTool(bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io), ], modelHfApiModel(), )测试证实test_tools.py默认创建 3 个工具且共享同一个解析出的客户端实例enable_*开关可精确控制工具组合。将记忆注入系统提示词memory_instructionsSmolAgents 没有自动注入机制因此集成提供了memory_instructions()在构造阶段同步执行一次 recall把相关记忆格式化成字符串供开发者拼接到system_prompt中让智能体在首轮推理前就自带历史上下文from hindsight_smolagents import create_hindsight_tools, memory_instructions tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, ) memories memory_instructions( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, ) agent CodeAgent( toolstools, modelHfApiModel(), system_promptfYou are a helpful assistant.\n\n{memories}, )memory_instructions()参数参数默认值说明bank_id必填从中召回的 Hindsight 记忆库 IDclientNone预先配置好的客户端hindsight_api_url/api_keyNone未提供 client 时的连接信息queryrelevant context about the user记忆注入的召回查询budgetlow召回预算级别max_results5最多注入的记忆条数max_tokens4096召回结果最大 token 数prefixRelevant memories:\n记忆列表前的前缀文本tags/tags_matchNone/any召回结果过滤标签及其匹配模式实现上见 tools.py该方法在构造时同步执行一次 recall无结果时返回空字符串任何异常都会静默返回空字符串避免记忆注入失败阻塞智能体启动。全局配置 configure()configure()提供全局默认配置见 config.py参数默认值说明hindsight_api_urlhttps://api.hindsight.vectorize.ioHindsight API 地址api_keyHINDSIGHT_API_KEY环境变量认证 API keybudgetmid默认召回预算级别max_tokens4096默认召回最大 token 数tagsNoneretain 操作的默认标签recall_tagsNone过滤召回结果的默认标签recall_tags_matchany默认标签匹配模式verboseFalse是否开启详细日志配置后即可省略连接参数from hindsight_smolagents import configure, create_hindsight_tools configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyyour-api-key, budgetmid, # 召回预算low/mid/high max_tokens4096, # 召回结果最大 token tags[env:prod], # 存储记忆的标签 recall_tags[scope:global], # 召回过滤标签 recall_tags_matchany, # 标签匹配模式 ) tools create_hindsight_tools(bank_iduser-123)配置解析遵循显式参数 全局配置的覆盖顺序测试 test_tools.py 对此有完整验证。实战用例用例一代码评审 Agent一个能从过往评审中学习的代码评审智能体from hindsight_smolagents import configure, create_hindsight_tools from smolagents import CodeAgent configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyyour-hindsight-key ) memory_tools create_hindsight_tools(bank_idcode-reviews) agent CodeAgent( tools[CodeAnalysisTool()] memory_tools, system_prompt You are a code review expert. Before reviewing, use hindsight_recall to recall what youve learned about common issues in this codebase. After reviewing, use hindsight_retain to save your findings so future reviews improve. ) # 每次评审都滋养下一次 for pr in pull_requests: result agent.run(fReview PR {pr.number}: {pr.diff})该智能体跨评审累积机构知识能识别历史模式并捕获反复出现的 bug。用例二数据分析 Agent一个分析数据集并记住发现的智能体from hindsight_smolagents import configure, create_hindsight_tools from smolagents import CodeAgent configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyyour-hindsight-key ) memory_tools create_hindsight_tools(bank_iddata-analysis) agent CodeAgent( tools[PandasTool(), SQLQueryTool()] memory_tools ) # 智能体查询数据、留存洞察 result agent.run( Analyze the sales database. Find trends. Use hindsight_retain to save what you learn. Then answer: What does our data tell us about customer behavior? ) # 稍后智能体召回这些洞察 follow_up agent.run( Use hindsight_recall to remember what you learned about customer behavior. Then answer: How should we adjust pricing based on what youve learned? )智能体的分析随时间复利增长——每一次新查询都能引用之前的发现。用例三研究助理一个阅读论文并构建知识库的智能体from hindsight_smolagents import configure, create_hindsight_tools from smolagents import CodeAgent configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyyour-hindsight-key ) memory_tools create_hindsight_tools(bank_idresearch-papers) agent CodeAgent( tools[DocumentReaderTool()] memory_tools ) # 处理一系列论文 papers [paper1.pdf, paper2.pdf, paper3.pdf] for paper in papers: agent.run(fRead {paper}. Extract key findings and use hindsight_retain to save them.) # 然后综合 summary agent.run(Use hindsight_reflect to analyze everything youve learned. What are the major themes?)该智能体跨多篇论文综合提炼识别出任何单一来源都无法显现的模式。完整示例跨会话学习循环下面的完整示例展示一个在多次交互中持续学习的智能体from hindsight_smolagents import configure, create_hindsight_tools from smolagents import CodeAgent, DuckDuckGoSearchTool # 全局配置一次 configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyyour-hindsight-key ) # 创建带记忆工具的智能体 memory_tools create_hindsight_tools(bank_idlearning-agent) agent CodeAgent( tools[DuckDuckGoSearchTool()] memory_tools ) # 第一个任务研究机器学习 print( Task 1: ML Research ) result1 agent.run( Search for the latest machine learning breakthroughs in 2026. Focus on: transformer improvements, efficiency, novel architectures. Use hindsight_retain to save your findings. ) # 第二个任务基于先前学习继续 print(\n Task 2: Build on Prior Learning ) result2 agent.run( Use hindsight_recall to remember what you learned about ML breakthroughs. Now research how these apply to resource-constrained environments. Use hindsight_retain to save what you discover. ) # 第三个任务综合学习成果 print(\n Task 3: Synthesize ) result3 agent.run( Use hindsight_reflect to synthesize everything youve learned about ML in 2026. What are the patterns? Whats most important? What should developers focus on? ) print(result3) # Agent 的高层综合结果每个任务都建立在前一个任务之上智能体召回已学内容将其应用到新问题再跨所有交互进行综合。最佳实践显式留存Explicit Retention只在智能体发现真正有价值的信息时调用retain()而不是每一步都调用保持记忆聚焦、不冗余。上下文化召回Contextual Recall使用具体查询。What have I learned about database performance? 远好于 Tell me everything. 具体的问题能命中更精准的语义匹配。定期反思Reflect Periodically完成多个任务后用reflect()综合所学、识别模式把零散事实沉淀为可复用的方法论。用标签组织Tag for Organization使用[ml, 2026]、[database, performance]这类标签按主题组织事实recall 时配合recall_tags与recall_tags_match精准过滤避免无关记忆干扰推理。给智能体分版本Version Your Agent不同角色/版本的智能体记忆需求不同用独立的bank_id隔离不同角色的记忆库防止知识串扰。故障排查Recall 返回空通常是智能体还没 retain 任何内容或查询与已存事实不匹配。确认 retain 确实被调用并检查存储内容。记忆感觉重复冗余事实被多次存储。用标签约束 有选择地 retain质量优先于数量。Reflect 输出过于泛化为 reflect 提供上下文。调用reflect(Reflect on what youve learned about X)比开放式反思更有价值。API 错误从源码角度看需要重点排查三点bank_id是否存在——好在 retain 工具会在首次调用时自动创建记忆库tools.py一般无需手动预建API key 是否有效——可通过configure()显式传入或设置HINDSIGHT_API_KEY环境变量连接配置是否完整——若既没传client/hindsight_api_url也没调用configure()会直接抛出HindsightError: No Hindsight API URL configured...。进一步探索hindsight-smolagents 集成 README完整的功能说明、Quick Start 与配置参考表三个记忆工具的源码实现retain/recall/reflect 的完整调用链全局配置源码configure()与环境变量解析逻辑单元测试工具行为、配置回退、错误包装的完整验证仓库根目录 README.md了解 Hindsight 整体架构与自托管方式【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考