Hindsight × Strands Agents 集成指南：用 hindsight-strands 为 Agent 注入持久记忆

Hindsight × Strands Agents 集成指南用 hindsight-strands 为 Agent 注入持久记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文讲解如何通过官方集成包hindsight-strands让基于 Strands Agents SDKPython构建的 Agent 获得长期记忆能力使用 Strands 原生的tool模式将 Hindsight 的 retain存储、recall检索、reflect综合三大记忆能力封装为普通 Python 工具函数直接传入Agent(tools[...])即可生效。读完本文你将掌握工具工厂create_hindsight_tools()、系统提示词记忆注入memory_instructions()、全局配置configure()以及 FastAPI 生命周期管理等完整用法并了解其底层实现原理。为什么需要给 Strands Agent 接入记忆Strands Agents SDK 默认是无状态的——每次对话结束后Agent 便遗忘了之前的所有交互。hindsight-strands正是为解决这一问题而存在它将 Hindsight 记忆后端的能力封装成 Strands 原生工具让 Agent 可以在会话之间持久化事实、偏好与决策并在后续对话中按需检索与综合。该包同时满足 Strands 生态的两大核心约束工具必须是可通过Agent(tools[...])直接使用的普通 Python 函数工具调用运行在 Strands 自身的 asyncio 事件循环内。集成包通过闭包捕获bank_id与 Hindsight 客户端的方式无需对 Agent 上下文做任何侵入式修改参见 tools.py 模块注释。核心特性根据 hindsight-strands README 与 官方集成文档该集成提供以下能力原生tool函数工具是普通 Python 函数兼容Agent(tools[...])零上下文侵入记忆指令Memory Instructions预先召回相关记忆并注入 Agent 系统提示词三大记忆工具Retain存储、Recall检索、Reflect综合可按需任意组合极简配置可全局配置一次也可直接传入客户端实例。安装与运行前提pip install hindsight-strands根据 pyproject.toml 的依赖声明安装时会自动拉取两个核心依赖strands-agentsStrands Agents SDK 本体提供tool装饰器与Agent类hindsight-client 0.4.0Hindsight 的官方 Python 客户端封装 retain / recall / reflect 等 API 调用。运行环境要求Python 3.10并且需要一个可访问的 Hindsight API 服务器云服务或自托管均可。快速开始方案一使用 Hindsight Cloud推荐注册获取 API Key 后无需自托管即可接入。以下示例完整代码from strands import Agent from hindsight_strands import create_hindsight_tools tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., # 或通过环境变量 HINDSIGHT_API_KEY 提供 ) agent Agent(toolstools) agent(Remember that I prefer dark mode) agent(What are my preferences?)创建后Agent 将自动获得三个可调用工具hindsight_retain— 将信息存储到长期记忆hindsight_recall— 在长期记忆中检索相关事实hindsight_reflect— 基于记忆综合生成有依据的回答。方案二本地自托管开发调试如果你通过仓库脚本scripts/dev/start-api.sh在本地运行 Hindsight只需替换 URLtools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, )本地模式下 API Key 可省略。自托管的完整安装说明可参考 安装指南 对应章节及仓库内的 Hindsight 自托管文档。注意当hindsight-api-url/api_key直接传入时集成包会在内部创建 Hindsight 客户端此时应在程序退出时调用tools.close()同步或await tools.aclose()异步释放资源。深入理解三大记忆工具的实现从源码看tools.py三个工具均由tool装饰器包装在创建时通过闭包捕获bank_id与解析后的客户端实例hindsight_retain(content)调用client.retain(bank_id..., content..., tags...)存储内容成功后返回固定文案Memory stored successfully.。存储前还会通过_ensure_bank()自动调用client.create_bank(bank_id..., name...)确保记忆库存在已存在时静默忽略异常且每个 bank 只尝试创建一次参见 test_tools.py 中对应测试hindsight_recall(query)调用client.recall(...)并传入budget、max_tokens将结果格式化为带编号的列表如1. fact1\n2. fact2无结果时返回No relevant memories found.hindsight_reflect(query)调用client.reflect(...)直接返回综合后的文本空文本时回退到No relevant memories found.。值得关注的一个底层细节Strands 会在自己的 asyncio 事件循环中执行工具而 Hindsight 客户端内部同样使用 asyncio包括asyncio.timeout两者在同一循环中会冲突。因此 tools.py 使用了一个最大 4 线程的ThreadPoolExecutor通过_run_in_thread()将客户端调用放到独立线程执行从而获得全新的事件循环规避循环嵌套问题。另外错误处理上所有非HindsightError的异常会被记录日志并统一包装为HindsightError定义于 errors.py而原本的HindsightError则直接透传便于上层精确处理对应测试见 test_tools.py。记忆指令把记忆注入系统提示词除了让 Agent 主动调用工具你还可以在对话开始前预召回相关记忆并注入系统提示词让 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.\n\n{memories}, )实现上tools.pymemory_instructions()会执行一次同步 recall将结果格式化为Relevant memories:\n\n1. ...\n2. ...形式的字符串若无结果则返回空字符串。其异常处理策略非常务实召回失败时静默返回空字符串绝不让记忆注入失败阻断 Agent 启动。同时若客户端由函数内部创建会在 finally 块中关闭避免连接泄漏。FastAPI 生命周期管理推荐做法在 Web 服务中更推荐的做法是在应用 lifespan 中创建一个共享Hindsight 客户端通过client...传入这样所有权清晰、关闭时机可控from contextlib import asynccontextmanager from fastapi import FastAPI from hindsight_client import Hindsight from hindsight_strands import create_hindsight_tools, memory_instructions asynccontextmanager async def lifespan(app: FastAPI): client Hindsight(base_urlhttps://api.hindsight.vectorize.io, api_keyhsk_...) app.state.hindsight_client client try: yield finally: await client.aclose() app FastAPI(lifespanlifespan) app.post(/chat) async def chat(): client app.state.hindsight_client tools create_hindsight_tools(bank_iduser-123, clientclient) memories memory_instructions(bank_iduser-123, clientclient) ...需要理解的关键点客户端所有权ownership由_resolve_client()决定tools.py显式传入client...时调用方拥有客户端集成包不会关闭它只传hindsight_api_url/api_key时集成包内部创建客户端并拥有它此时需要在关闭阶段调用await tools.aclose()或tools.close()。返回的HindsightTools是 list 兼容容器支持len()、索引、直接传入Agent(tools...)同时提供close()/aclose()方法并支持with与async with上下文管理器tools.py。对应测试验证了close()只关闭内部持有的客户端、绝不误关外部客户端test_tools.py。按需选择工具并非每个 Agent 都需要全部三个工具。通过enable_*开关精确控制暴露给 Agent 的工具集合tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., enable_retainTrue, enable_recallTrue, enable_reflectFalse, # 不暴露 reflect 工具 )从源码看tools.py每个开关对应一段独立的工具构建逻辑全部关闭时返回空列表测试逐一验证了仅 retain / 仅 recall / 仅 reflect / 全关四种组合test_tools.py。全局配置一次配置处处使用如果应用中有多处需要创建工具可以调用configure()设置全局默认值之后创建工具时无需再传连接信息from hindsight_strands import configure, create_hindsight_tools configure( hindsight_api_urlhttp://localhost:8888, api_keyyour-api-key, # 或设置 HINDSIGHT_API_KEY 环境变量 budgetmid, # 召回预算low/mid/high max_tokens4096, # 召回结果的最大 token 数 tags[env:prod], # 存储记忆时附带的标签 recall_tags[scope:global], # 检索时用于过滤的标签 recall_tags_matchany, # 标签匹配模式any/all/any_strict/all_strict ) # 之后无需再传连接参数 tools create_hindsight_tools(bank_iduser-123)从实现看config.pyconfigure()返回并全局保存一个HindsightStrandsConfigdataclass 实例api_key未显式提供时自动回退到HINDSIGHT_API_KEY环境变量。_resolve_client()与工具构建时的参数解析均遵循显式参数 全局配置 默认值的优先级见 tools.pyreset_config()可清空全局配置。相关测试覆盖了 URL / Key 的显式覆盖与全局回退逻辑test_tools.py。配置参考完整参数表create_hindsight_tools()参数默认值说明bank_id必填Hindsight 记忆库bankIDclientNone预配置的 Hindsight 客户端调用方拥有生命周期hindsight_api_urlNoneAPI 地址未传 client 时使用api_keyNoneAPI 密钥未传 client 时使用budgetmidrecall/reflect 预算级别low/mid/highmax_tokens4096召回结果最大 token 数tagsNone存储记忆时附带的标签recall_tagsNone检索时过滤记忆的标签recall_tags_matchany标签匹配模式enable_retainTrue是否包含 retain存储工具enable_recallTrue是否包含 recall检索工具enable_reflectTrue是否包含 reflect综合工具memory_instructions()参数默认值说明bank_id必填Hindsight 记忆库 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI 地址未传 client 时使用api_keyNoneAPI 密钥未传 client 时使用queryrelevant context about the user用于记忆注入的召回查询budgetlow召回预算级别注此处默认 low区别于工具默认的 midmax_results5最多注入的记忆条数max_tokens4096召回结果最大 token 数prefixRelevant memories:\n记忆列表前附加的文本tagsNone过滤召回结果的标签tags_matchany标签匹配模式configure()参数默认值说明hindsight_api_urlHindsight Cloudhttps://api.hindsight.vectorize.ioHindsight API 地址api_keyHINDSIGHT_API_KEY环境变量API 密钥budgetmid默认召回预算级别max_tokens4096召回默认最大 token 数tagsNoneretain 操作默认标签recall_tagsNone默认召回过滤标签recall_tags_matchany默认标签匹配模式verboseFalse是否开启详细日志运行前提与依赖清单Python 3.10strands-agentsStrands SDKhindsight-client 0.4.0一个可访问的 Hindsight API 服务器Hindsight Cloud 或本地自托管。进一步探索完整实现源码hindsight_strands 包tools.py、config.py、errors.py单元测试tests/test_tools.py 与 tests/test_config.py覆盖客户端解析、工具组合、标签透传、客户端生命周期等 40 场景包说明与版本信息README.md、pyproject.toml集成变更记录strands 集成 Changelog更多实战示例可参考 集成文档目录 下的相关指南如 Strands 持久记忆指南与按 Agent 隔离 vs 共享记忆专题。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考