使用 Hindsight 为 Microsoft Agent Framework 接入长期记忆hindsight-agent-framework 上下文提供者实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南讲解如何通过hindsight-agent-framework集成包以**上下文提供者Context Provider**的形式把 Hindsight 长期记忆接入 Microsoft Agent FrameworkSemantic Kernel 的继任者智能体在每次before_run钩子自动召回相关记忆注入上下文在after_run钩子自动留存本轮对话无需 MCP 服务、无需模型记得调用任何记忆工具。读完本指南你将掌握安装、连接 Cloud/自托管后端、用bank_id隔离记忆作用域、按需调整召回与留存参数以及一套可复现的验证流程。快速答案pip install hindsight-agent-framework设置HINDSIGHT_API_KEYCloud或传入hindsight_api_url自托管将HindsightProvider(bank_iduser-123)加入智能体的context_providers正常运行智能体——每次运行自动完成召回recall与留存retain验证后一次运行能回忆起前一次运行存储的内容为什么以 Context Provider 方式接入记忆Agent Framework 的每次运行都经过before_run/after_run生命周期钩子早期版本为invoking/invoked1.x 契约已更名。HindsightProvider正是挂在这两个钩子上召回before_run把用户输入作为查询发给 Hindsight将返回的记忆以## Memories指令块注入智能体 instructions留存after_run运行结束后将用户输入与智能体回复组合成转录文本写入 Hindsight bank。这样做的好处是既没有 MCP 服务器要维护也没有模型必须记得去调用的工具——记忆行为完全自动化且召回与留存都是 best-effort尽力而为记忆服务短暂抖动也绝不会阻塞智能体运行。从源码结构看该设计在 provider.py 中体现为对 Agent FrameworkContextProvider基类的真实继承class HindsightProvider(ContextProvider)测试 test_provider.py 专门断言isinstance(provider, ContextProvider)且source_id hindsight确保框架钩子 API 一旦漂移测试会立刻失败报警。前置条件开始之前请确认具备一个可以添加 context provider 的 Microsoft Agent Framework 智能体一个可达的 Hindsight 后端Hindsight Cloud 或自托管服务器Hindsight API KeyCloud或自托管服务器 URL。Step 1安装集成包pip install hindsight-agent-framework该包只新增一个HindsightProvider供你挂到智能体上。它不改变你构建或运行智能体的方式——只是包裹每次运行使记忆在运行前被召回、运行后被留存。包的完整源码、pyproject.toml与uv.lock位于仓库 hindsight-integrations/agent-framework 目录。Step 2把 Provider 指向 Hindsight方式 AHindsight Cloud一次性设置 API Keyexport HINDSIGHT_API_KEYyour-hindsight-key然后把 provider 挂到智能体上from agent_framework.openai import OpenAIChatClient from hindsight_agent_framework import HindsightProvider agent OpenAIChatClient().as_agent( nameassistant, instructionsYou are a helpful assistant., context_providers[HindsightProvider(bank_iduser-123)], ) session agent.create_session() await agent.run(Remember that I prefer vegetarian food., sessionsession) await agent.run(Suggest a recipe., sessionsession) # recalls the preference方式 B自托管 Hindsight 服务器先在本机跑起一个 Hindsight 服务pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-openai-key hindsight-api # http://localhost:8888再通过hindsight_api_url指向它HindsightProvider(bank_iduser-123, hindsight_api_urlhttp://localhost:8888)客户端解析规则源码级细节在 config.py 中默认 API 地址常量DEFAULT_HINDSIGHT_API_URL https://api.hindsight.vectorize.ioAPI Key 环境变量名HINDSIGHT_API_KEY。而 _client.py 中的resolve_client()按以下优先级解析显式传入的client实例最高优先级显式hindsight_api_url/api_key参数configure(...)设置的进程级全局配置默认 Cloud URL HINDSIGHT_API_KEY环境变量兜底仅设置环境变量也能工作。三个细节值得注意API Key 在构造客户端时是可选的——缺失时不会立刻报错只在真正发起请求时才失败客户端统一设置 30 秒超时TIMEOUT_DEFAULT 30.0由于 SDK 不提供单调用超时这个值作为所有 recall/retain/bank 操作的兜底客户端还会带上形如hindsight-agent-framework/{version}的 User-Agent。这些行为均有 test_config.py 中的test_resolve_uses_cloud_default_when_nothing_supplied、test_resolve_honors_env_key、test_explicit_args_win等用例逐项验证。Provider 如何调用记忆因为 provider 挂在 Agent Framework 的运行生命周期上它恰好工作在框架暴露的两个时点召回before_run以用户消息为查询调用 Hindsight 的arecall把相关记忆拼成## Memories块注入智能体 instructions。源码中该块文案为## Memories\nConsider the following memories when responding. Ignore any that are not relevant:见 provider.py并通过context.extend_instructions(self.source_id, block)注入。若没有召回结果则不注入保持 instructions 干净留存after_run调用aretain把本轮用户输入与智能体回复格式化为[role]\ntext转录文本写入 bank并携带contextagent-framework标签与metadata{source: agent-framework}。其中查询由 _build_query 构造优先取所有 role 为user的消息文本按行拼接若没有用户消息则退而取全部消息文本。留存的转录由 _format_transcript 渲染。两个自动化的防御性设计值得展开绝不阻塞智能体before_run/after_run内部所有 Hindsight 调用都包在try/except中失败只记logger.debug后静默返回。测试 test_provider.py 与test_retain_failure_is_silent明确验证RuntimeError(server down)也不会抛出避免记忆反馈回路召回的记忆是作为instructions而非 messages 注入的不会出现在留存转录里留存时还通过exclude_sources{self.source_id}防御性排除自身来源。测试test_no_feedback_loop_injected_memories_not_retained断言留存内容中绝不含## Memories或被召回的原文。记忆 Bank用bank_id划分作用域记忆存放在 Hindsight 的bank中作用域由bank_id决定——每个用户、每个智能体或每个会话一个 bank。上面的例子中bank_iduser-123即为该用户提供独立的记忆存储互不串扰。HindsightProvider除bank_id外还接受更多参数完整签名见 provider.py参数默认值说明clientNone预构建的 Hindsight 客户端传入则跳过 URL/Key/环境变量解析hindsight_api_urlCloud 默认地址Hindsight API 地址api_keyNoneAPI Key兜底读取HINDSIGHT_API_KEY环境变量budgetmid召回预算等级low/mid/highmax_tokens4096注入召回记忆的最大 token 数contextagent-framework留存记忆的来源标签source labeltagsNone留存时附加到记忆上的标签列表recall_tagsNone召回时按标签过滤recall_tags_matchany标签匹配模式any/all/any_strict/all_strictmissionNone银行使命设置后首次使用时以事实提取人格fact-extraction persona创建 bankauto_recallTrue每次运行前是否自动召回auto_retainTrue每次运行后是否自动留存source_idhindsight注入上下文使用的来源 id还可以用configure(...)设置进程级全局默认值让多个 provider 共享同一套连接与行为配置。configure(hindsight_api_url..., api_key..., budget..., max_tokens..., tags..., recall_tags..., recall_tags_match..., context..., mission..., verbose...)会返回一个HindsightAgentFrameworkConfig数据类默认值定义见 config.py配套的get_config()/reset_config()用于读取与重置全局配置。值得一提的还有mission与_ensure_bank()的组合当设置了mission时provider 在首次调用进程级一次性守卫_bank_initialized前会尝试acreate_bank(bank_id..., namebank_id, missionmission)创建带事实提取人格的 bank失败同样静默降级见 provider.py。验证记忆确实生效推荐按以下序列验证给智能体挂上HindsightProvider(bank_iduser-123)运行一次让智能体记下某个偏好或事实使用同一个bank_id再次运行询问之前记录的事实。例如第一次运行告诉智能体 Remember that I prefer vegetarian food.第二次运行问它 Suggest a recipe.如果第二次运行反映出了之前的偏好说明配置生效。由于留存已持久化到 bank即使跨越不同进程这一验证也成立。仓库中的端到端测试 test_e2e.py 正是这个流程的自动化版本test_retain_then_recall_roundtrip用随机bank_id先经after_run留存 my favorite programming language is Haskell 这类事实再在循环中反复触发before_run查询 What programming language do I like?直到指令里出现haskell为止最多等 60 秒留给服务端抽取时间。该测试通过requires_real_llm标记并在设置了HINDSIGHT_API_URL时才运行不会进入常规 CI 确定性测试桶。单元级验证则见 test_provider.pytest_before_run_injects_memories断言召回后 instructions 同时包含## Memories与记忆原文test_after_run_retains_user_and_assistant断言留存内容同时包含[user]与[assistant]两块文本。常见错误不同运行之间使用了不同的bank_id记忆按bank_id隔离。如果第二次运行用了另一个 bank它不可能召回第一次运行存储的内容。排查时先确认两次运行传入了完全相同的bank_id。指望模型去调用一个记忆工具不存在供模型调用的记忆工具。召回与留存自动发生在运行钩子上——你只需要把 provider 挂上即可不要在设计提示词时让模型记住调用记忆函数。忘记设置凭据Cloud 场景设置HINDSIGHT_API_KEY自托管场景给 provider 传hindsight_api_url必要时再加api_key。注意在 Cloud 模式下若未设置 Key客户端构造不会报错但首次真实请求会失败——建议在首次运行前就确认环境变量已导出。构建了 provider 却没有挂到智能体上provider 必须出现在智能体的context_providers列表中。只HindsightProvider(...)实例化而不加入列表before_run/after_run永远不会被框架调用也就没有任何召回或留存。FAQ必须使用 Hindsight Cloud 吗不需要。自托管服务器同样适用——运行hindsight-api并把hindsight_api_url传给 provider 即可两套方式在本指南 Step 2 中都有完整示例。这会改变我构建智能体的方式吗不会。你只需挂一个 context provider然后照常运行智能体。没有 MCP 服务器也没有模型必须调用的工具。记忆的作用域如何确定由传给HindsightProvider的bank_id决定——每个用户、每个智能体或每个会话一个 bank。可以单独关掉召回或留存吗可以。provider 分别提供auto_recall与auto_retain两个开关默认均为True可独立控制。对应的单元测试test_before_run_disabled_skips_recall与test_after_run_disabled_skips_retain验证了关闭后不会发起任何arecall/aretain调用。下一步通读集成包的 README.md 与 pyproject.toml了解依赖声明与开发命令uv run ruff check .、uv run pytest tests -v深入 provider.py 阅读钩子实现细节尤其是_build_query、_format_transcript与_ensure_bank查看 test_provider.py 与 test_config.py把这些用例当作集成行为的规格说明书如需更低层的召回 / 留存行为直接使用 Hindsight 客户端 SDK 的arecall/aretain/acreate_bank等接口provider 正是封装自这些调用本仓库还提供面向其他框架的同类集成如 ag2、autogen、langgraph、openai-agents、smolagents 等见 hindsight-integrations 目录可对照学习不同框架下记忆接入的等价实现。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考