使用 Hindsight 为 Strands Agent 添加持久记忆retain / recall / reflect 工具与 memory_instructions 实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南讲解如何在 Strands Agents SDK 的 Agent 中接入 Hindsight 持久记忆能力通过hindsight-strands集成包创建原生tool风格的hindsight_retain、hindsight_recall、hindsight_reflect三个记忆工具并用memory_instructions()把预召回的记忆注入系统提示词让 Agent 在不同会话之间获得稳定、可隔离的长期记忆。读完本文你将掌握安装集成、连接 Hindsight Cloud 或本地 API、按用户/项目设计 bank ID、验证记忆生效以及常见坑位的完整方案。为什么这套方案成立Strands SDK 在工具与提示词上已经有自己的约定因此 Hindsight 只需要两个插入点就能接入工具函数承载显式的记忆读写动作和可选的注入指令承载自动召回。这意味着你不需要在 Agent 运行时内部再挂一个独立的记忆守护进程集成面小而可预期。从 hindsight-integrations/strands/hindsight_strands/tools.py 的源码看该集成把 Strands 的tool装饰器直接用于普通 Python 函数bank_id和 Hindsight 客户端在构造时通过闭包捕获因此返回的工具列表可以直接传给Agent(tools...)无需修改 Agent 上下文。这正是Strands 已把工具视为普通函数Hindsight 顺势接入这一设计思路的代码级印证。前置条件一个可运行的 Strands Agent基于strands-agentsSDKPython 环境并已安装hindsight-strands一套对同一用户或同一项目保持稳定的bank ID 命名方案快速答案安装 Strands 集成包hindsight-strands将其指向 Hindsight Cloud 或本地 Hindsight API用稳定的 bank ID 把记忆接入 Strands 运行时先存储一条偏好或项目事实再启动一次全新的运行确认 recall 能自动把之前的上下文带回来。Step 1安装集成包pip install hindsight-strands依据 hindsight-integrations/strands/pyproject.toml该包要求 Python 3.10依赖strands-agents与hindsight-client0.4.0当前版本为 0.1.3。安装后即可从hindsight_strands导入公开 APIconfigure、get_config、reset_config、HindsightStrandsConfig、HindsightError、create_hindsight_tools、memory_instructions见 hindsight-integrations/strands/hindsight_strands/init.py。Step 2把 Strands 连接到 Hindsight推荐使用 Hindsight Cloud免费档位无需自托管。连接配置有两种等价写法。方式一全局配置推荐单服务场景from hindsight_strands import configure configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., # 或设置 HINDSIGHT_API_KEY 环境变量 budgetmid, max_tokens4096, )方式二每次调用显式传参from strands import Agent from hindsight_strands import create_hindsight_tools, memory_instructions tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., )如果你在本地自托管 Hindsight把 API URL 换成http://localhost:8888并去掉api_key即可。关于配置解析的细节可参考 hindsight-integrations/strands/hindsight_strands/config.pyconfigure()中api_key优先使用显式参数否则回退到HINDSIGHT_API_KEY环境变量hindsight_api_url缺省时使用默认生产地址https://api.hindsight.vectorize.io。HindsightStrandsConfig还额外支持tags写入记忆时的默认标签、recall_tags召回过滤标签、recall_tags_match标签匹配模式any/all/any_strict/all_strict以及verbose开关。Step 3把记忆接入 Strands 运行时from strands import Agent from hindsight_strands import create_hindsight_tools, memory_instructions tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., ) memories memory_instructions( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., ) agent Agent( toolstools, system_promptfYou are a helpful assistant. {memories}, )如果不想做自动注入去掉memory_instructions()让 Agent 在需要时显式调用 recall 工具即可。三个记忆工具的语义create_hindsight_tools()默认生成三个tool函数可分别用enable_retain/enable_recall/enable_reflect开关裁剪工具作用底层调用hindsight_retain(content)把信息写入长期记忆事实、用户偏好、决策等客户端retain并在首次使用时自动create_bank确保 bank 存在hindsight_recall(query)检索相关记忆返回编号列表无结果时返回 No relevant memories found.客户端recall透传budget/max_tokens可选tags/tags_matchhindsight_reflect(query)基于记忆综合出一条连贯、经过推理的回答多条记忆需要合并时尤其有用客户端reflect返回response.text对应的实现与单元测试分别在 hindsight-integrations/strands/hindsight_strands/tools.py 和 hindsight-integrations/strands/tests/test_tools.py。测试中还验证了bank 只会被创建一次、retain 失败会被包装为HindsightError并记录日志、recall 未命中时返回固定兜底文案、reflect 返回空文本时同样走兜底文案。线程池与事件循环的兼容处理Strands 在自身的 asyncio 事件循环内运行工具而hindsight-client内部也使用 asyncio包括asyncio.timeout直接在同循环内调用会冲突。因此tools.py中通过ThreadPoolExecutor(max_workers4)把每个记忆操作放到独立线程中执行获得一个全新的事件循环——这是集成实现中值得注意的底层细节。客户端生命周期管理如果你传入预先创建的client外部拥有集成不会关闭它tools.close()/await tools.aclose()不会触碰外部客户端如果你通过hindsight_api_url/api_key让集成内部创建客户端返回的HindsightTools容器一个 list 兼容对象会在close()/aclose()时关闭内部客户端也支持with/async with上下文管理器。在 FastAPI 这类服务中推荐在应用 lifespan 里创建共享客户端并显式await client.aclose()关闭再以client...方式传给工具工厂参见 hindsight-integrations/strands/README.md 的 FastAPI Lifecycle 示例。Step 4选择正确的 bank 策略按用户建 bankPer-user通常适合助手类应用每个用户一个独立记忆空间按项目建 bankPer-project适合同一用户在不同无关工作流之间切换的场景无论选择哪种务必保证memory_instructions()与记忆工具使用同一个 bank 值否则会出现工具写入 A bank、提示词从 B bank 召回的错位。Step 5验证记忆确实生效在第一次运行中存储一条偏好或工作事实用相同的 bank ID 启动第二次运行询问之前的事实确认 Agent 能前后一致地回答换一个不同的 bank ID 测试确认记忆隔离符合预期。如果第二次运行能回答出第一次运行中的细节说明配置成功。如果不行打开 debug 日志、检查配置的 bank ID并确认 retain 调用确实完成。全局配置 vs 每次调用传参全局配置configure()适合单一服务一次设置后create_hindsight_tools(bank_id...)与memory_instructions(bank_id...)会自动读取全局默认值API URL、api_key、budget、max_tokens、tags、recall_tags 等无需重复传连接参数。每次调用传参则更安全适合不同 Agent 需要不同记忆行为不同 bank、不同 budget、不同标签策略的场景。从 hindsight-integrations/strands/tests/test_config.py 可以看到configure()每次调用都会生成并替换新的配置实例显式参数优先于环境变量与全局配置。_resolve_client()的解析优先级为显式client 显式hindsight_api_url/api_key 全局配置 报错HindsightError: No Hindsight API URL configured并且在内部创建客户端时会设置 30 秒超时与hindsight-strands/version的用户代理标识。常见错误与排查工具与提示词使用不同 bank用memory_instructions()构建的提示词来自一个 bank而工具指向另一个 bank导致召回与写入隔离失效忘记自动注入是可选行为memory_instructions()必须显式加入 system prompt 才会生效共享 bank 误用应用需要严格用户隔离时却选择了共享 bank会造成记忆串扰调用失败排查确认 API URL 可达、api_key正确、retain 实际完成开启 verbose 或 debug 日志观察。值得一提的容错设计memory_instructions()内部召回失败时会静默返回空字符串避免记忆注入故障阻塞 Agent 主流程见 hindsight-integrations/strands/tests/test_tools.py 的test_returns_empty_on_exception。FAQ可以只用基于工具的记忆吗可以。如果你希望由 Agent 自行决定何时查询记忆工具本身已经足够不需要memory_instructions()。reflect 相比 recall 多提供了什么Recall 返回的是原始记忆条目的编号列表Reflect 则基于记忆综合生成一段合成回答当需要把多条记忆合并推理时更有价值。应该全局配置还是每次调用配置全局配置适合单一服务、统一行为每次调用传参适合不同 Agent 需要不同记忆行为不同 bank、预算、标签的场景。下一步在 hindsight-integrations/strands/README.md 查看完整参数对照表create_hindsight_tools()、memory_instructions()、configure()的每个参数默认值与含义阅读 hindsight-docs/docs-integrations/strands.md 获取集成文档中的更多细节阅读 cookbook/README.md 了解其他落地范例结合源码 hindsight-integrations/strands/hindsight_strands/tools.py 与测试 hindsight-integrations/strands/tests/test_tools.py 深入理解工具工厂的边界行为与容错逻辑。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Hindsight 为 Strands Agent 添加持久记忆：retain / recall / reflect 工具与 memory_instructions 实战指南
使用 Hindsight 为 Strands Agent 添加持久记忆retain / recall / reflect 工具与 memory_instructions 实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南讲解如何在 Strands Agents SDK 的 Agent 中接入 Hindsight 持久记忆能力通过hindsight-strands集成包创建原生tool风格的hindsight_retain、hindsight_recall、hindsight_reflect三个记忆工具并用memory_instructions()把预召回的记忆注入系统提示词让 Agent 在不同会话之间获得稳定、可隔离的长期记忆。读完本文你将掌握安装集成、连接 Hindsight Cloud 或本地 API、按用户/项目设计 bank ID、验证记忆生效以及常见坑位的完整方案。为什么这套方案成立Strands SDK 在工具与提示词上已经有自己的约定因此 Hindsight 只需要两个插入点就能接入工具函数承载显式的记忆读写动作和可选的注入指令承载自动召回。这意味着你不需要在 Agent 运行时内部再挂一个独立的记忆守护进程集成面小而可预期。从 hindsight-integrations/strands/hindsight_strands/tools.py 的源码看该集成把 Strands 的tool装饰器直接用于普通 Python 函数bank_id和 Hindsight 客户端在构造时通过闭包捕获因此返回的工具列表可以直接传给Agent(tools...)无需修改 Agent 上下文。这正是Strands 已把工具视为普通函数Hindsight 顺势接入这一设计思路的代码级印证。前置条件一个可运行的 Strands Agent基于strands-agentsSDKPython 环境并已安装hindsight-strands一套对同一用户或同一项目保持稳定的bank ID 命名方案快速答案安装 Strands 集成包hindsight-strands将其指向 Hindsight Cloud 或本地 Hindsight API用稳定的 bank ID 把记忆接入 Strands 运行时先存储一条偏好或项目事实再启动一次全新的运行确认 recall 能自动把之前的上下文带回来。Step 1安装集成包pip install hindsight-strands依据 hindsight-integrations/strands/pyproject.toml该包要求 Python 3.10依赖strands-agents与hindsight-client0.4.0当前版本为 0.1.3。安装后即可从hindsight_strands导入公开 APIconfigure、get_config、reset_config、HindsightStrandsConfig、HindsightError、create_hindsight_tools、memory_instructions见 hindsight-integrations/strands/hindsight_strands/init.py。Step 2把 Strands 连接到 Hindsight推荐使用 Hindsight Cloud免费档位无需自托管。连接配置有两种等价写法。方式一全局配置推荐单服务场景from hindsight_strands import configure configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., # 或设置 HINDSIGHT_API_KEY 环境变量 budgetmid, max_tokens4096, )方式二每次调用显式传参from strands import Agent from hindsight_strands import create_hindsight_tools, memory_instructions tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., )如果你在本地自托管 Hindsight把 API URL 换成http://localhost:8888并去掉api_key即可。关于配置解析的细节可参考 hindsight-integrations/strands/hindsight_strands/config.pyconfigure()中api_key优先使用显式参数否则回退到HINDSIGHT_API_KEY环境变量hindsight_api_url缺省时使用默认生产地址https://api.hindsight.vectorize.io。HindsightStrandsConfig还额外支持tags写入记忆时的默认标签、recall_tags召回过滤标签、recall_tags_match标签匹配模式any/all/any_strict/all_strict以及verbose开关。Step 3把记忆接入 Strands 运行时from strands import Agent from hindsight_strands import create_hindsight_tools, memory_instructions tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., ) memories memory_instructions( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., ) agent Agent( toolstools, system_promptfYou are a helpful assistant. {memories}, )如果不想做自动注入去掉memory_instructions()让 Agent 在需要时显式调用 recall 工具即可。三个记忆工具的语义create_hindsight_tools()默认生成三个tool函数可分别用enable_retain/enable_recall/enable_reflect开关裁剪工具作用底层调用hindsight_retain(content)把信息写入长期记忆事实、用户偏好、决策等客户端retain并在首次使用时自动create_bank确保 bank 存在hindsight_recall(query)检索相关记忆返回编号列表无结果时返回 No relevant memories found.客户端recall透传budget/max_tokens可选tags/tags_matchhindsight_reflect(query)基于记忆综合出一条连贯、经过推理的回答多条记忆需要合并时尤其有用客户端reflect返回response.text对应的实现与单元测试分别在 hindsight-integrations/strands/hindsight_strands/tools.py 和 hindsight-integrations/strands/tests/test_tools.py。测试中还验证了bank 只会被创建一次、retain 失败会被包装为HindsightError并记录日志、recall 未命中时返回固定兜底文案、reflect 返回空文本时同样走兜底文案。线程池与事件循环的兼容处理Strands 在自身的 asyncio 事件循环内运行工具而hindsight-client内部也使用 asyncio包括asyncio.timeout直接在同循环内调用会冲突。因此tools.py中通过ThreadPoolExecutor(max_workers4)把每个记忆操作放到独立线程中执行获得一个全新的事件循环——这是集成实现中值得注意的底层细节。客户端生命周期管理如果你传入预先创建的client外部拥有集成不会关闭它tools.close()/await tools.aclose()不会触碰外部客户端如果你通过hindsight_api_url/api_key让集成内部创建客户端返回的HindsightTools容器一个 list 兼容对象会在close()/aclose()时关闭内部客户端也支持with/async with上下文管理器。在 FastAPI 这类服务中推荐在应用 lifespan 里创建共享客户端并显式await client.aclose()关闭再以client...方式传给工具工厂参见 hindsight-integrations/strands/README.md 的 FastAPI Lifecycle 示例。Step 4选择正确的 bank 策略按用户建 bankPer-user通常适合助手类应用每个用户一个独立记忆空间按项目建 bankPer-project适合同一用户在不同无关工作流之间切换的场景无论选择哪种务必保证memory_instructions()与记忆工具使用同一个 bank 值否则会出现工具写入 A bank、提示词从 B bank 召回的错位。Step 5验证记忆确实生效在第一次运行中存储一条偏好或工作事实用相同的 bank ID 启动第二次运行询问之前的事实确认 Agent 能前后一致地回答换一个不同的 bank ID 测试确认记忆隔离符合预期。如果第二次运行能回答出第一次运行中的细节说明配置成功。如果不行打开 debug 日志、检查配置的 bank ID并确认 retain 调用确实完成。全局配置 vs 每次调用传参全局配置configure()适合单一服务一次设置后create_hindsight_tools(bank_id...)与memory_instructions(bank_id...)会自动读取全局默认值API URL、api_key、budget、max_tokens、tags、recall_tags 等无需重复传连接参数。每次调用传参则更安全适合不同 Agent 需要不同记忆行为不同 bank、不同 budget、不同标签策略的场景。从 hindsight-integrations/strands/tests/test_config.py 可以看到configure()每次调用都会生成并替换新的配置实例显式参数优先于环境变量与全局配置。_resolve_client()的解析优先级为显式client 显式hindsight_api_url/api_key 全局配置 报错HindsightError: No Hindsight API URL configured并且在内部创建客户端时会设置 30 秒超时与hindsight-strands/version的用户代理标识。常见错误与排查工具与提示词使用不同 bank用memory_instructions()构建的提示词来自一个 bank而工具指向另一个 bank导致召回与写入隔离失效忘记自动注入是可选行为memory_instructions()必须显式加入 system prompt 才会生效共享 bank 误用应用需要严格用户隔离时却选择了共享 bank会造成记忆串扰调用失败排查确认 API URL 可达、api_key正确、retain 实际完成开启 verbose 或 debug 日志观察。值得一提的容错设计memory_instructions()内部召回失败时会静默返回空字符串避免记忆注入故障阻塞 Agent 主流程见 hindsight-integrations/strands/tests/test_tools.py 的test_returns_empty_on_exception。FAQ可以只用基于工具的记忆吗可以。如果你希望由 Agent 自行决定何时查询记忆工具本身已经足够不需要memory_instructions()。reflect 相比 recall 多提供了什么Recall 返回的是原始记忆条目的编号列表Reflect 则基于记忆综合生成一段合成回答当需要把多条记忆合并推理时更有价值。应该全局配置还是每次调用配置全局配置适合单一服务、统一行为每次调用传参适合不同 Agent 需要不同记忆行为不同 bank、预算、标签的场景。下一步在 hindsight-integrations/strands/README.md 查看完整参数对照表create_hindsight_tools()、memory_instructions()、configure()的每个参数默认值与含义阅读 hindsight-docs/docs-integrations/strands.md 获取集成文档中的更多细节阅读 cookbook/README.md 了解其他落地范例结合源码 hindsight-integrations/strands/hindsight_strands/tools.py 与测试 hindsight-integrations/strands/tests/test_tools.py 深入理解工具工厂的边界行为与容错逻辑。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考