Pydantic AI 接入 Hindsight 实现持久化记忆异步记忆工具与自动指令注入实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南围绕 Hindsight 提供的hindsight-pydantic-ai集成包讲解如何为 Pydantic AI Agent 注入跨会话的长期记忆通过create_hindsight_tools()暴露 retain/recall/reflect 三个异步记忆工具并通过memory_instructions()在每次运行前自动召回相关记忆注入系统提示词。读完本文你将掌握从安装、连接、Bank 策略设计到记忆生效验证的完整落地路径并理解其底层实现与配置优先级。为什么这套方案成立Pydantic AI 将tools工具与instructions指令作为一等公民概念提供给 Agent。Hindsight 的集成恰好同时覆盖这两者记忆工具create_hindsight_tools给 Agent 显式的记忆操作能力让模型自主决定何时调用记忆指令memory_instructions在每轮运行开始前自动把相关记忆注入上下文属于自动召回。两者结合就能同时实现自动记忆使用与Agent 驱动的显式记忆操作既不需要线程池 hack也不需要手写召回逻辑。从源码看该集成是端到端异步原生的——retain、recall、reflect 全部走异步路径aretain/arecall/areflect在 async 生产服务中接入时不需要任何同步包装参见 tools.py。前置条件一个可正常运行的 Pydantic AI AgentPython 环境已安装hindsight-pydantic-ai一个跨运行保持稳定的 Bank ID 策略同一用户或同一项目在不同会话中必须复用相同的 Bank ID。Step 1安装集成包pip install hindsight-pydantic-ai该包是轻量设计根据 pyproject.toml 与 README.md它只依赖pydantic-ai-slim1.0.0避免拉入全部模型提供商与hindsight-client0.4.0运行要求 Python 3.10采用 MIT 许可证。Step 2连接 Pydantic AI 与 Hindsight连接 Hindsight 后端有两种方式核心都是构造一个Hindsight客户端方式一Hindsight Cloud推荐免自托管from hindsight_client import Hindsight client Hindsight(base_urlhttps://api.hindsight.vectorize.io, api_keyhsk_...)方式二本地自托管如果使用仓库自带的启动脚本在本地运行 Hindsight例如./scripts/dev/start-api.sh只需把 URL 指向本地端口client Hindsight(base_urlhttp://localhost:8888)也可以调用一次configure()建立全局配置之后创建工具时无需反复传 client详见下文全局配置章节。Step 3将记忆接入 Pydantic AI 运行时最干净的模式是给 Agent 挂上 Hindsight 工具再通过memory_instructions()让相关记忆在每次运行前自动注入from hindsight_client import Hindsight from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions from pydantic_ai import Agent client Hindsight(base_urlhttps://api.hindsight.vectorize.io, api_keyhsk_...) agent Agent( openai:gpt-4o, toolscreate_hindsight_tools(clientclient, bank_iduser-123), instructions[memory_instructions(clientclient, bank_iduser-123)], ) result await agent.run(What do you remember about my preferences?) print(result.output)上述代码执行后Agent 会获得三个可调用的记忆工具源码定义见 tools.py工具名职责对应底层 APIhindsight_retain将信息写入长期记忆事实、用户偏好、决策、规则等client.aretain()hindsight_recall搜索长期记忆中与查询相关的信息返回编号列表client.arecall()hindsight_reflect基于记忆合成有条理、有推理的回答而非返回原始事实client.areflect()三个工具都是takes_ctxFalse的异步闭包直接捕获已解析的 client因此不需要修改RunContext或 deps。默认三个工具全部创建也可以通过include_retain/include_recall/include_reflect任意裁剪组合例如省略 reflecttools create_hindsight_tools( clientclient, bank_iduser-123, include_retainTrue, include_recallTrue, include_reflectFalse, # Omit reflect )而memory_instructions()返回的是一个兼容Agent(instructions[...])的异步可调用对象tools.py。它在每次agent.run()时都会被重新求值自动调用arecall()召回记忆以prefix默认Relevant memories:\n为前缀拼成编号列表注入系统提示词——因此即使复用了message_history注入的记忆也始终是最新状态。两种变体按需取舍只要工具、不要自动注入Agent 自己决定何时用记忆agent Agent( openai:gpt-4o, toolscreate_hindsight_tools(clientclient, bank_iduser-123), )只要自动注入、不给工具agent Agent( openai:gpt-4o, instructions[memory_instructions(clientclient, bank_iduser-123)], )Step 4选择合适的 Bank 策略Bank记忆库是 Hindsight 组织记忆的命名空间所有 retain/recall 操作都以bank_id为锚点按用户建 Bank每用户一个对跟随单个用户的助手类应用是最安全的默认选择按工作流/项目建 Bank当同一个用户操作多个互不相关的系统时更合理绝对避免每次请求轮换 Bank ID那会让 Agent 看起来无状态即使集成本身正确记忆也永远无法被后续会话命中。此外注意工具与指令必须使用同一个 Bank ID否则会出现存进 A 库、从 B 库查的错位。Step 5验证记忆确实生效按以下步骤做端到端验证运行一次 Agent让它记住一条偏好或操作规则触发 retain使用相同的 Bank ID再次运行向它询问该细节检查回答是否在任何显式工具调用之前就已反映先前的记忆即自动注入生效如果未生效检查指令输出内容并确认 recall 使用的是预期的 Bank。判定标准第二次运行能答出第一次运行存下的细节说明配置成功。如果不行开启调试日志、核对配置的 Bank ID并确认 retain 调用确实完成。值得说明的是memory_instructions()具备故障隔离设计源码中指令函数对召回异常采取静默处理直接返回空字符串见 tools.py确保记忆后端短暂不可用时不会阻塞 Agent 主流程而显式工具调用失败则会抛出HindsightError让 Agent 感知错误测试用例见 test_tools.py 中的TestRetainTool/TestRecallTool/TestReflectTool。全局配置与单次覆盖client 解析与参数优先级如果不想在每个调用点都传 client可以先调用configure()做一次全局配置实现见 config.pyfrom hindsight_pydantic_ai import configure, create_hindsight_tools configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, # Hindsight Cloud (default) 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 ) # 之后无需传 client直接使用全局配置 tools create_hindsight_tools(bank_iduser-123)api_key缺省时会回退读取HINDSIGHT_API_KEY环境变量见 config.py。参数优先级规则源码见 tools.py 的_resolve_client显式传入的client优先直接使用不再创建新客户端未传 client 时依次回退hindsight_api_url/api_key显式参数 → 全局configure()配置 → 内置默认值若最终仍无 API URL抛出HindsightError(No Hindsight API URL configured...)未显式传入的budget/max_tokens/tags/recall_tags/recall_tags_match会回退到全局配置的默认值。构造函数参数覆盖全局配置tools create_hindsight_tools( bank_iduser-123, budgethigh, # 覆盖全局 budget max_tokens8192, # 覆盖全局 max_tokens tags[session:abc], # 覆盖全局 tags )create_hindsight_tools()参数参考参数默认值说明bank_id必填Hindsight 记忆库 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI 密钥未提供 client 时使用budgetmid召回/反思预算级别low/mid/highmax_tokens4096召回结果最大 token 数tagsNone存储记忆时附加的标签recall_tagsNone搜索时用于过滤的标签recall_tags_matchany标签匹配模式include_retainTrue是否包含 retain存储工具include_recallTrue是否包含 recall搜索工具include_reflectTrue是否包含 reflect合成工具memory_instructions()参数参考参数默认值说明bank_id必填Hindsight 记忆库 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI 密钥未提供 client 时使用queryrelevant context about the user记忆注入的召回查询budgetlow召回预算级别max_results5最多注入的记忆条数max_tokens4096召回结果最大 token 数prefixRelevant memories:\n记忆列表前的前缀文本tagsNone过滤召回结果的标签tags_matchany标签匹配模式configure()参数参考参数默认值说明hindsight_api_urlHindsight Cloudhttps://api.hindsight.vectorize.ioHindsight API URLapi_keyHINDSIGHT_API_KEY环境变量认证密钥budgetmid默认召回预算级别max_tokens4096默认召回最大 token 数tagsNone默认 retain 附加标签recall_tagsNone默认召回过滤标签recall_tags_matchany默认标签匹配模式verboseFalse开启详细日志按标签过滤召回记忆集成同时支持recall_tags与recall_tags_match用于收窄记忆作用域。例如在memory_instructions()中只注入带scope:global标签的记忆instructions_fn memory_instructions( clientclient, bank_iduser-123, queryrelevant context about the user, # 召回查询 budgetlow, # 保持低延迟 max_results5, # 限制注入条数 max_tokens4096, # 召回 token 上限 prefixRelevant memories:\n, # 列表前缀 tags[scope:global], # 标签过滤 tags_matchany, # 标签匹配模式 )标签过滤逻辑会原样透传给底层arecall()的tags与tags_match参数见 tools.pytags_match支持any/all/any_strict/all_strict四种匹配模式测试用例对标签传递的正确性有专门覆盖见 test_tools.py 的test_recall_passes_tags与test_passes_tags。常见错误加了工具却忘记加memory_instructions()导致本应自动召回的上下文没有注入工具和指令使用了不同的 Bank ID造成存取错位在某处覆盖了全局配置却忘了每次调用的实参优先级更高per call arguments win最终行为与预期不符。FAQQ1工具和记忆指令必须同时使用吗不需要。想要自动注入 显式记忆操作就两者都用如果某种设计更适合只用一个完全可以只用其中一个。测试test_tools.py也验证了三个工具可任意组合裁剪包括全部排除。Q2为什么异步支持在这里很重要因为 retain/recall/reflect 全部是异步原生调用aretain/arecall/areflect在 async 应用中接入时无需为记忆调用包一层丑陋的同步包装sync wrapper保持集成简单。Q3能否按标签过滤召回的记忆可以。集成支持recall_tags与recall_tags_match可以按标签收窄记忆作用域详见上文按标签过滤召回记忆章节。下一步若需要托管式记忆后端可从 Hindsight Cloud 起步若想自托管参考仓库中 Hindsight 安装/启动文档本地启动 API 后客户端指向http://localhost:8888完整的集成说明可继续阅读 hindsight-integrations/pydantic-ai/README.md 与 docs-integrations/pydantic-ai.md想要理解 retain/recall/reflect 在服务端的完整语义事实抽取、知识图谱、四种并行搜索策略等可阅读 Hindsight 快速开始文档 的 Whats Happening 章节需要确认底层客户端接口时可查看hindsight-client中aretain/arecall/areflect的实现与对应 API 定义想对比其他 Agent 框架的持久记忆接入方式可浏览仓库内 hindsight-integrations 目录下其他框架如 agno、langgraph、llamaindex 等的同构集成。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pydantic AI 接入 Hindsight 实现持久化记忆：异步记忆工具与自动指令注入实战指南
Pydantic AI 接入 Hindsight 实现持久化记忆异步记忆工具与自动指令注入实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南围绕 Hindsight 提供的hindsight-pydantic-ai集成包讲解如何为 Pydantic AI Agent 注入跨会话的长期记忆通过create_hindsight_tools()暴露 retain/recall/reflect 三个异步记忆工具并通过memory_instructions()在每次运行前自动召回相关记忆注入系统提示词。读完本文你将掌握从安装、连接、Bank 策略设计到记忆生效验证的完整落地路径并理解其底层实现与配置优先级。为什么这套方案成立Pydantic AI 将tools工具与instructions指令作为一等公民概念提供给 Agent。Hindsight 的集成恰好同时覆盖这两者记忆工具create_hindsight_tools给 Agent 显式的记忆操作能力让模型自主决定何时调用记忆指令memory_instructions在每轮运行开始前自动把相关记忆注入上下文属于自动召回。两者结合就能同时实现自动记忆使用与Agent 驱动的显式记忆操作既不需要线程池 hack也不需要手写召回逻辑。从源码看该集成是端到端异步原生的——retain、recall、reflect 全部走异步路径aretain/arecall/areflect在 async 生产服务中接入时不需要任何同步包装参见 tools.py。前置条件一个可正常运行的 Pydantic AI AgentPython 环境已安装hindsight-pydantic-ai一个跨运行保持稳定的 Bank ID 策略同一用户或同一项目在不同会话中必须复用相同的 Bank ID。Step 1安装集成包pip install hindsight-pydantic-ai该包是轻量设计根据 pyproject.toml 与 README.md它只依赖pydantic-ai-slim1.0.0避免拉入全部模型提供商与hindsight-client0.4.0运行要求 Python 3.10采用 MIT 许可证。Step 2连接 Pydantic AI 与 Hindsight连接 Hindsight 后端有两种方式核心都是构造一个Hindsight客户端方式一Hindsight Cloud推荐免自托管from hindsight_client import Hindsight client Hindsight(base_urlhttps://api.hindsight.vectorize.io, api_keyhsk_...)方式二本地自托管如果使用仓库自带的启动脚本在本地运行 Hindsight例如./scripts/dev/start-api.sh只需把 URL 指向本地端口client Hindsight(base_urlhttp://localhost:8888)也可以调用一次configure()建立全局配置之后创建工具时无需反复传 client详见下文全局配置章节。Step 3将记忆接入 Pydantic AI 运行时最干净的模式是给 Agent 挂上 Hindsight 工具再通过memory_instructions()让相关记忆在每次运行前自动注入from hindsight_client import Hindsight from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions from pydantic_ai import Agent client Hindsight(base_urlhttps://api.hindsight.vectorize.io, api_keyhsk_...) agent Agent( openai:gpt-4o, toolscreate_hindsight_tools(clientclient, bank_iduser-123), instructions[memory_instructions(clientclient, bank_iduser-123)], ) result await agent.run(What do you remember about my preferences?) print(result.output)上述代码执行后Agent 会获得三个可调用的记忆工具源码定义见 tools.py工具名职责对应底层 APIhindsight_retain将信息写入长期记忆事实、用户偏好、决策、规则等client.aretain()hindsight_recall搜索长期记忆中与查询相关的信息返回编号列表client.arecall()hindsight_reflect基于记忆合成有条理、有推理的回答而非返回原始事实client.areflect()三个工具都是takes_ctxFalse的异步闭包直接捕获已解析的 client因此不需要修改RunContext或 deps。默认三个工具全部创建也可以通过include_retain/include_recall/include_reflect任意裁剪组合例如省略 reflecttools create_hindsight_tools( clientclient, bank_iduser-123, include_retainTrue, include_recallTrue, include_reflectFalse, # Omit reflect )而memory_instructions()返回的是一个兼容Agent(instructions[...])的异步可调用对象tools.py。它在每次agent.run()时都会被重新求值自动调用arecall()召回记忆以prefix默认Relevant memories:\n为前缀拼成编号列表注入系统提示词——因此即使复用了message_history注入的记忆也始终是最新状态。两种变体按需取舍只要工具、不要自动注入Agent 自己决定何时用记忆agent Agent( openai:gpt-4o, toolscreate_hindsight_tools(clientclient, bank_iduser-123), )只要自动注入、不给工具agent Agent( openai:gpt-4o, instructions[memory_instructions(clientclient, bank_iduser-123)], )Step 4选择合适的 Bank 策略Bank记忆库是 Hindsight 组织记忆的命名空间所有 retain/recall 操作都以bank_id为锚点按用户建 Bank每用户一个对跟随单个用户的助手类应用是最安全的默认选择按工作流/项目建 Bank当同一个用户操作多个互不相关的系统时更合理绝对避免每次请求轮换 Bank ID那会让 Agent 看起来无状态即使集成本身正确记忆也永远无法被后续会话命中。此外注意工具与指令必须使用同一个 Bank ID否则会出现存进 A 库、从 B 库查的错位。Step 5验证记忆确实生效按以下步骤做端到端验证运行一次 Agent让它记住一条偏好或操作规则触发 retain使用相同的 Bank ID再次运行向它询问该细节检查回答是否在任何显式工具调用之前就已反映先前的记忆即自动注入生效如果未生效检查指令输出内容并确认 recall 使用的是预期的 Bank。判定标准第二次运行能答出第一次运行存下的细节说明配置成功。如果不行开启调试日志、核对配置的 Bank ID并确认 retain 调用确实完成。值得说明的是memory_instructions()具备故障隔离设计源码中指令函数对召回异常采取静默处理直接返回空字符串见 tools.py确保记忆后端短暂不可用时不会阻塞 Agent 主流程而显式工具调用失败则会抛出HindsightError让 Agent 感知错误测试用例见 test_tools.py 中的TestRetainTool/TestRecallTool/TestReflectTool。全局配置与单次覆盖client 解析与参数优先级如果不想在每个调用点都传 client可以先调用configure()做一次全局配置实现见 config.pyfrom hindsight_pydantic_ai import configure, create_hindsight_tools configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, # Hindsight Cloud (default) 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 ) # 之后无需传 client直接使用全局配置 tools create_hindsight_tools(bank_iduser-123)api_key缺省时会回退读取HINDSIGHT_API_KEY环境变量见 config.py。参数优先级规则源码见 tools.py 的_resolve_client显式传入的client优先直接使用不再创建新客户端未传 client 时依次回退hindsight_api_url/api_key显式参数 → 全局configure()配置 → 内置默认值若最终仍无 API URL抛出HindsightError(No Hindsight API URL configured...)未显式传入的budget/max_tokens/tags/recall_tags/recall_tags_match会回退到全局配置的默认值。构造函数参数覆盖全局配置tools create_hindsight_tools( bank_iduser-123, budgethigh, # 覆盖全局 budget max_tokens8192, # 覆盖全局 max_tokens tags[session:abc], # 覆盖全局 tags )create_hindsight_tools()参数参考参数默认值说明bank_id必填Hindsight 记忆库 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI 密钥未提供 client 时使用budgetmid召回/反思预算级别low/mid/highmax_tokens4096召回结果最大 token 数tagsNone存储记忆时附加的标签recall_tagsNone搜索时用于过滤的标签recall_tags_matchany标签匹配模式include_retainTrue是否包含 retain存储工具include_recallTrue是否包含 recall搜索工具include_reflectTrue是否包含 reflect合成工具memory_instructions()参数参考参数默认值说明bank_id必填Hindsight 记忆库 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI 密钥未提供 client 时使用queryrelevant context about the user记忆注入的召回查询budgetlow召回预算级别max_results5最多注入的记忆条数max_tokens4096召回结果最大 token 数prefixRelevant memories:\n记忆列表前的前缀文本tagsNone过滤召回结果的标签tags_matchany标签匹配模式configure()参数参考参数默认值说明hindsight_api_urlHindsight Cloudhttps://api.hindsight.vectorize.ioHindsight API URLapi_keyHINDSIGHT_API_KEY环境变量认证密钥budgetmid默认召回预算级别max_tokens4096默认召回最大 token 数tagsNone默认 retain 附加标签recall_tagsNone默认召回过滤标签recall_tags_matchany默认标签匹配模式verboseFalse开启详细日志按标签过滤召回记忆集成同时支持recall_tags与recall_tags_match用于收窄记忆作用域。例如在memory_instructions()中只注入带scope:global标签的记忆instructions_fn memory_instructions( clientclient, bank_iduser-123, queryrelevant context about the user, # 召回查询 budgetlow, # 保持低延迟 max_results5, # 限制注入条数 max_tokens4096, # 召回 token 上限 prefixRelevant memories:\n, # 列表前缀 tags[scope:global], # 标签过滤 tags_matchany, # 标签匹配模式 )标签过滤逻辑会原样透传给底层arecall()的tags与tags_match参数见 tools.pytags_match支持any/all/any_strict/all_strict四种匹配模式测试用例对标签传递的正确性有专门覆盖见 test_tools.py 的test_recall_passes_tags与test_passes_tags。常见错误加了工具却忘记加memory_instructions()导致本应自动召回的上下文没有注入工具和指令使用了不同的 Bank ID造成存取错位在某处覆盖了全局配置却忘了每次调用的实参优先级更高per call arguments win最终行为与预期不符。FAQQ1工具和记忆指令必须同时使用吗不需要。想要自动注入 显式记忆操作就两者都用如果某种设计更适合只用一个完全可以只用其中一个。测试test_tools.py也验证了三个工具可任意组合裁剪包括全部排除。Q2为什么异步支持在这里很重要因为 retain/recall/reflect 全部是异步原生调用aretain/arecall/areflect在 async 应用中接入时无需为记忆调用包一层丑陋的同步包装sync wrapper保持集成简单。Q3能否按标签过滤召回的记忆可以。集成支持recall_tags与recall_tags_match可以按标签收窄记忆作用域详见上文按标签过滤召回记忆章节。下一步若需要托管式记忆后端可从 Hindsight Cloud 起步若想自托管参考仓库中 Hindsight 安装/启动文档本地启动 API 后客户端指向http://localhost:8888完整的集成说明可继续阅读 hindsight-integrations/pydantic-ai/README.md 与 docs-integrations/pydantic-ai.md想要理解 retain/recall/reflect 在服务端的完整语义事实抽取、知识图谱、四种并行搜索策略等可阅读 Hindsight 快速开始文档 的 Whats Happening 章节需要确认底层客户端接口时可查看hindsight-client中aretain/arecall/areflect的实现与对应 API 定义想对比其他 Agent 框架的持久记忆接入方式可浏览仓库内 hindsight-integrations 目录下其他框架如 agno、langgraph、llamaindex 等的同构集成。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考