使用 hindsight-composio 为 Composio Agent 接入 Hindsight 持久化记忆retain / recall / reflect 自定义工具实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文讲解如何通过hindsight-composio集成包把 Hindsight 的 retain存储、recall检索、reflect综合推理三大核心记忆操作注册为 Composio 会话内的自定义工具custom tools让运行在 Composio 上的 Agent 直接以工具调用tool calling的方式读写长期记忆从而做到跨会话持续记忆、每次对话不再从零开始。读完本文你将掌握包的安装与后端指向、工具注册与按需裁剪、基于user_id的按用户记忆隔离机制、全局配置方式以及一套可复现的记忆生效验证流程。为什么选择 hindsight-composio在 Agent 已有的工具调用循环里加记忆Composio Agent 的常规工作方式是Agent 在推理循环中调用注册好的工具来获取能力。hindsight-composio的核心思路正是把 Hindsight 的记忆能力伪装成三个普通工具——HINDSIGHT_RETAIN、HINDSIGHT_RECALL、HINDSIGHT_REFLECT——注册进同一个会话从而让记忆读写成为 Agent 自身工具调用循环的一部分由 Agent 自己决定何时存储、何时检索。从源码看工具通过composio.experimental.tool()装饰器注册为 in-process 自定义工具见 tools.py并绑定到具体会话。每个调用对应的 Hindsight 记忆库bank取自会话的user_id因此一套注册好的工具集即可自动实现按用户隔离记忆当调用没有user_id时可配置一个兜底记忆库fallback bank。该集成适合 Composio 的核心原因还有一层官方 README 明确指出它只面向 Composio 0.13.x SDKfrom composio import Composio并刻意排除了 API 完全不同的 1.0.0 重写版本同时明确提示自定义工具 API 目前仍是 experimental 状态——这两点是选型和排障时必须知晓的前提。快速上手Quick answer完整方案可以浓缩为五个步骤pip install hindsight-composio设置HINDSIGHT_API_KEYHindsight Cloud或传入hindsight_api_url自托管调用register_hindsight_tools(composio, ...)构建工具集创建带user_id的 Composio 会话——该user_id即 Hindsight 的bank_id验证后一个会话能召回前一个会话存储的内容前置条件动手前请确认环境满足Python 3.10pyproject.toml中requires-python 3.10见 pyproject.tomlComposio 已安装并可用composio 0.13.1, 1且已配置COMPOSIO_API_KEY可达的 Hindsight 后端Hindsight Cloud或自托管的 Hindsight 服务器依赖自动带入pip install hindsight-composio会拉取hindsight-client 0.4.0与pydantic 2注意包版本为 0.1.0见 pyproject.toml属于 Beta 阶段Development Status :: 4 - Beta生产接入前建议评估其演进节奏。Step 1安装集成包pip install hindsight-composio安装后hindsight_composio包会暴露两个核心函数register_hindsight_tools和configure完整导出清单见init.py它们就是你接线 Hindsight 与 Composio 的全部入口。Step 2把工具指向 Hindsight 后端使用 Hindsight Cloud通过环境变量设置 API Keyexport HINDSIGHT_API_KEYhsk_...然后注册工具from composio import Composio from hindsight_composio import register_hindsight_tools composio Composio() # 使用 COMPOSIO_API_KEY tools register_hindsight_tools( composio, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., # 或通过 HINDSIGHT_API_KEY 环境变量设置 )使用自托管服务器把 URL 换成你自己的服务地址即可tools register_hindsight_tools( composio, hindsight_api_urlhttp://localhost:8888, )底层机制客户端解析register_hindsight_tools内部通过_resolve_client见 tools.py解析 Hindsight 客户端优先级为显式传入的client参数 hindsight_api_url/api_key参数 全局configure()配置 默认生产 URLhttps://api.hindsight.vectorize.io见 config.py。解析出的客户端使用 30 秒超时若既无 URL 也无配置会抛出HindsightError: No Hindsight API URL configured。这一点已被单元测试覆盖test_creates_client_from_url验证了Hindsight(base_url..., timeout30.0)的构造方式test_explicit_url_overrides_config验证了显式 URL 优先于全局配置见 tests/test_tools.py。Step 3在会话上注册工具创建 Composio 会话并把工具作为自定义工具传入。user_id会成为 Hindsight 的记忆库banksession composio.create( user_iduser-123, # 即 Hindsight 的 bank_id experimental{custom_tools: tools}, ) # 像往常一样把 session.tools() 传给 agent/LLM该会话现在有三个可被 Agent 调用的工具工具 slug作用输入HINDSIGHT_RETAIN将信息存入长期记忆content要存储的信息HINDSIGHT_RECALL在长期记忆中检索相关事实query检索查询HINDSIGHT_REFLECT基于记忆综合推理出有依据的回答query要反思的问题三个工具的输入模型RetainInput/RecallInput/ReflectInput均为 Pydantic 模型见 tools.pyComposio 会据此为 LLM 生成工具 schema。测试test_custom_tools_carry_input_schema验证了注册后的工具确实携带input_params为对应 Pydantic 模型见 tests/test_tools.py。按需裁剪工具三个工具默认全部启用。若只想暴露其中一部分通过enable_retain/enable_recall/enable_reflect控制tools register_hindsight_tools( composio, hindsight_api_urlhttps://api.hindsight.vectorize.io, enable_retainTrue, enable_recallTrue, enable_reflectFalse, # 不暴露 reflect )测试test_enable_retain_only、test_no_tools_when_all_disabled分别验证了单工具注册与全禁用返回空列表的行为见 tests/test_tools.py。工具如何读写记忆三个工具的行为由 tools.py 中的三个内部函数实现Retainhindsight_retain调用client.retain(bank_id..., content...)可附带tags标签成功后返回{status: stored, bank: bank}。存储前会先create_bank确保记忆库存在且同一 bank 只会尝试创建一次见_ensure_banktools.py。Recallhindsight_recall调用client.recall(bank_id..., query..., budget..., max_tokens...)可选tagstags_match过滤返回{memories: [...], count: n}无结果时返回空列表。Reflecthindsight_reflect调用client.reflect(bank_id..., query..., budget...)返回综合后的{answer: ...}若回答为空则回退为No relevant memories found.。三个工具都会捕获底层异常并包装为HindsightError抛出异常类型定义见 errors.py同时记录错误日志。因为工具直接注册在会话上何时存储、何时检索完全由 Agent 在工具调用循环中自主决定——记忆能力与 Agent 已有的其他工具能力无缝融合无需任何额外的编排代码。补充说明由于工具是直接绑定会话的测试test_recall_does_not_create_bank表明 recall 不会隐式创建 bank只有 retain 才会因此对全新用户先做 recall 会得到空结果而非报错见 tests/test_tools.py。按用户隔离的记忆库Per-user memory banks记忆库bank在每次调用时按以下顺序解析会话的user_id推荐方式一套工具集自动按用户隔离default_bank传给register_hindsight_tools或configure仅当调用没有user_id时使用若两者都不可用工具会抛出HindsightError: No Hindsight bank for this call见 tools.py。设置兜底记忆库tools register_hindsight_tools( composio, hindsight_api_urlhttps://api.hindsight.vectorize.io, default_bankshared, # 仅当会话没有 user_id 时使用 )底层解析逻辑是bank getattr(ctx, user_id, None) or default_bank测试test_user_id_takes_precedence_over_default_bank证实了user_id优先于default_bank见 tests/test_tools.py。全局一次性配置如果不想每次调用都传连接参数可以用configure()一次性设置连接信息、预算、标签等全局默认值from hindsight_composio import configure, register_hindsight_tools configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyyour-api-key, # 或设置 HINDSIGHT_API_KEY 环境变量 default_bankshared, # 无 user_id 时的兜底 bank budgetmid, # recall/reflect 预算low/mid/high max_tokens4096, # recall 结果的最大 token 数 tags[env:prod], # 存储记忆时附带的标签 recall_tags[scope:global], # recall 检索时的标签过滤 recall_tags_matchany, # any/all/any_strict/all_strict ) tools register_hindsight_tools(composio)configure()的实现细节见 config.py未传api_key时自动回退到HINDSIGHT_API_KEY环境变量未传 URL 时使用默认生产地址https://api.hindsight.vectorize.io配置存于模块级全局对象可用get_config()读取、reset_config()重置。register_hindsight_tools会合并显式参数 全局配置 默认值三层取值见 tools.py参数表如下参数默认值说明composio必填Composio实例提供experimental.tool装饰器clientNone预配置的 Hindsight 客户端优先hindsight_api_urlNoneAPI URL未传 client 时使用api_keyNoneAPI Key未传 client 时使用default_bankNone调用无user_id时使用的 bankbudgetmidrecall/reflect 预算等级low/mid/highmax_tokens4096recall 结果的最大 token 数tagsNoneretain 存储记忆时附带的标签recall_tagsNonerecall 检索时的标签过滤recall_tags_matchany标签匹配模式any/all/any_strict/all_strictenable_retainTrue是否包含 retain存储工具enable_recallTrue是否包含 recall检索工具enable_reflectTrue是否包含 reflect综合工具验证记忆真正生效一套可复现的验证流程注册工具并创建带user_id的会话让 Agent 调用HINDSIGHT_RETAIN存储一条事实用相同user_id启动一个新会话让 Agent 调用HINDSIGHT_RECALL检索该事实确认前一个会话存储的事实被召回实际场景示例会话一在对话中记录了用户的偏好会话二同一用户在后续请求中成功召回该偏好如果 recall 能召回此前会话存储的内容说明记忆链路已打通。参考实现端到端测试仓库中的 E2E 测试给出了与上述流程完全一致的落地代码见 tests/test_e2e.py例如test_retain_and_recall_roundtrip构造Hindsight客户端指向HINDSIGHT_API_URL默认http://localhost:8888用_Ctx(user_idbank_id)模拟 Composio 注入的会话上下文调用hindsight_retain存储 The team uses PostgreSQL 16 and deploys to us-east-1.轮询调用hindsight_recall最多 12 次、间隔 1 秒查询 What technologies does the team use?断言召回内容中包含 postgresql 或 us-east-1test_reflect_synthesizes_from_memory则验证 reflect 能从已存记忆综合出引用 PostgreSQL 或 us-east 的回答。这些测试通过-m requires_real_llm单独运行前提是本地已有可达的 Hindsight 服务器通过/health探活并且由服务器端 LLM 完成事实抽取无需额外的 provider key。进阶预召回注入系统提示词hindsight_composio还额外导出了memory_instructions()见 tools.py它在会话开始前同步执行一次 recall返回格式化好的记忆文本。由于 Composio 不会自动注入上下文你可以把返回的字符串自己拼进 Agent 的 system prompt实现开箱即带记忆的预热效果from hindsight_composio import memory_instructions prefix memory_instructions( bank_iduser-123, queryrelevant context about the user, budgetlow, max_results5, max_tokens4096, ) # 把 prefix 拼入 agent 的 system prompt其格式化输出形如Relevant memories:\n\n1. likes tea\n2. lives in NYC无结果或 recall 失败时静默返回空字符串不会阻塞 Agent 启动相关行为见 tests/test_tools.py 的TestMemoryInstructions。常见错误与规避忘记设置user_idbank 从会话的user_id解析。若既无user_id也无default_bank工具会直接抛出HindsightError。规避创建会话时始终指定user_id或为无用户场景配置default_bank。期待跨用户召回每个user_id映射到独立的 bank。用户 A 存储的记忆默认对用户 B 不可见——这种隔离正是设计目的。若确有共享需求可显式使用公共default_bank但注意这会打破隔离。指向错误的 Composio SDK本集成针对 Composio 0.13.x SDKfrom composio import Composio刻意排除了 API 不同的 1.0.0 重写版本。规避锁定依赖为composio0.13.1,1该约束已写入 pyproject.toml升级 Composio 大版本前先确认集成兼容性。注册了不想让 Agent 调用的工具三个工具默认全开。若 Agent 不应存储或综合用enable_retain/enable_recall/enable_reflect显式关闭避免 Agent 误用导致非预期行为或额外成本。FAQ必须用 Hindsight Cloud 吗不需要。自托管 Hindsight 服务器同样可用——把hindsight_api_urlhttp://localhost:8888或你的服务器地址传给register_hindsight_tools即可。自托管参考入口可查看 hindsight-api 与 hindsight-all 的说明。记忆的作用域是什么按会话user_id作用域隔离user_id映射到 Hindsightbank_id。一套注册好的工具集自动实现按用户隔离。Agent 会得到哪些工具默认是HINDSIGHT_RETAIN、HINDSIGHT_RECALL、HINDSIGHT_REFLECT三个通过enable_*标志可自由组合。Composio 的 experimental 自定义工具 API 有影响吗Composio 的自定义工具 API 目前是 experimental。本集成面向 Composio 0.13.x SDK 构建基于该 experimental 接口升级或更换 SDK 时需重新验证工具注册是否仍正常。下一步若想用托管后端可注册 Hindsight Cloud 直接开箱即用想完全掌控数据则可按自托管方式部署本仓库的 docker/standalone含Dockerfile与start-all.sh与 docker/docker-compose 提供了容器化启动方案深入理解记忆读写 APIretain 与 recall 属于 Hindsight 的核心操作相关实现可参考 hindsight-api 中的引擎代码与测试如 tests/test_recall_config.py、tests/test_recall_token_budget.py本集成的完整参数说明与快速开始示例可继续查阅 composio 集成 README源码级参考工具实现见 hindsight_composio/tools.py配置实现见 hindsight_composio/config.py单元测试见 tests/test_tools.py端到端测试见 tests/test_e2e.py【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考