Hindsight × SmolAgents 集成实战用 retain / recall / reflect 为 Agent 注入持久记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南聚焦 Hindsight 官方提供的 SmolAgents 集成包hindsight-smolagentsv0.1.0系统讲解如何通过 SmolAgents 原生Tool模式让 Agent 获得 retain存储、recall检索、reflect综合推理三项长期记忆能力。读者学完后可以完成从安装、连接 Hindsight API、配置记忆工具到将记忆注入 Agent 系统提示词的全流程接入并理解其底层调用链与配置优先级。集成概览原生 Tool 子类 Hindsight 持久记忆hindsight-smolagents是 Hindsight 仓库中 SmolAgents 方向的官方集成包其首个版本0.1.0在集成变更日志见 hindsight-docs/src/pages/changelog/integrations/smolagents.md中正式发布核心能力是让 SmolAgents 智能体通过提供的记忆工具与配置使用 Hindsight 持久记忆。该变更日志对应的完整集成源码与使用文档位于仓库 hindsight-integrations/smolagents 目录。从 源码结构 看该包提供的主要特性包括原生 Tool 子类HindsightRetainTool、HindsightRecallTool、HindsightReflectTool均直接继承 SmolAgents 的Tool基类可无缝传入CodeAgent/ToolCallingAgent记忆注入memory_instructions()在 Agent 构建时同步预检索相关记忆并拼装成可注入system_prompt的文本工厂函数create_hindsight_tools()一次调用即可按需创建全部三个工具且共享同一个 Hindsight 客户端实例统一配置configure()全局配置一次后续创建工具无需重复传参也支持直接传入已构建的 Hindsight 客户端。安装与依赖通过 pip 安装pip install hindsight-smolagents根据 pyproject.toml 中的声明该包的运行要求为依赖说明Python 3.10包的最低 Python 版本要求smolagentsHugging Face 的 Agent 框架提供Tool基类与CodeAgenthindsight-client 0.4.0官方 Hindsight Python 客户端负责与 Hindsight API 通信此外运行环境需要一个可访问的 Hindsight API 服务端。使用 Hindsight Cloud 只需注册并获取 API Key本地开发可参考仓库的 scripts/dev/start-api.sh 启动自托管服务。快速开始一个带长期记忆的 CodeAgent完整可运行的接入示例源码级用法见 hindsight_smolagents/init.py 顶部 docstringfrom smolagents import CodeAgent, HfApiModel from hindsight_smolagents import create_hindsight_tools tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., # 或设置 HINDSIGHT_API_KEY 环境变量 ) agent CodeAgent( toolstools, modelHfApiModel(), ) agent.run(Remember that I prefer dark mode) agent.run(What are my preferences?)第一条指令触发hindsight_retain把偏好写入记忆库第二条指令则通过hindsight_recall检索到该记忆并回答——Agent 由此获得了跨会话的长期记忆能力。bank_id是 Hindsight 记忆库的唯一标识可以按用户、租户或业务场景划分。三个记忆工具源码视角的调用链解析三个工具均定义在 hindsight_smolagents/tools.py 中遵循 SmolAgentsTool子类的标准声明方式name、description、inputs、output_type、forward。hindsight_retain— 写入长期记忆输入contentstring即要存储的信息输出成功返回Memory stored successfully.调用链forward()→_ensure_bank()按需调用client.create_bank()→client.retain(bank_id..., content..., tags...)。值得注意的是_ensure_bank的实现首次写入时如果记忆库不存在会自动创建且create_bank失败例如库已存在也不会阻塞写入同一会话内每个bank_id只尝试创建一次_created_banks集合去重。tags支持在存储时为记忆打标签供后续检索过滤。hindsight_recall— 检索相关记忆输入querystring检索查询输出按编号列表返回匹配记忆如1. fact1\n2. fact2\n3. fact3无结果时返回No relevant memories found.调用链client.recall(bank_id..., query..., budget..., max_tokens..., tags..., tags_match...)。底层对应的客户端方法见 hindsight_client.py 中的recall()budgetlow/mid/high控制检索预算max_tokens限制返回结果长度tags/tags_match控制按标签过滤匹配模式支持any/all/any_strict/all_strict。hindsight_reflect— 基于记忆综合回答输入querystring需要基于记忆回答的问题输出综合后的回答文本空结果时回退为No relevant memories found.调用链client.reflect(bank_id..., query..., budget...)对应客户端的reflect()方法。与 recall 返回原始记忆片段不同reflect 适合需要连贯总结或推理式回答的场景。统一的错误处理三个工具的forward()都遵循相同的错误策略捕获HindsightError时原样抛出不重复包装捕获其他异常时记录logger.error并包装为HindsightError抛出。这一行为在 tests/test_tools.py 中有完整覆盖如test_retain_failure_raises_hindsight_error、test_recall_hindsight_error_not_wrapped。工厂函数一次创建全部记忆工具create_hindsight_tools()是推荐的入口参数齐全且全部工具共享同一个解析出的客户端实例测试test_shares_client_across_tools对此有断言tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., enable_retainTrue, # 默认 True包含存储工具 enable_recallTrue, # 默认 True包含检索工具 enable_reflectFalse, # 关闭综合工具 )完整参数参考参数默认值说明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标签匹配模式any/all/any_strict/all_strictenable_retainTrue是否包含 retain 工具enable_recallTrue是否包含 recall 工具enable_reflectTrue是否包含 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(), )记忆预注入memory_instructions 与系统提示词SmolAgents 没有自动注入机制因此集成包提供memory_instructions()在构建 Agent 时同步执行一次 recall把检索到的相关记忆格式化为文本由开发者拼接到system_prompt中让模型在首轮推理前就记得历史上下文from hindsight_smolagents import create_hindsight_tools, memory_instructions memories memory_instructions( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, ) agent CodeAgent( toolscreate_hindsight_tools(bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io), modelHfApiModel(), system_promptfYou are a helpful assistant.\n\n{memories}, )memory_instructions()参数参考参数默认值说明bank_id必填检索的记忆库 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI 地址api_keyNoneAPI Keyqueryrelevant context about the user预检索查询词budgetlow检索预算级别max_results5注入的最多记忆条数max_tokens4096检索结果最大 token 数prefixRelevant memories:\n记忆列表前的引导文本tagsNone过滤检索结果的标签tags_matchany标签匹配模式实现细节见 tools.py 中memory_instructions()无匹配结果时返回空字符串任何异常都会被静默吞掉并返回空字符串源码注释明确指令失败不应阻塞 Agent 启动。对应测试test_returns_empty_on_exception验证了该容错行为。全局配置configure 与环境变量当有多个工具或多次调用时可用configure()一次性设置默认连接与行为之后创建工具只需传bank_idfrom hindsight_smolagents import configure, create_hindsight_tools configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, # 默认即 Cloud 地址 api_keyyour-api-key, # 或设置 HINDSIGHT_API_KEY 环境变量 budgetmid, # recall 预算low/mid/high max_tokens4096, # recall 结果最大 token 数 tags[env:prod], # 存储记忆时的默认标签 recall_tags[scope:global], # 检索时的默认过滤标签 recall_tags_matchany, # 标签匹配模式 verboseFalse, # 是否启用详细日志 ) tools create_hindsight_tools(bank_iduser-123) # 无需再传连接参数configure()的实现位于 hindsight_smolagents/config.py关键行为包括默认 API 地址常量DEFAULT_HINDSIGHT_API_URL https://api.hindsight.vectorize.ioAPI Key 环境变量名为HINDSIGHT_API_KEYKey 解析优先级显式api_key参数 HINDSIGHT_API_KEY环境变量测试test_configure_explicit_overrides_env验证全局配置可通过get_config()读取、reset_config()清空工具侧_resolve_client()的解析优先级为显式client 显式hindsight_api_url/api_key 全局配置 抛HindsightErrorNo Hindsight API URL configured该逻辑在TestResolveClient与TestToolConstruction系列测试中覆盖完整。配置优先级速查层级优先级说明显式client最高直接使用传入的 Hindsight 客户端显式hindsight_api_url/api_key高仅覆盖连接参数configure()全局配置中未显式传入时回退工具默认值低如budgetmid、max_tokens4096本地自托管开发不使用 Hindsight Cloud 时指向本地 API 服务即可。README 中给出的本地开发示例./scripts/dev/start-api.sh启动服务后tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, )自托管部署方式可参考仓库根目录的 docker/docker-compose 与 helm/hindsight 相关配置。自托管时无需 API Key显式 URL 指向本机服务即可。测试与验证集成包自带完整的单元测试可作为行为契约使用tests/test_config.py覆盖HindsightSmolAgentsConfig默认值、configure()的环境变量回退、显式参数覆盖环境变量、get_config()/reset_config()语义tests/test_tools.py覆盖三个工具的 Tool 属性声明、create_hindsight_tools的开关组合、客户端解析优先级、bank 自动创建去重、标签传递、budget/max_tokens 透传、错误包装与日志记录以及memory_instructions的格式化、max_results截断与异常容错。在 hindsight-integrations/smolagents 目录下可直接运行测试开发依赖见 pyproject.toml 的[dependency-groups].devpip install -e .[dev] pytest小结hindsight-smolagents以三个原生Tool子类为骨架、以create_hindsight_tools工厂与configure全局配置为入口把 Hindsight 的持久记忆能力完整封装进了 SmolAgents 生态。接入路径清晰安装包 → 配置连接 → 创建工具 → 挂载到 Agent可选memory_instructions预注入。其容错设计bank 自动创建、指令失败静默、错误统一包装保证了在生产环境中 Agent 的主流程不会被记忆功能阻塞。想深入了解底层记忆库的实现机制可继续阅读 hindsight-clients/python/hindsight_client/hindsight_client.py 中的retain/recall/reflect客户端方法以及 hindsight-api 下的服务端实现。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考