为 Pydantic AI 接入持久化记忆hindsight-pydantic-ai 五步实战与源码剖析【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightPydantic AI 提供了类型化输出、依赖注入与异步原生工具但它的每次agent.run()都以空白状态开始——它不记得用户昨天说过什么、有什么偏好、此前研究过什么。本文以hindsight-pydantic-ai集成为核心讲解如何用约五行代码为任意 Pydantic AI Agent 接入 Hindsight 长期记忆retain / recall / reflect 三件套与自动记忆注入并结合仓库源码剖析其底层实现、全部可调参数与生产级注意事项。读完你即可在自己的 Python Agent 项目中落地跨会话、跨进程重启的持久化记忆。TL;DRPydantic AI 本身没有内置持久化记忆每次运行都从零开始hindsight-pydantic-ai提供 retain、recall、reflect 三个记忆工具以及自动注入记忆的memory_instructions()接入只需五步安装 Hindsight、安装集成包、创建客户端、调用create_hindsight_tools()传入 Agent、可选添加memory_instructions()memory_instructions()会在每次运行前静默地把相关记忆召回并注入系统提示词让 Agent 自带上下文开局与模型无关OpenAI、Anthropic、Gemini 均可使用。问题Pydantic AI 没有持久记忆Pydantic AI 是一个优秀的 Agent 框架类型化输出、依赖注入、异步原生设计、干净的工具 API。但它没有任何记忆层——这是事实而非缺陷描述每次agent.run()都从零开始Agent 不知道用户昨天说过什么、不知道用户的偏好、不知道它自己已经研究过什么。你当然可以通过message_history在同一会话内延续对话但那是聊天历史不是记忆聊天历史不会提炼事实、不会合并重复信息它会线性膨胀直到撑爆上下文窗口和 token 预算。真正的 Agent 记忆应该是从对话中抽取结构化事实构建实体与关系的知识图谱跨天、跨周、跨月地检索相关上下文从零散记忆中综合出连贯的答案。这正是 Hindsight 提供的一个可以本地运行或云端托管的记忆引擎而hindsight-pydantic-ai通过 Pydantic AI 的**工具tools与指令instructions**两套机制把它直接接入 Agent无需自建 RAG 流水线也无需自行管理向量数据库。Pydantic AI 持久记忆在 Hindsight 中如何工作在写代码前先理解接入后的底层原理。当你通过 Hindsight 存储一条事实时它不会保存原始文本而是抽取结构化实体与关系、构建知识图谱并为多策略检索建立索引。之后 Agent 检索记忆时会综合使用语义搜索、BM25 关键词匹配、图谱遍历与时间排序。hindsight-pydantic-ai通过两个集成点把记忆引擎接入 Pydantic AIPydantic AI Agent |-- tools[create_hindsight_tools(...)] | |-- hindsight_retain - 存储事实到记忆 | |-- hindsight_recall - 检索相关记忆 | |-- hindsight_reflect - 综合全部记忆合成答案 | |-- instructions[memory_instructions(...)] |-- 每次运行自动召回相关记忆并注入系统提示词**工具Tools**让 Agent 在对话过程中显式地存储与检索记忆**指令Instructions**则在 Agent 开始思考之前就静默注入相关记忆。两者均可选可按需单独使用或组合使用。从源码看hindsight-integrations/pydantic-ai/hindsight_pydantic_ai/tools.py这三个工具是异步闭包hindsight_retain调用client.aretain()、hindsight_recall调用client.arecall()、hindsight_reflect调用client.areflect()并通过Tool(fn, takes_ctxFalse)包装。因为 Pydantic AI 本身是异步原生的这里没有任何线程池 hack 或兼容层。如果你偏好协议化接入也可以使用 Hindsight 的 MCP 记忆服务器仓库中的 hindsight-api-slim/hindsight_api/mcp_local.py来代替直接工具集成。五步为 Pydantic AI Agent 接入持久记忆整个设置大约五分钟安装 Hindsight、安装集成包、把工具接入 Agent、验证记忆跨会话生效。第 1 步安装并启动 Hindsight先安装 Hindsight 服务器并本地启动pip install hindsight-allexport HINDSIGHT_API_LLM_API_KEYYOUR_OPENAI_KEY hindsight-api服务默认运行在http://localhost:8888。它内置了嵌入式 Postgres、本地嵌入模型与本地重排序除实体抽取所需的 LLM API Key 外无需任何外部服务。仓库中的 hindsight-all/README.md 提供了该包的完整说明。提示也可以使用 Hindsight Cloud 跳过自建步骤云端提供同样的 API 与托管基础设施。第 2 步安装 Pydantic AI 记忆集成包pip install hindsight-pydantic-ai还需要一个模型提供商。以 OpenAI 为例pip install pydantic-ai-slim[openai]其他提供商同理替换为[anthropic]或[google]即可。集成包与模型无关记忆层无论用哪个 LLM 行为完全一致。从 pyproject.toml 可见该包仅依赖pydantic-ai-slim1.0.0与hindsight-client0.4.0且要求 Python 3.10刻意保持轻量依赖pydantic-ai-slim而非完整版避免拉入所有模型提供商。第 3 步向 Agent 添加持久记忆工具五行代码就在这里——创建 Hindsight 客户端生成记忆工具传入 Agentfrom hindsight_client import Hindsight from hindsight_pydantic_ai import create_hindsight_tools from pydantic_ai import Agent client Hindsight(base_urlhttp://localhost:8888) agent Agent( openai:gpt-4o-mini, toolscreate_hindsight_tools(clientclient, bank_iduser-123), )这就是完整的接入。Agent 现在拥有三个工具hindsight_retain(content)把信息存入长期记忆hindsight_recall(query)检索记忆并返回匹配的事实列表hindsight_reflect(query)从所有相关记忆中综合出一个有依据的答案。由 Agent 根据对话上下文自行决定何时调用哪个工具无需手动调用。从源码看tools.pyhindsight_retain内部把bank_id与content透传给aretain()成功后返回 Memory stored successfully.hindsight_recall把结果按1. ...、2. ...编号返回tools.py无结果时返回 No relevant memories found.。第 4 步验证跨会话记忆运行两段独立对话来验证记忆是否跨会话持久import asyncio async def main(): # 第一次对话 r1 await agent.run( Remember that I prefer functional programming patterns and Im building a data pipeline in Python. ) print(r1.output) # 之后的对话 —— Agent 回忆上下文 r2 await agent.run(What approach should I take for error handling?) print(r2.output) asyncio.run(main())第一次运行时Agent 通过hindsight_retain存储偏好第二次运行时Agent 调用hindsight_recall找到相关上下文然后基于已知信息给出建议函数式模式、Python、数据管道。这就是持久化记忆的核心价值跨运行、跨天、跨进程重启都有效。记忆存在于 Hindsight 的知识图谱中而非 Agent 的上下文窗口。即使完全重启 Python 进程Agent 也能从上次停止的地方继续。第 5 步用 Pydantic AI 指令自动注入记忆上面的工具需要 Agent 自己决定是否检索记忆。有时你希望持久记忆自动注入在 Agent 开始回复之前就位。Pydantic AI 的instructions参数支持异步可调用对象每次agent.run()都会执行——天然适合记忆注入from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions agent Agent( openai:gpt-4o-mini, toolscreate_hindsight_tools(clientclient, bank_iduser-123), instructions[memory_instructions(clientclient, bank_iduser-123)], )现在每次运行时memory_instructions都会调用 Hindsight 的 recall API把相关记忆注入系统提示词。Agent 每段对话都带着用户上下文开局无需任何工具调用。可以自定义查询、结果数量与前缀来控制注入内容memory_instructions( clientclient, bank_iduser-123, queryuser preferences, history, and context, max_results10, prefixHere is what you know about this user:\n, )从源码看tools.pymemory_instructions返回一个接收RunContext的异步函数它调用arecall()截取前max_results条结果拼上prefix与编号列表返回。如果 recall 失败或没有结果函数返回空字符串绝不阻塞 Agent 响应——这一点由测试 test_tools.py 的test_empty_results_returns_empty_string与test_error_returns_empty_string明确验证。Pydantic AI 记忆的高级配置选择要包含的记忆工具并非每次都需要全部三个工具。create_hindsight_tools允许按需选择# 只读 Agent能检索记忆但不能写入 tools create_hindsight_tools( clientclient, bank_iduser-123, include_retainFalse, include_recallTrue, include_reflectTrue, ) # 只写 Agent只存储数据不查询 tools create_hindsight_tools( clientclient, bank_iduser-123, include_retainTrue, include_recallFalse, include_reflectFalse, )这种灵活性在多 Agent 架构中很有用例如一个 Pydantic AI Agent 负责收集信息并写入持久记忆另一个 Agent 只读记忆来回答问题。拆分读写权限让每个 Agent 各司其职避免只应消费上下文的 Agent 意外写入记忆。测试 test_tools.py 对include_retain/include_recall/include_reflect的各种组合及全排除场景都有覆盖。多个 Agent 共享的全局配置如果有多个 Pydantic AI Agent 共享同一个 Hindsight 持久记忆实例用全局配置代替到处传clientfrom hindsight_pydantic_ai import configure, create_hindsight_tools configure(hindsight_api_urlhttp://localhost:8888, api_keyYOUR_KEY) # 无需 client工具使用全局配置 agent1_tools create_hindsight_tools(bank_idagent-1) agent2_tools create_hindsight_tools(bank_idagent-2)显式的client参数始终优先于全局配置允许在需要时按 Agent 覆盖。全局配置由 config.py 中的configure()管理api_key未显式传入时回退到HINDSIGHT_API_KEY环境变量默认 API 地址为https://api.hindsight.vectorize.io。_resolve_client()tools.py的解析顺序是显式client→ 显式hindsight_api_url/api_key→ 全局配置都不存在时抛出 HindsightError提示先传client或调用configure()。参数参考create_hindsight_tools()参数默认值说明bank_id必填Hindsight 记忆库 IDclientNone预配置的 Hindsight 客户端hindsight_api_urlNoneAPI 地址未传 client 时使用api_keyNoneAPI 密钥未传 client 时使用budgetmidrecall/reflect 预算级别low/mid/highmax_tokens4096recall 结果最大 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 地址未传 client 时使用api_keyNoneAPI 密钥未传 client 时使用queryrelevant context about the user记忆注入的召回查询budgetlowrecall 预算级别默认低延迟max_results5注入的记忆条数上限max_tokens4096recall 结果最大 token 数prefixRelevant memories:\n记忆列表前的文本tagsNone过滤 recall 结果的标签tags_matchany标签匹配模式参数参考configure()参数默认值说明hindsight_api_urlHindsight Cloudhttps://api.hindsight.vectorize.ioHindsight API 地址api_keyHINDSIGHT_API_KEY环境变量认证密钥budgetmid默认 recall 预算级别max_tokens4096默认 recall 最大 token 数tagsNoneretain 操作的默认标签recall_tagsNone过滤 recall 的默认标签recall_tags_matchany默认标签匹配模式verboseFalse是否启用详细日志逐参数覆盖全局配置构造参数优先于全局配置tools.py 中的解析逻辑、README.md 的示例均有体现tools create_hindsight_tools( bank_iduser-123, budgethigh, # 覆盖全局 budget max_tokens8192, # 覆盖全局 max_tokens tags[session:abc], # 覆盖全局 tags )关于标签匹配与标签作用域recall_tags_match支持any/all/any_strict/all_strict客户端 hindsight_client.py 还额外支持exact。any表示命中任一标签即返回all要求全部命中*_strict变体用于更严格的匹配语义。配合tags写入时打标与recall_tags读取时过滤你可以按项目、环境或主题切分记忆空间例如tags[env:prod]与recall_tags[scope:global]。Pydantic AI 持久记忆完整可运行示例保存为memory_agent.py并运行import asyncio from hindsight_client import Hindsight from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions from pydantic_ai import Agent BANK_ID demo-user async def main(): client Hindsight(base_urlhttp://localhost:8888) await client.acreate_bank(bank_idBANK_ID, nameDemo User Memory) agent Agent( openai:gpt-4o-mini, toolscreate_hindsight_tools(clientclient, bank_idBANK_ID), instructions[memory_instructions(clientclient, bank_idBANK_ID)], ) print(--- Run 1: Teaching the agent ---) r1 await agent.run( Remember: Im a backend engineer. I use Python and Rust. I prefer small, composable libraries over large frameworks. ) print(fAgent: {r1.output}\n) print(--- Run 2: Agent recalls context ---) r2 await agent.run(Recommend a web framework for my next project.) print(fAgent: {r2.output}\n) print(--- Run 3: Agent synthesizes ---) r3 await agent.run(What do you know about my engineering philosophy?) print(fAgent: {r3.output}) asyncio.run(main())运行export OPENAI_API_KEYYOUR_KEY python memory_agent.py第一次执行结束后再运行一次。Agent 会记住第一次会话的一切因为持久记忆把事实存在 Hindsight 里而不是进程里。注意示例中的await client.acreate_bank(...)在异步代码中必须使用async版本的acreate_bank而不是同步的create_bank()后者在asyncio.run()内会尝试创建嵌套事件循环而报错。陷阱与边界情况Bank ID 冲突。每个bank_id都是独立的持久记忆库。如果两个无关的 Agent 共享同一个 bank记忆会以意想不到的方式合并。请为每个用户、每个 Agent、每个项目使用唯一的 bank ID。指令延迟。memory_instructions在每次agent.run()时都会发起一次 recall API 调用。对延迟敏感的应用请使用budgetlow和较小的max_results或者干脆关闭自动注入只依赖 Agent 在需要时调用 recall 工具。多数情况下持久记忆查询带来的额外延迟约为 50–200ms具体取决于记忆规模与网络状况。重复记忆。如果 Agent 多次存储相同信息Hindsight 会在事实层面去重。但更好的做法是在系统提示词中给 Agent 清晰指引何时存储新事实、何时跳过。异步事件循环冲突。同步的create_bank()无法在asyncio.run()内工作因为它会尝试创建嵌套事件循环。异步代码中务必使用await client.acreate_bank()。这是 Python 异步编程的常见陷阱并非 Hindsight 或 Pydantic AI 集成特有的问题。权衡与替代方案何时适合使用Pydantic AI 持久记忆 Hindsight 最适合与同一用户或同一上下文跨多次会话交互的 Agent。典型场景个人助理、客服机器人、不断积累知识的研究型 Agent以及任何记住过往交互能随时间提升质量的 Python Agent。何时不要使用一次性 Agent运行后不再出现、无状态的 API 处理器每个请求相互独立、或你希望完全控制提示词内容的场景。最后一种情况下请直接使用 Hindsight Python 客户端hindsight-clients/python/hindsight_client/hindsight_client.py而不是 Pydantic AI 集成。方案对比方案优势劣势最适合Hindsight Pydantic AI多策略检索语义 BM25 图谱 时间、结构化事实抽取、综合引擎需要运行 Hindsight 服务或使用云版本需要深度记忆的多会话 Agent手动 message_historyPydantic AI 内置、无额外依赖不提炼事实、线性膨胀直至撑爆上下文窗口简短的单会话对话自建向量库 RAG完全控制嵌入与检索需要自行管理分块、索引与检索已有向量基础设施的团队Mem0另一种外部记忆方案、API 简单检索策略较少、无图谱召回不需要实体关系的简单记忆需求总结一行也不多的持久记忆接入接入 Pydantic AI 持久记忆不需要复杂基础设施或自建检索流水线。hindsight-pydantic-ai提供的两个函数覆盖了完整的 Agent 记忆生命周期create_hindsight_tools()返回异步工具Agent 调用它们跨会话存储与检索知识memory_instructions()每次运行自动注入相关记忆Agent 自带上下文开局、无需工具调用。这个集成刻意保持最小化两个函数无需子类化无需修改 deps 类型——只是连接到真实记忆引擎的 Pydantic AI 工具与指令。记忆在进程重启后依然存活随时间构建知识图谱并随 Agent 对每个用户的了解加深而不断增值。对需要持久记忆的 Pydantic AI Agent 开发者来说这是从无状态走向有状态的最短路径。下一步实践本地试跑pip install hindsight-all hindsight-pydantic-ai pydantic-ai-slim[openai]然后运行上面的完整示例用标签切分记忆retain 使用tags、检索使用recall_tags按项目、环境或主题分区组合工具与指令memory_instructions负责自动上下文工具负责对话中的显式存取继续读源码集成实现见 hindsight-integrations/pydantic-ai/hindsight_pydantic_ai/tools.py配置见 config.py行为契约由 tests/test_tools.py 与 tests/test_config.py 锁定客户端底层 API 见 hindsight_client.pyaretain/arecall/areflect探索其他集成仓库中还有针对 CrewAI、OpenAI Agents 等框架的同类记忆集成以及 MCP 记忆服务器可视化知识图谱运行 Hindsight 控制平面hindsight-control-plane浏览抽取到的事实、实体与关系。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考