Hindsight × Agno 持久记忆实战：用 retain / recall / reflect 给 Agno Agent 装上跨会话长期记忆

Hindsight × Agno 持久记忆实战用 retain / recall / reflect 给 Agno Agent 装上跨会话长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读Agno 框架擅长多模态输入、多 Agent 协作与结构化输出但每次agent.run()都以空上下文窗口开始跨会话记忆完全缺失。hindsight-agno以 Agno 原生的Toolkit模式接入 Hindsight通过retain_memory存储、recall_memory检索、reflect_on_memory综合三个工具与memory_instructions指令注入两路机制为 Agent 提供可跨天、跨周检索的长期记忆。读完本文你将掌握从本地启动 Hindsight、三步接入 Agno Agent到按用户隔离记忆库、裁剪工具集、全局配置与避坑的完整实战方案。TL;DRAgno 没有内置持久记忆每次agent.run()都从零开始。hindsight-agno提供HindsightTools——一个原生 AgnoToolkit内含 retain、recall、reflect 三个记忆工具。三行代码完成接入安装包、创建HindsightTools、传给Agent。memory_instructions()在每次运行时把相关记忆预载入Agent(instructions[...])让 Agent 开局自带上下文无需工具调用。通过user_id或自定义bank_resolver按用户隔离记忆库自动生效。不想自建服务可直接使用 Hindsight Cloud两行配置即可运行。问题Agno 没有持久记忆Agno 是一个能力完整的 Agent 框架Toolkit模式让添加工具变得简单团队协作原语支持多 Agent 工作流结构化输出与流式响应开箱即用。但 Agno 本身不携带任何记忆层。每次agent.run()都从空白开始Agent 不知道用户上次会话说过什么不知道他们的偏好、反复出现的问题也不知道它自己此前研究过什么。今天用户告诉 Agent 的重要信息明天就消失了。你确实可以把messages传给 Agent 来延续单次运行内的对话但那是会话历史session history不是记忆。会话历史不抽取结构化事实、随每一轮对话线性膨胀、不泛化也不去重进程一退出便全部消失。真正的 Agent 记忆应该是这样的从对话中抽取离散事实并持久化存储构建实体与关系的知识图谱通过语义检索跨天、跨周、跨月召回相关上下文从零散累积的知识中综合出连贯的回答这正是 Hindsight 提供的能力。hindsight-agno包把它直接接入 Agno 的Toolkit体系你不需要自己构建其中任何一环。工作原理工具 指令两条通路hindsight-agno在 Agno 的两个点上接入记忆Agno Agent |-- tools[HindsightTools(...)] | |-- retain_memory - 把事实存入长期记忆 | |-- recall_memory - 检索记忆中的相关事实 | |-- reflect_on_memory - 基于记忆综合出答案 | |-- instructions[memory_instructions(...)] |-- 自动把相关记忆注入系统提示词**工具Tools**让 Agent 在对话过程中显式地存取记忆**指令Instructions**在 Agent 开始回答之前就把相关记忆注入系统提示词无需任何工具调用。HindsightTools直接继承 Agno 的Toolkit基类与 Agno 生态中Mem0Tools采用的模式一致。你把它加进tools[...]就像添加任何其他 Agno 工具包一样。从源码可以看到它在构造时通过super().__init__(namehindsight_tools, toolstools, instructions_TOOL_INSTRUCTIONS, **kwargs)注册工具并附带一段内置指令引导模型“主动存储用户可能后续有用信息并在回答前先查记忆”——见 tools.py。理解每个工具的职责与触发时机很重要retain_memory当 Agent 遇到值得保留的信息时调用——明确的偏好、一个决定、关于用户或项目的事实。recall_memory返回过去会话中的匹配事实列表。Agent 需要查资料时调用它。reflect_on_memory把记忆综合成连贯答案。recall_memory返回列表reflect_on_memory则跨所有相关记忆进行推理、产出一个回答。对“你对我的工程风格了解多少”这类问题它比原始事实检索更合适。这三个工具的方法签名都是(run_context, content | query) - strdocstring 会直接成为传给 LLM 的工具描述测试TestToolDocstrings专门验证了这一点。底层分别调用hindsight_client的retain、recall、reflectAPI并把非HindsightError的异常统一包装为HindsightError抛出保留原始异常的__cause__链——见 tools.py 与 errors.py。搭建 Agno 持久记忆第 1 步启动 Hindsightpip install hindsight-allexport HINDSIGHT_API_LLM_API_KEYYOUR_OPENAI_KEY hindsight-api这会在本地http://localhost:8888启动 Hindsight。唯一的外部依赖是用于实体抽取的 LLM API Key。不想自托管直接用 Hindsight Cloud跳过这一步。第 2 步安装 Agno 集成pip install hindsight-agno agno该包要求 Python 3.10依赖agno与hindsight-client0.4.0当前仓库版本为 0.4.19见 pyproject.toml。第 3 步把HindsightTools加进 Agentfrom 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_urlhttp://localhost:8888, )], )这就是完整接入。Agent 现在拥有三个工具retain_memory把信息存入长期记忆recall_memory检索长期记忆中的相关事实reflect_on_memory从累积记忆中综合出有依据的回答关于bank_id有个细节值得了解当调用retain_memory时HindsightTools会先通过_ensure_bank()尝试自动创建该记忆库每个 Toolkit 实例内只创建一次即便创建失败也会被容忍并记为已创建因为“库可能已存在”而recall/reflect不会触发创建——见 tools.py 及测试TestEnsureBank。第 4 步验证跨会话记忆# 第一次会话Agent 存入上下文 agent.print_response( Remember that I prefer functional programming patterns and I am building a data pipeline in Python. ) # 后续会话Agent 召回上下文 agent.print_response(What approach should I take for error handling?)重启进程再跑第二次调用Agent 依然记得。Agno 的持久记忆存储在 Hindsight 里而不是 Agent 的上下文窗口中。第 5 步用memory_instructions自动注入记忆如果希望每次运行开始时自动注入记忆使用memory_instructionsfrom hindsight_agno import HindsightTools, memory_instructions agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, )], instructions[memory_instructions( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, )], )每次agent.run()时memory_instructions都会调用 Hindsight 的 recall API把相关记忆注入系统提示词。Agent 开局自带上下文无需工具调用。可以自定义检索查询、结果条数与前缀memory_instructions( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, queryuser preferences, history, and context, max_results10, prefixHere is what you know about this user:\n, )如果召回结果为空或调用失败memory_instructions返回空字符串Agent 正常运行不受影响。这一点在源码中体现为对 recall 调用全程try/except并静默返回见 tools.py测试TestMemoryInstructions也覆盖了“错误不抛异常”这一行为。需要留意的是若连客户端都解析不出来未配置任何 URL则会抛出HindsightError而不是静默。进阶配置按用户隔离记忆库面向多用户的 AgentHindsightTools会动态解析 bank ID。解析顺序与源码_resolve_bank_id()一致见 tools.pybank_resolver可调用对象(RunContext) - str用于自定义逻辑bank_id构造时传入的静态 bank IDRunContext.user_id自动按用户建库# 从 RunContext 取 user_id 自动建库 agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools(hindsight_api_urlhttp://localhost:8888)], user_iduser-123, ) # 基于团队的自定义解析器 def resolve_bank(ctx): return fteam-{ctx.user_id.split(-)[0]} agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools( bank_resolverresolve_bank, hindsight_api_urlhttp://localhost:8888, )], )优先级测试TestBankIdResolution验证了bank_resolver优先于静态bank_id、静态bank_id优先于user_id若三者都缺失则抛出HindsightError(No bank_id available...)。选择要包含的记忆工具# 只读 Agent只召回与综合不存储 tools HindsightTools( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, enable_retainFalse, enable_recallTrue, enable_reflectTrue, )这在多 Agent 场景很有用一个 Agent 负责积累知识另一个 Agent 基于知识回答问题。enable_*三个开关对应构造时只注册被启用的工具测试TestHindsightToolsInit验证了从“仅 retain”到“全部禁用0 个工具”的各种组合。全局配置当多个 Agent 共享同一套连接参数时可全局配置一次from hindsight_agno import configure, HindsightTools configure( hindsight_api_urlhttp://localhost:8888, api_keyyour-api-key, budgetmid, max_tokens4096, ) agent1_tools HindsightTools(bank_iduser-alice) agent2_tools HindsightTools(bank_iduser-bob)configure()维护一份进程级全局配置见 config.pyHindsightTools与memory_instructions在解析客户端时都会回退到它显式传入的client/hindsight_api_url/api_key优先于全局配置。注意配置在工具构造时被捕获之后修改全局配置不会影响已创建的 Toolkit测试TestConfigToolkitInteraction验证了这一点。Hindsight Cloud 配置from hindsight_agno import configure configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_your_token, )无需管理守护进程无需本地 Postgres。抽取、索引与检索全部由云端完成。未显式传api_key时configure()会回退读取HINDSIGHT_API_KEY环境变量未传hindsight_api_url时默认使用云端地址见 config.py 与TestConfigure测试。完整可运行示例from agno.agent import Agent from agno.models.openai import OpenAIChat from hindsight_agno import HindsightTools, memory_instructions BANK_ID demo-user HINDSIGHT_URL http://localhost:8888 agent Agent( modelOpenAIChat(idgpt-4o-mini), tools[HindsightTools( bank_idBANK_ID, hindsight_api_urlHINDSIGHT_URL, )], instructions[memory_instructions( bank_idBANK_ID, hindsight_api_urlHINDSIGHT_URL, )], ) print(--- Run 1: Teaching the agent ---) agent.print_response( Remember: I am a backend engineer. I use Python and Rust. I prefer small, composable libraries over large frameworks. ) print(\n--- Run 2: Agent recalls context ---) agent.print_response(Recommend a web framework for my next project.) print(\n--- Run 3: Agent synthesizes ---) agent.print_response(What do you know about my engineering philosophy?)运行两遍。Agent 会记得第一次执行的全部内容。何时不该用 Agno 持久记忆以下场景请跳过记忆层一次性 Agent永远不会与同一用户交互两次、无状态 API 处理器每个请求完全独立、或需要完全掌控进入提示词内容的情况。这些场景下直接使用 Hindsight Python 客户端而非 Agno 集成会更合适。与其他方案的对比方案优势劣势最适合Hindsight Agno多策略检索语义 BM25 图 时间、结构化事实抽取、综合回答需要 Hindsight 服务端或云需要深度记忆的多会话 Agent手动传 messagesAgno 内置、零依赖不持久、随上下文窗口膨胀短的单会话对话常见陷阱bank ID 冲突。每个bank_id都是一个独立的记忆库。请为每个用户、每个 Agent 或每个项目使用唯一的 bank ID防止无关 Agent 之间记忆串库。记忆指令延迟。memory_instructions在每次agent.run()时都会发起一次 recall API 调用。对延迟敏感的应用使用budgetlow和较小的max_results。召回耗时约 50–200ms取决于库大小与网络状况。也正因如此memory_instructions在构造时执行的是同步client.recall测试test_uses_sync_recall专门断言了这一点。重复记忆。Hindsight 在事实层面会去重但如果你在系统提示词里给 Agent 设定“何时该存新事实”的引导效果会更好。另外可以利用tags/recall_tags匹配模式any/all/any_strict/all_strict在存储与检索两侧做标签过滤更精细地控制记忆边界。参数速查HindsightTools()默认值以源码与 README 为准详见 README.md参数默认值说明bank_idNone静态记忆库 IDbank_resolverNone可调用(RunContext) - str动态解析 bank IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI Key未提供 client 时使用budgetmid召回/综合的预算级别low/mid/highmax_tokens4096召回结果的最大 token 数tagsNone存储记忆时附加的标签recall_tagsNone检索时用于过滤的标签recall_tags_matchany标签匹配模式enable_retainTrue是否注册 retain存储工具enable_recallTrue是否注册 recall检索工具enable_reflectTrue是否注册 reflect综合工具memory_instructions()参数默认值说明bank_id必填记忆库 IDclientNone预配置客户端优先hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI Key未提供 client 时使用queryrelevant context about the user召回查询budgetlow召回预算级别max_results5最多注入的记忆条数max_tokens4096召回结果最大 token 数prefixRelevant memories:\n记忆列表前的前缀文本tagsNone过滤召回结果的标签tags_matchany标签匹配模式configure()参数默认值说明hindsight_api_urlhttps://api.hindsight.vectorize.ioHindsight API URLapi_key环境变量HINDSIGHT_API_KEY认证 Keybudgetmid默认召回预算max_tokens4096默认召回最大 token 数tagsNoneretain 操作的默认标签recall_tagsNone召回过滤的默认标签recall_tags_matchany默认标签匹配模式verboseFalse开启详细日志回顾Agno 默认接入 Hindsight 后跨会话记忆无自动记忆接入成本无pip install hindsight-agno召回机制不可用工具或指令触发的语义检索按用户隔离无通过user_id或bank_resolver托管方式N/A本地或 Hindsight Cloud深入阅读集成配置参考docs-integrations/agno.md核心实现tools.py工具注册、bank 解析、错误包装、config.py全局配置测试用例test_tools.py 与 test_config.py 覆盖了 bank 解析优先级、工具开关组合、错误传播、memory_instructions容错等关键行为本地试跑pip install hindsight-all hindsight-agno agno按上文“完整可运行示例”运行即可【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考