使用 hindsight-agno 为 Agno Agent 接入 Hindsight 长期记忆：retain / recall / reflect 完整实战指南

使用 hindsight-agno 为 Agno Agent 接入 Hindsight 长期记忆retain / recall / reflect 完整实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读hindsight-agno是 Hindsight 官方提供的 Agno 集成包它基于 Agno 原生的Toolkit模式将 Hindsight 的长期记忆能力封装为三个可直接挂载到 Agent 上的工具retain_memory存储、recall_memory检索、reflect_on_memory综合推理。本指南将带你完成从安装、快速接入、bank 解析机制到全局配置的完整实操并结合仓库源码与测试用例深入说明客户端解析、bank 自动创建、工具注册与错误处理等底层实现让你能够为任何 Agno Agent 快速赋予跨会话的持久记忆能力。为什么需要给 Agno Agent 接记忆Agno原名 Phidata以Toolkit模式组织 Agent 能力Mem0Tools就是这一模式的代表。hindsight-agno采用完全相同的设计哲学——继承Toolkit基类并注册工具因此接入成本极低与 Agno 生态天然融合。与单纯的工具不同Hindsight 提供的是「会学习的记忆」存储retain、检索recall、反思reflect三阶段闭环。集成包将这三阶段分别封装为独立的 agent-callable 工具Agent 在对话中可以主动决定何时写入、何时查询、何时综合——这正是长期记忆 Agent 的核心能力模型。特性总览根据集成包官方说明README 与关联文档该集成提供以下核心能力原生 Toolkit继承 AgnoToolkit基类与Mem0Tools同模式tools.py 中HindsightTools(Toolkit)直接向super().__init__传入工具列表与内置指令。记忆指令注入memory_instructions()在构建 Agent 时预检索记忆并注入instructions[...]。三大记忆工具retain / recall / reflect 可按需任意组合enable_*开关。灵活的 Bank 解析静态 bank ID、RunContext.user_id、自定义 resolver 三级优先级。简洁配置全局configure()一次配置或直接传入 client。安装集成包以独立发行版发布安装命令pip install hindsight-agno包名与依赖在 pyproject.toml 中定义requires-python 3.10支持 Python 3.10 / 3.11 / 3.12硬依赖为agno与hindsight-client0.4.0即底层 SDK 客户端from hindsight_client import Hindsight。安装后可用import hindsight_agno验证__version__当前为0.1.0见 __init__.py。快速开始Hindsight Cloud 接入最省事的方式是使用托管的 Hindsight Cloud 服务注册获取 API Keyhsk_...后即可直接接入无需自建基础设施from agno.agent import Agent from agno.models.openai import OpenAIChat from hindsight_agno import HindsightTools agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., # 或设置 HINDSIGHT_API_KEY 环境变量 )], ) agent.print_response(Remember that I prefer dark mode) agent.print_response(What are my preferences?)两轮对话完成后Agent 已具备三个可调用工具retain_memory— 将信息写入长期记忆recall_memory— 从长期记忆中检索相关事实reflect_on_memory— 基于记忆综合出有推理依据的回答。agent.print_response会触发工具调用闭环第一句触发retain_memory写入「偏好深色模式」第二句触发recall_memory检索并回答。自托管本地开发如果你通过./scripts/dev/start-api.sh仓库中的 启动脚本在本地运行 Hindsight API把 URL 换成http://localhost:8888即可tools[HindsightTools( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, )]完整的自托管安装说明PostgreSQL 14、pgvector/pgvectorscale/vchord/scann 等向量扩展、pg0 嵌入式数据库、生产环境选型参见 安装指南。自托管时同样可以通过HINDSIGHT_API_KEY环境变量提供鉴权。三大记忆工具的实现细节从源码层面看三个工具都由 tools.py 中的同名方法实现每个方法都接收 Agno 的RunContext与必要的参数retain_memory(run_context, content)通过_resolve_bank_id解析目标 bank调用_ensure_bank自动创建 bank若该 session 尚未创建携带可选的tags调用client.retain(bank_id, content, tags...)成功返回字符串Memory stored successfully.。recall_memory(run_context, query)解析 bank调用client.recall(bank_id, query, budget, max_tokens, tags..., tags_match...)有结果时输出编号列表1. ...、2. ...无结果时返回No relevant memories found.。reflect_on_memory(run_context, query)解析 bank调用client.reflect(bank_id, query, budget)返回综合后的文本若文本为空则回退为No relevant memories found.。值得注意的实现细节均有对应测试佐证见 test_tools.pybank 自动创建只发生在 retain_ensure_bank只在retain_memory中被调用recall 与 reflect 不会触发创建test_recall_does_not_create_bank、test_reflect_does_not_create_bank创建失败被静默容忍若 bank 已存在导致create_bank抛错集成包会吞掉异常并继续写入test_bank_creation_failure_is_swallowed同时把该 bank 标记为已创建避免重复尝试test_bank_creation_failure_marks_as_created每个 Toolkit 实例独立跟踪已创建 bank 集合_created_banks: set[str]多实例互不干扰统一错误包装底层调用失败会被包装为HindsightError定义于 errors.py并保留原始异常链__cause__便于排查。通过 memory_instructions 预注入记忆除按需检索外集成包还提供了「预检索注入」模式在构建 Agent 时同步执行一次 recall把相关记忆格式化为字符串注入instructions[...]让模型在每一轮对话开始前就看到相关上下文from hindsight_agno import HindsightTools, memory_instructions agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, )], instructions[memory_instructions( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, )], )memory_instructions()的源码实现tools.py有四个值得注意的行为使用同步client.recall而非异步变体test_uses_sync_recall结果按max_results默认 5截断并以prefix默认Relevant memories:\n开头、逐条编号格式化无结果时返回空字符串不会产生冗余 prompt 内容异常被静默吞掉即使 recall 失败也返回空字符串绝不阻塞 Agent 启动test_error_does_not_raise——这是刻意的容错设计记忆注入失败不应影响主流程。按需选择工具不是所有场景都需要三个工具。比如只想存储与检索、不需要综合推理可以关闭 reflecttools [HindsightTools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, enable_retainTrue, enable_recallTrue, enable_reflectFalse, # 省略 reflect )]底层实现tools.py按enable_*标志动态构建工具列表再传给Toolkit.__init__。测试用例覆盖了全部组合三个全开len(functions) 3、仅 retain、仅 recall、仅 reflect、任意两个、以及全部关闭len(functions) 0见 test_tools.py。Bank 解析机制Hindsight 以「bank」记忆库为隔离单元。集成包按以下顺序解析 bank ID源码见 tools.pybank_resolver— 自定义可调用对象(RunContext) - str优先级最高bank_id— 构造时传入的静态 bank IDrun_context.user_id— 自动使用用户 ID 作为 bank实现按用户隔离以上都不可用时抛出HindsightError(No bank_id available...)。# 方式一按 RunContext 的 user_id 自动分库 agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools(hindsight_api_urlhttps://api.hindsight.vectorize.io)], user_iduser-123, # 作为 bank_id 使用 ) # 方式二自定义 resolver例如按团队分库 def resolve_bank(ctx): return fteam-{ctx.user_id} agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools( bank_resolverresolve_bank, hindsight_api_urlhttps://api.hindsight.vectorize.io, )], )测试用例如实印证了优先级关系test_tools.pytest_bank_resolver_takes_priority_over_bank_idresolver 与静态 bank_id 同时存在时 resolver 胜出test_static_bank_id_takes_priority_over_user_id静态 bank_id 优先于run_context.user_idtest_missing_bank_id_raises_error三者皆无时抛HindsightErrortest_bank_id_consistent_across_tools同一 context 下三个工具解析出相同的 bank保证读写一致。若使用动态 resolver每次工具调用都会重新计算 bank每个新 bank 在首次 retain 时各自动创建一次test_different_bank_ids_created_separately验证了 alice/bob 各自只创建一次。全局配置 configure()当应用中有多个 Agent、多个 Toolkit 时逐个传连接参数非常繁琐。集成包提供了进程级全局配置from hindsight_agno import configure, HindsightTools configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, 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, # 标签匹配模式any/all/any_strict/all_strict ) # 之后创建 Toolkit 无需再传连接参数 tools [HindsightTools(bank_iduser-123)]配置实现在 config.pyconfigure()返回并保存HindsightAgnoConfig单例后续HindsightTools、memory_instructions通过get_config()读取API Key 解析顺序显式api_key参数 HINDSIGHT_API_KEY环境变量test_configure_explicit_overrides_envURL 默认值hindsight_api_url缺省时回退到https://api.hindsight.vectorize.ioDEFAULT_HINDSIGHT_API_URL提供reset_config()用于测试或动态重配test_reset_config、test_reset_is_idempotent。客户端解析与参数优先级Toolkit 构造时_resolve_clienttools.py按「显式 client 显式 URL/Key 全局配置」解析底层Hindsight客户端传入client时完全忽略URL 与 Keytest_explicit_client_ignores_url_and_key否则以base_url、timeout30.0、user_agenthindsight-agno/version构造客户端有 Key 时附加api_key显式 URL / Key 会覆盖全局配置test_explicit_url_overrides_config、test_explicit_api_key_overrides_config若 URL 与配置皆无抛HindsightError(No Hindsight API URL configured...)。注意一个继承自默认参数的细节budget、max_tokens等「非 None 默认值」参数在构造时采用or回退逻辑因此构造函数默认值如budgetmid会覆盖全局配置中的值——若想让全局配置生效需显式传参test_constructor_defaults_override_config_for_budget而tags、recall_tags采用is not None判断未显式传入时会正确继承全局配置test_config_defaults_for_tags。配置参考HindsightTools()参数默认值说明bank_idNone静态 Hindsight 记忆 bank IDbank_resolverNone可调用对象(RunContext) - str用于动态解析 bank IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI Key未提供 client 时使用budgetmidRecall/reflect 预算级别low/mid/highmax_tokens4096Recall 结果的最大 token 数tagsNone存储记忆时应用的标签recall_tagsNone检索时用于过滤的标签recall_tags_matchany标签匹配模式enable_retainTrue是否注册 retain存储工具enable_recallTrue是否注册 recall检索工具enable_reflectTrue是否注册 reflect综合工具memory_instructions()参数默认值说明bank_id必填Hindsight 记忆 bank IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI Key未提供 client 时使用queryrelevant context about the user用于记忆注入的 recall 查询budgetlowRecall 预算级别max_results5注入的最大记忆条数max_tokens4096Recall 结果的最大 token 数prefixRelevant memories:\n记忆列表前的引导文本tagsNone过滤 recall 结果的标签tags_matchany标签匹配模式configure()参数默认值说明hindsight_api_urlHindsight Cloudhttps://api.hindsight.vectorize.ioHindsight API URLapi_keyHINDSIGHT_API_KEY环境变量鉴权 API Keybudgetmid默认 recall 预算级别max_tokens4096默认 recall 最大 token 数tagsNoneretain 操作的默认标签recall_tagsNonerecall 过滤的默认标签recall_tags_matchany默认标签匹配模式verboseFalse启用详细日志标签匹配模式说明recall_tags_match/tags_match支持any、all、any_strict、all_strict四种模式对应底层hindsight-client的标签过滤语义。仅在设置tags/recall_tags时随请求一起下发见 tools.py未配置标签时请求中不会携带tags与tags_match参数test_recall_no_tags_key_when_none。错误处理约定集成包定义了统一的HindsightError继承Exception见 errors.py错误处理遵循两条原则工具调用失败会被包装retain / recall / reflect 的底层异常统一包装为HindsightError(Retain failed: ...)等并保留原始异常链便于诊断test_retain_error_chains_original_exception等来自 bank 解析的HindsightError不会被二次包装保持错误信息原样向上传播test_retain_preserves_hindsight_errormemory_instructions()全量吞错其内部异常一律返回空字符串保证 Agent 初始化不被记忆检索阻塞。运行前提与依赖使用本集成前请确认满足以下条件Python 3.10已安装agnohindsight-client 0.4.0由pip install hindsight-agno自动带入存在一个可访问的 Hindsight API 服务——托管 Cloud默认 URLhttps://api.hindsight.vectorize.io或本地自托管实例如http://localhost:8888参见 安装指南 与 本地启动脚本。小结hindsight-agno把 Hindsight 的「存储—检索—反思」记忆闭环以最贴合 Agno 生态的方式接入继承Toolkit、动态注册工具、三级 bank 解析、全局配置与预注入指令再加上自动建库与容错设计开发者只需十几行代码就能让 Agent 拥有跨会话的持久记忆。源码实现tools.py、config.py与 1700 余行测试用例test_tools.py、test_config.py为上述行为提供了完整佐证你可以直接基于它们继续扩展自己的记忆型 Agent 应用。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考