Hindsight 实战指南：为 SmolAgents 添加持久化记忆（原生 Tool 子类 + 可选系统提示注入）
【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight
本指南基于 Hindsight 开源仓库中的官方文档与hindsight-smolagents集成包源码，手把手讲解如何为 HuggingFace SmolAgents 的CodeAgent接入跨会话的长期记忆：通过三个原生Tool子类（hindsight_retain、hindsight_recall、hindsight_reflect）让 Agent 自主读写记忆，并可选地用memory_instructions()在运行前把最相关的记忆预注入系统提示。读完本文，你将掌握完整的安装、连接、bank 隔离策略、参数调优与验证排错方法，且全程无需改动 SmolAgents 自身的 Agent 循环。
快速答案（Quick answer）
- 安装
hindsight-smolagents集成包（或插件）；- 将其指向 Hindsight Cloud 或本地自托管的 Hindsight API；
- 用稳定的 bank ID 把记忆接入 SmolAgents 运行时；
- 存入一条偏好或项目事实，然后开启一次全新运行；
- 确认 recall 能自动把之前的上下文带回来。
为什么这套方案可行
SmolAgents 的设计围绕工具（tool）展开，因此 Hindsight 可以非常干净地嵌入其中。Agent 在需要时可以主动调用记忆工具（retain / recall / reflect），同时一段简单的指令字符串可以在运行开始前把最相关的上下文"前置加载"进系统提示。这样既保留了熟悉的CodeAgent工作流，又在其背后增加了一层持久化记忆，属于"最小侵入"的接入方式。
从源码看，这套方案正是通过继承 SmolAgents 的Tool基类实现的：HindsightRetainTool、HindsightRecallTool、HindsightReflectTool三个类都定义了name、description、inputs、output_type等 Tool 元数据（见 tools.py），可以直接被任何接受工具的 SmolAgents Agent 使用。
前置条件
- 一个可用的 SmolAgents Agent，例如
CodeAgent； - Python 环境已安装
hindsight-smolagents； - 为同一个用户、项目或助理准备一个跨运行稳定的 bank ID（Hindsight 记忆库标识）。
Step 1：安装集成包
pip install hindsight-smolagents根据 pyproject.toml 中的声明，该包要求：
- Python >= 3.10；
- 依赖
smolagents与hindsight-client >= 0.4.0（后者负责与 Hindsight API 通信）； - 运行环境需要一个可访问的 Hindsight API 服务（Cloud 或自托管）。
Step 2：连接 SmolAgents 与 Hindsight
推荐使用Hindsight Cloud（免费档，无需自托管），注册后获取 API Key 即可。在代码中通过configure()做一次全局配置：
from hindsight_smolagents import configure configure( hindsight_api_url="https://api.hindsight.vectorize.io", api_key="hsk_...", # 或设置 HINDSIGHT_API_KEY 环境变量 budget="mid", max_tokens=4096, )如果改为本地自托管 Hindsight，只需把 API URL 换成http://localhost:8888并去掉api_key（本地 Hindsight API 的默认端口为 8888，仓库中的 监控配置 与 prometheus.yml 均以该端口为默认探活地址）。
你也可以跳过全局配置，直接在create_hindsight_tools()里传入hindsight_api_url。若既不传参也不配置，_resolve_client()会抛出HindsightError（"No Hindsight API URL configured..."），提示必须显式提供连接信息——该行为由 config.py 和 tools.py 共同保证，并有一组单元测试覆盖（见 tests/test_config.py 与 tests/test_tools.py）。
Step 3：把记忆接入运行时
使用工厂函数create_hindsight_tools()一次创建全部记忆工具，再用memory_instructions()生成可注入系统提示的记忆文本：
from smolagents import CodeAgent, HfApiModel from hindsight_smolagents import create_hindsight_tools, memory_instructions tools = create_hindsight_tools( bank_id="user-123", hindsight_api_url="https://api.hindsight.vectorize.io", api_key="hsk_...", ) memories = memory_instructions( bank_id="user-123", hindsight_api_url="https://api.hindsight.vectorize.io", api_key="hsk_...", ) agent = CodeAgent( tools=tools, model=HfApiModel(), system_prompt=f"You are a helpful assistant. {memories}", )接入后，Agent 获得了三个可调用的记忆工具（工具名与行为均可从 tools.py 的源码与 tests/test_tools.py 的断言中确认）：
hindsight_retain—— 存储信息到长期记忆（输入content），首次使用时还会自动调用create_bank()确保记忆库存在，且同一会话内只创建一次；hindsight_recall—— 按查询搜索长期记忆，返回编号列表（如1. fact1\n2. fact2），无结果时返回 "No relevant memories found."；hindsight_reflect—— 基于记忆综合出一个有推理的答案（调用 Hindsight 的 reflect 接口，返回response.text），适合需要连贯总结而非原始事实的场景。
create_hindsight_tools()参数参考
| 参数 | 默认值 | 说明 |
|---|---|---|
bank_id | 必填 | Hindsight 记忆库 ID |
client | None | 预配置的 Hindsight 客户端（优先使用） |
hindsight_api_url | None | API 地址（未提供 client 时使用） |
api_key | None | API Key（未提供 client 时使用） |
budget | "mid" | recall/reflect 的预算等级（low/mid/high） |
max_tokens | 4096 | recall 结果的最大 token 数 |
tags | None | 存储记忆时附加的标签 |
recall_tags | None | 搜索记忆时的过滤标签 |
recall_tags_match | "any" | 标签匹配模式（any/all/any_strict/all_strict） |
enable_retain | True | 是否包含 retain（存储）工具 |
enable_recall | True | 是否包含 recall（搜索）工具 |
enable_reflect | True | 是否包含 reflect（综合）工具 |
memory_instructions()参数参考
memory_instructions()在构造时同步执行一次 recall，把格式化好的记忆字符串返回给你，再由你手动拼入system_prompt——因为 SmolAgents 本身没有自动注入机制（该设计在 tools.py 的 docstring 中有明确说明）。若没有结果或调用失败，它返回空字符串，不会阻塞 Agent 启动。
| 参数 | 默认值 | 说明 |
|---|---|---|
bank_id | 必填 | 要从中 recall 的记忆库 ID |
client | None | 预配置的 Hindsight 客户端 |
hindsight_api_url | None | API 地址（未提供 client 时使用） |
api_key | None | API Key（未提供 client 时使用） |
query | "relevant context about the user" | 用于记忆注入的 recall 查询 |
budget | "low" | recall 预算等级（默认比工具级更低，节省开销） |
max_results | 5 | 最多注入的记忆条数 |
max_tokens | 4096 | recall 结果的最大 token 数 |
prefix | "Relevant memories:\n" | 记忆列表前拼接的文本 |
tags | None | 过滤 recall 结果的标签 |
tags_match | "any" | 标签匹配模式 |
直接使用单个工具类
create_hindsight_tools()只是对三个工具类的便捷封装（工厂内部共享同一个解析出的client实例，见 tools.py）。你也可以按需直接实例化：
from hindsight_smolagents import HindsightRetainTool, HindsightRecallTool agent = CodeAgent( tools=[ HindsightRetainTool( bank_id="user-123", hindsight_api_url="https://api.hindsight.vectorize.io", ), HindsightRecallTool( bank_id="user-123", hindsight_api_url="https://api.hindsight.vectorize.io", ), ], model=HfApiModel(), )只保留需要的工具，可以通过工厂的开关参数完成：
tools = create_hindsight_tools( bank_id="user-123", hindsight_api_url="https://api.hindsight.vectorize.io", enable_retain=True, enable_recall=True, enable_reflect=False, # 省略 reflect )全局配置：避免到处传连接参数
configure()会把默认连接信息保存为模块级全局配置，之后创建工具或生成记忆指令时无需重复传参（显式参数优先级高于全局配置，相关优先级逻辑见 tests/test_config.py 的test_configure_explicit_overrides_env等用例）：
from hindsight_smolagents import configure, create_hindsight_tools configure( hindsight_api_url="https://api.hindsight.vectorize.io", # Hindsight Cloud（默认） api_key="your-api-key", # 或设置 HINDSIGHT_API_KEY 环境变量 budget="mid", # recall 预算：low/mid/high max_tokens=4096, # recall 结果最大 token 数 tags=["env:prod"], # 存储记忆时附加的标签 recall_tags=["scope:global"], # recall 过滤标签 recall_tags_match="any", # 标签匹配模式：any/all/any_strict/all_strict ) # 之后创建工具无需再传连接参数 tools = create_hindsight_tools(bank_id="user-123")configure()参数参考
| 参数 | 默认值 | 说明 |
|---|---|---|
hindsight_api_url | Hindsight Cloud（https://api.hindsight.vectorize.io） | Hindsight API 地址 |
api_key | HINDSIGHT_API_KEY环境变量 | API Key |
budget | "mid" | 默认 recall 预算等级 |
max_tokens | 4096 | 默认 recall 最大 token 数 |
tags | None | retain 操作的默认标签 |
recall_tags | None | 默认 recall 过滤标签 |
recall_tags_match | "any" | 默认标签匹配模式 |
verbose | False | 是否启用详细日志 |
Step 4：选择正确的 bank 策略
- 每个用户一个 bank：当同一个人需要在多个任务间被持续记住时使用；
- 每个项目一个 bank：当单个用户会在互不相关的上下文之间切换时使用。
关键在于：工具和可选的memory_instructions()必须使用同一个 bank key，否则写入与读取落在不同记忆库，记忆无法命中。这套隔离设计在客户端底层同样生效——retain、recall、reflect三个方法都以bank_id作为第一参数路由到对应记忆库（见 hindsight_client.py）。
Step 5：验证记忆是否生效
- 让 Agent 记住一条偏好或可复用的项目事实（触发
hindsight_retain）； - 再次运行 Agent 并询问该细节；
- 确认 recall 能找到之前的记忆——无论是通过注入的上下文还是工具调用；
- 如果测试多个用户，切换 bank ID 并验证记忆彼此隔离。
如果第二次运行能回答出第一次运行留下的细节，说明整套链路已打通。若不能，依次排查：
- 开启调试日志，确认
hindsight_retain是否真的执行完成（retain 工具在底层调用 Hindsight 客户端的retain方法，异常会被包装为HindsightError并记录Retain failed日志，见 tools.py）； - 核对配置的 bank ID 是否前后一致；
- 检查 API URL 与 Key 是否正确解析（无连接信息时会抛出
HindsightError，见 tools.py）。
常见错误（Common mistakes）
- 给工具传了一个 bank ID，却给
memory_instructions()传了另一个不同的 bank ID； - 只挂了工具，却期待自动提示注入（SmolAgents 无自动注入，必须手动拼
system_prompt）； - 在应用确实需要用户隔离时，却让 recall 停留在共享的大 bank 上。
FAQ
必须使用 memory instructions 吗？
不需要。它是可选项——当你希望上下文在 Agent 开始推理前自动注入时再使用。
可以只使用 recall 和 retain 吗？
可以。create_hindsight_tools()的三个开关（enable_retain/enable_recall/enable_reflect）让你自由组合；测试中也逐一验证了"只开 retain / 只开 recall / 只开 reflect / 全关"四种组合的工具数量与名称（见 tests/test_tools.py）。
只适用于 CodeAgent 吗？
不是。该集成遵循 SmolAgents 的工具模型，只要 Agent 接受Tool实例，同样的记忆工具就能接入（三个工具类均直接继承 SmolAgents 的Tool基类，见 tools.py）。
底层原理：一条记忆如何落库与召回
理解这层调用链有助于排查问题（也可直接阅读集成包完整说明 README.md 与文档版集成说明 smolagents.md）：
- 客户端解析：工具构造时通过
_resolve_client()决定 Hindsight 客户端——优先级为显式client> 显式hindsight_api_url/api_key> 全局configure()配置；URL 缺失即抛HindsightError（tools.py）。 - 写入（retain）：
HindsightRetainTool.forward(content)先确保 bank 存在（会话内只创建一次），再调用客户端retain(bank_id, content, tags=...)，成功返回 "Memory stored successfully."；网络类异常统一包装为HindsightError（tools.py）。 - 召回（recall）：
HindsightRecallTool.forward(query)携带budget与max_tokens调用客户端recall()，对结果按1. text编号拼接；无结果时返回提示语（tools.py）。客户端层的recall()还支持types、tags、tags_match、temporal_window、min_scores等更多高级参数（见 hindsight_client.py）。 - 综合（reflect）：
HindsightReflectTool.forward(query)调用客户端reflect()，返回模型综合后的文本；空结果回退为 "No relevant memories found."（tools.py）。 - 预注入：
memory_instructions()在构造期同步执行一次带budget="low"的 recall，截取前max_results条并拼接为可读文本；任何异常都被吞掉并返回空串，保证 Agent 启动不被记忆服务拖垮（tools.py）。
下一步（Next Steps）
- 若希望使用托管的记忆后端，可注册 Hindsight Cloud 直接使用；自托管场景下，Hindsight 的本地 API 默认监听
http://localhost:8888（可参考 监控启动脚本 中的API_PORT约定）； - 深入学习 Hindsight 的 recall 与 retain 接口能力，可阅读 Python 客户端实现 中
retain/recall/reflect三个方法的完整参数文档； - 对照仓库内的单元测试（tests/test_config.py、tests/test_tools.py）理解默认值、优先级与异常路径；
- 本仓库还提供跨运行记忆的进阶讨论，可参见另一篇指南 guide-smolagents-memory-across-runs.md，以及 SmolAgents 记忆工具博客。
【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
