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），僅供參考