为 Pydantic AI 接入持久化记忆：hindsight-pydantic-ai 五步实战与源码剖析

为 Pydantic AI 接入持久化记忆：hindsight-pydantic-ai 五步实战与源码剖析

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

Pydantic AI 提供了类型化输出、依赖注入与异步原生工具，但它的每次agent.run()都以空白状态开始——它不记得用户昨天说过什么、有什么偏好、此前研究过什么。本文以hindsight-pydantic-ai集成为核心，讲解如何用约五行代码为任意 Pydantic AI Agent 接入 Hindsight 长期记忆（retain / recall / reflect 三件套与自动记忆注入），并结合仓库源码剖析其底层实现、全部可调参数与生产级注意事项。读完你即可在自己的 Python Agent 项目中落地跨会话、跨进程重启的持久化记忆。

TL;DR

• Pydantic 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 AI：

Pydantic 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_ctx=False)包装。因为 Pydantic AI 本身是异步原生的，这里没有任何线程池 hack 或兼容层。如果你偏好协议化接入，也可以使用 Hindsight 的 MCP 记忆服务器（仓库中的 hindsight-api-slim/hindsight_api/mcp_local.py）来代替直接工具集成。

五步为 Pydantic AI Agent 接入持久记忆

整个设置大约五分钟：安装 Hindsight、安装集成包、把工具接入 Agent、验证记忆跨会话生效。

第 1 步：安装并启动 Hindsight

先安装 Hindsight 服务器并本地启动：

pip install hindsight-all

export HINDSIGHT_API_LLM_API_KEY=YOUR_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-slim>=1.0.0与hindsight-client>=0.4.0，且要求 Python >= 3.10，刻意保持轻量（依赖pydantic-ai-slim而非完整版，避免拉入所有模型提供商）。

第 3 步：向 Agent 添加持久记忆工具

"五行代码"就在这里——创建 Hindsight 客户端，生成记忆工具，传入 Agent：

from hindsight_client import Hindsight from hindsight_pydantic_ai import create_hindsight_tools from pydantic_ai import Agent client = Hindsight(base_url="http://localhost:8888") agent = Agent( "openai:gpt-4o-mini", tools=create_hindsight_tools(client=client, bank_id="user-123"), )

这就是完整的接入。Agent 现在拥有三个工具：

• hindsight_retain(content)：把信息存入长期记忆；
• hindsight_recall(query)：检索记忆并返回匹配的事实列表；
• hindsight_reflect(query)：从所有相关记忆中综合出一个有依据的答案。

由 Agent 根据对话上下文自行决定何时调用哪个工具，无需手动调用。从源码看（tools.py），hindsight_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 I'm 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", tools=create_hindsight_tools(client=client, bank_id="user-123"), instructions=[memory_instructions(client=client, bank_id="user-123")], )

现在每次运行时，memory_instructions都会调用 Hindsight 的 recall API，把相关记忆注入系统提示词。Agent 每段对话都带着用户上下文开局，无需任何工具调用。

可以自定义查询、结果数量与前缀来控制注入内容：

memory_instructions( client=client, bank_id="user-123", query="user preferences, history, and context", max_results=10, prefix="Here is what you know about this user:\n", )

从源码看（tools.py），memory_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( client=client, bank_id="user-123", include_retain=False, include_recall=True, include_reflect=True, ) # 只写 Agent：只存储数据，不查询 tools = create_hindsight_tools( client=client, bank_id="user-123", include_retain=True, include_recall=False, include_reflect=False, )

这种灵活性在多 Agent 架构中很有用：例如一个 Pydantic AI Agent 负责收集信息并写入持久记忆，另一个 Agent 只读记忆来回答问题。拆分读写权限让每个 Agent 各司其职，避免只应消费上下文的 Agent 意外写入记忆。测试 test_tools.py 对include_retain/include_recall/include_reflect的各种组合及全排除场景都有覆盖。

多个 Agent 共享的全局配置

如果有多个 Pydantic AI Agent 共享同一个 Hindsight 持久记忆实例，用全局配置代替到处传client：

from hindsight_pydantic_ai import configure, create_hindsight_tools configure(hindsight_api_url="http://localhost:8888", api_key="YOUR_KEY") # 无需 client：工具使用全局配置 agent1_tools = create_hindsight_tools(bank_id="agent-1") agent2_tools = create_hindsight_tools(bank_id="agent-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()

参数参考：memory_instructions()

参数参考：configure()

逐参数覆盖全局配置

构造参数优先于全局配置（tools.py 中的解析逻辑、README.md 的示例均有体现）：

tools = create_hindsight_tools( bank_id="user-123", budget="high", # 覆盖全局 budget max_tokens=8192, # 覆盖全局 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_url="http://localhost:8888") await client.acreate_bank(bank_id=BANK_ID, name="Demo User Memory") agent = Agent( "openai:gpt-4o-mini", tools=create_hindsight_tools(client=client, bank_id=BANK_ID), instructions=[memory_instructions(client=client, bank_id=BANK_ID)], ) print("--- Run 1: Teaching the agent ---") r1 = await agent.run( "Remember: I'm a backend engineer. I use Python and Rust. " "I prefer small, composable libraries over large frameworks." ) print(f"Agent: {r1.output}\n") print("--- Run 2: Agent recalls context ---") r2 = await agent.run("Recommend a web framework for my next project.") print(f"Agent: {r2.output}\n") print("--- Run 3: Agent synthesizes ---") r3 = await agent.run("What do you know about my engineering philosophy?") print(f"Agent: {r3.output}") asyncio.run(main())

运行：

export OPENAI_API_KEY=YOUR_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 调用。对延迟敏感的应用，请使用budget="low"和较小的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 集成。

方案对比

总结：一行也不多的持久记忆接入

接入 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.py（aretain/arecall/areflect）；
• 探索其他集成：仓库中还有针对 CrewAI、OpenAI Agents 等框架的同类记忆集成，以及 MCP 记忆服务器；
• 可视化知识图谱：运行 Hindsight 控制平面（hindsight-control-plane）浏览抽取到的事实、实体与关系。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight