Hindsight 与 Pydantic AI 集成指南为 Agent 构建持久化长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文讲解如何在 Pydantic AI Agent 中接入 Hindsight 的长期记忆能力通过hindsight-pydantic-ai集成包一行配置即可为 Agent 挂载retain存储、recall检索、reflect综合三个异步记忆工具并借助memory_instructions在每次运行时自动注入相关记忆。读完本文你将掌握从安装、快速上手、工具裁剪、全局配置到参数覆盖的完整实战方案并理解其底层实现原理。Hindsight × Pydantic AI为什么需要这个集成Pydantic AI 的 Agent 本身是无状态的——每次agent.run()只基于当前对话上下文推理跨会话的用户偏好、历史决策与事实都会被遗忘。Hindsight 提供的是Memory Bank记忆银行维度的长期记忆服务二者结合后Agent 可以主动调用记忆工具在需要时存取事实也可以被动接收记忆注入每次运行时自动把相关记忆写进系统提示词。该集成方案完全基于 Pydantic AI 的原生async 工具接口与instructions参数实现不依赖线程池、不修改RunContext、不需要额外依赖注入因此被官方文档称为 async-native with no thread-pool hacks。集成包本身只依赖pydantic-ai-slim而非完整的pydantic-ai避免把全部模型提供商的依赖拉入项目保持轻量。安装pip install hindsight-pydantic-ai根据 pyproject.toml该包要求Python 3.10pydantic-ai-slim1.0.0hindsight-client0.4.0一个可访问的 Hindsight API 服务Hindsight Cloud 或本地自托管快速开始使用 Hindsight Cloud最简单的方式是使用 Hindsight Cloud注册并获取 API Key 后直接传入Hindsight客户端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 获得三个工具工具名职责hindsight_retain将信息存入长期记忆如重要事实、用户偏好、决策hindsight_recall按语义相似度检索长期记忆返回编号列表hindsight_reflect基于记忆综合出一个有推理依据的连贯回答而非罗列原始事实与此同时memory_instructions返回的可调用对象会在每次运行时自动执行一次 recall把命中的记忆注入系统提示词——即使复用message_history记忆内容也保持新鲜。本地自托管开发环境如果本地通过./scripts/dev/start-api.sh启动了 Hindsight 服务只需替换 base_urlclient Hindsight(base_urlhttp://localhost:8888)自托管的完整部署方式可参考 Docker Compose 部署示例 与 standalone 镜像构建脚本。两种使用模式工具驱动 vs 自动注入集成支持三种组合方式可根据 Agent 的自主性需求灵活选择1. 工具 自动注入推荐见上文快速开始Agent 既能主动查记忆系统也会自动补充上下文。2. 仅工具无自动注入让 Agent 自己决定何时使用记忆避免每次运行都注入上下文、节省 tokenagent Agent( openai:gpt-4o, toolscreate_hindsight_tools(clientclient, bank_iduser-123), )3. 仅注入无显式工具只想要记忆自动注入但不给 Agent 记忆工具权限agent Agent( openai:gpt-4o, instructions[memory_instructions(clientclient, bank_iduser-123)], )裁剪工具集三个工具默认全部启用但可以用include_*参数按需裁剪tools create_hindsight_tools( clientclient, bank_iduser-123, include_retainTrue, include_recallTrue, include_reflectFalse, # Omit reflect )对应测试 test_tools.py 验证了默认返回 3 个工具、单工具模式如仅hindsight_retain、全部排除返回空列表等行为。全局配置一次配置处处使用如果项目中有多个 Agent 需要接入记忆不必反复传 client用configure()全局配置一次from hindsight_pydantic_ai import configure, create_hindsight_tools configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, # Hindsight Cloud默认值 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 ) # 之后创建工具无需再传 client —— 自动使用全局配置 tools create_hindsight_tools(bank_iduser-123)从 config.py 的实现可以看到api_key未显式传入时会自动回退读取HINDSIGHT_API_KEY环境变量hindsight_api_url未传时使用常量DEFAULT_HINDSIGHT_API_URL https://api.hindsight.vectorize.io。模块内通过模块级全局变量_global_config保存配置并提供get_config()读取、reset_config()重置测试test_config.py对这三个行为均有覆盖。API Key 解析优先级configure(api_key...)显式参数 HINDSIGHT_API_KEY环境变量。按工具覆盖全局配置create_hindsight_tools()的构造参数优先于全局配置tools create_hindsight_tools( bank_iduser-123, budgethigh, # 覆盖全局 budget max_tokens8192, # 覆盖全局 max_tokens tags[session:abc], # 覆盖全局 tags )结合源码 tools.py 可见其优先级逻辑显式传入的tags/recall_tags/budget/max_tokens直接生效否则才回退到全局配置且 client 解析同样遵循「显式client 显式 URL/Key 全局配置」的顺序若三者皆无则抛出HindsightError(No Hindsight API URL configured...)。定制记忆注入memory_instructions 参数详解memory_instructions()允许精细控制注入哪些记忆、以什么格式注入instructions_fn memory_instructions( clientclient, bank_iduser-123, queryrelevant context about the user, # 检索用的查询语句 budgetlow, # 预算设为 low保持快速 max_results5, # 最多注入条数 max_tokens4096, # Recall 最大 token prefixRelevant memories:\n, # 记忆列表前的前缀文本 tags[scope:global], # 按标签过滤 tags_matchany, # 标签匹配模式 )容错设计值得注意的实现细节该注入函数在 recall 失败时静默返回空字符串而不是抛出异常阻塞 Agent 运行——从源码注释 instructions failures shouldnt block the agent 与测试test_error_returns_empty_string均可确认。这意味着记忆服务短暂不可用时Agent 依然能正常响应只是少了记忆上下文属于高可用的设计取舍。API 参考create_hindsight_tools()参数默认值说明bank_id必填Hindsight 记忆银行 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI URL未提供 client 时使用api_keyNoneAPI Key未提供 client 时使用budgetmidRecall/Reflect 预算级别low/mid/highmax_tokens4096Recall 结果最大 token 数tagsNone存储记忆时附加的标签recall_tagsNone检索记忆时的过滤标签recall_tags_matchany标签匹配模式any/all/any_strict/all_strictinclude_retainTrue是否包含 retain存储工具include_recallTrue是否包含 recall检索工具include_reflectTrue是否包含 reflect综合工具memory_instructions()参数默认值说明bank_id必填Hindsight 记忆银行 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 最大 tokentagsNoneretain 操作的默认标签recall_tagsNone默认 recall 过滤标签recall_tags_matchany默认标签匹配模式verboseFalse是否开启详细日志底层原理工具与指令是如何实现的从源码结构看集成包 hindsight_pydantic_ai 仅由四个文件构成职责非常清晰tools.py核心工厂函数create_hindsight_tools()与memory_instructions()config.py全局配置数据类HindsightPydanticAIConfig与configure()/get_config()/reset_config()errors.py统一异常类型HindsightError__init__.py对外导出版本号0.1.0。工具实现方式三个工具都是捕获了resolved_client的异步闭包通过Tool(fn, takes_ctxFalse)包装为 Pydantic AI 工具因此无需修改RunContext或注入依赖。工具内部依次调用 Python 客户端的异步方法hindsight_retain→client.aretain(bank_id, content, tags...)hindsight_recall→client.arecall(bank_id, query, budget, max_tokens, tags..., tags_match...)结果格式化为1. ...编号列表无结果时返回No relevant memories found.hindsight_reflect→client.areflect(bank_id, query, budget)直接返回综合文本。这些异步方法的签名定义在 hindsight_client.py其中arecall还支持types、query_timestamp、include_entities、temporal_window、min_scores等更高级的检索参数集成包暴露的是最常用的子集——需要更精细的检索控制时可以直接用Hindsight客户端调用完整 API。错误处理所有工具调用失败都会把原始异常包装为HindsightError抛出测试中验证了Retain failed、Recall failed、Reflect failed三种消息方便上层统一捕获与重试。最佳实践建议按用户划分 Memory Bank将bank_id设为用户/会话的唯一标识如user-123天然实现多租户记忆隔离善用标签体系存储时用tags[env:prod]标记来源环境检索时用recall_tags精确圈定记忆范围tags_match选择匹配策略any任一命中 /all全部命中另有any_strict/all_strict严格变体控制注入成本默认自动注入每次运行都会产生一次 recall 调用对延迟敏感的场景可把budgetlow、max_results调小或改用仅工具模式让 Agent 按需查询利用容错设计memory_instructions失败时静默降级生产环境无需为记忆服务的短暂抖动增加额外熔断逻辑多 Agent 复用配置应用启动时统一configure()一次所有 Agent 共享连接与默认参数个别 Agent 再用构造参数覆盖。总结hindsight-pydantic-ai用极简的 API 面两个工厂函数 一个全局配置为 Pydantic AI Agent 补齐了长期记忆能力异步原生、无线程池侵入、支持工具/注入/混合三种模式、全局配置与按工具覆盖并存并有完整的单元测试保障行为边界。无论是给客服 Agent 记忆用户偏好还是给编码助手保留跨会话的项目上下文这套集成都是低成本接入 Hindsight 记忆能力的直接路径。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考