使用 Hindsight 为 LlamaIndex Agent 添加跨会话持久记忆HindsightMemory 与 HindsightToolSpec 实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南介绍如何为 LlamaIndex Agent 接入 Hindsight 持久记忆使用HindsightMemory实现自动化的跨会话记忆回放recall与存储retain或在需要 Agent 自主决策记忆时机时切换到HindsightToolSpec显式工具模式。读完本文你将掌握两种模式的接入步骤、bank 策略选择、参数调优与端到端验证方法并理解其底层基于 LlamaIndexBaseMemory/BaseToolSpec的实现原理。快速答案安装hindsight-llamaindex集成包或插件。将客户端指向 Hindsight Cloud 或本地自托管的 Hindsight API。使用一个稳定的 bank ID 将记忆接入 LlamaIndex 运行时。存储一条用户偏好或项目事实然后开启一次全新的运行会话。确认 recall 能自动带回之前的上下文。为什么这套方案可行LlamaIndex 本身已经提供了记忆抽象层Hindsight 可以在正确的层次上接入HindsightMemory在 Agent 运行前回放上下文recall、在每轮对话结束后存储消息retain而 tool spec 模式则在你希望获得显式工具控制权时提供retain、recall、reflect三个工具交给 Agent 自行决策。两种模式并存是这份集成设计的核心特色这一点在 集成包 README 和init.py 中均有明确说明工具模式HindsightToolSpec/create_hindsight_tools基于 LlamaIndex 的BaseToolSpec由 Agent 决定何时 retain / recall / reflect记忆模式HindsightMemory基于 LlamaIndex 的BaseMemory接口每一轮消息自动存储、自动以上下文形式回放。对于大多数场景自动记忆模式更平滑——它不需要把每个工作流都改造成手动的记忆调用。前置条件一个可运行的 LlamaIndex Agent 或 workflowPython 环境并已安装hindsight-llamaindex一个稳定的 bank ID代表你想要跨时间持久化的用户、项目或助手。根据 pyproject.toml 的声明该集成要求 Python 3.10、llama-index-core0.11.0、hindsight-client0.4.0。Step 1安装集成包pip install hindsight-llamaindex安装后建议顺手确认hindsight_client也可用它是本集成的底层 HTTP 客户端依赖用于调用 Hindsight 的 retain / recall / reflect API。Step 2连接 LlamaIndex 与 Hindsightfrom hindsight_client import Hindsight client Hindsight(base_urlhttp://localhost:8888)使用 Hindsight Cloud 时改用云 API 地址并按与其他 Python 集成相同的方式为客户端配置认证API key。从源码看客户端解析逻辑集中在 _client.py 的resolve_client()中其回退顺序是显式传入的client优先其次hindsight_api_url/api_key参数再其次全局configure()配置最后回退到默认 API 地址和HINDSIGHT_API_KEY环境变量。默认 API 地址定义在 config.pyDEFAULT_HINDSIGHT_API_URL https://api.hindsight.vectorize.io HINDSIGHT_API_KEY_ENV HINDSIGHT_API_KEY也就是说自托管用户可以只传base_url而使用云端时即使不显式传入 key只要设置了HINDSIGHT_API_KEY环境变量from_defaults()/create_hindsight_tools()等工厂方法也能自动读取。API key 在构造客户端时是可选的——缺失 key 只会在真正发起调用时报错。全局配置方式不想在每次构造时重复传参可以调用configure()设置全局默认值from hindsight_llamaindex import configure configure( hindsight_api_urlhttp://localhost:8888, api_keyyour-api-key, budgetmid, tags[source:llamaindex], contextmy-app, missionTrack user preferences, )configure()支持的全部字段及默认值见 config.pyhindsight_api_url默认https://api.hindsight.vectorize.io、api_key、budget默认mid、max_tokens默认 4096、tags、recall_tags、recall_tags_match默认any、context默认llamaindex、mission、verbose。Step 3将记忆接入运行时3.1 自动记忆模式推荐起步import asyncio from hindsight_client import Hindsight from hindsight_llamaindex import HindsightMemory from llama_index.core.agent import ReActAgent from llama_index.llms.openai import OpenAI async def main(): client Hindsight(base_urlhttp://localhost:8888) memory HindsightMemory.from_client( clientclient, bank_iduser-123, missionTrack user preferences and project context, ) agent ReActAgent(tools[], llmOpenAI(modelgpt-4o)) response await agent.run(Remember that I prefer dark mode, memorymemory) print(response) asyncio.run(main())关于记忆如何挂到 Agent 上memory.py 的类文档特别强调memory 是通过run(..., memorymemory)传入而不是传给构造函数——这与 LlamaIndex 新版本 workflow 型 Agentllama_index.core.agent.workflow.ReActAgent及同类的调用约定一致。3.2 显式工具模式如果你希望 Agent 显式决定何时存储或搜索记忆则创建HindsightToolSpec并将其工具传给 Agentimport asyncio from hindsight_client import Hindsight from hindsight_llamaindex import HindsightToolSpec from llama_index.llms.openai import OpenAI from llama_index.core.agent import ReActAgent async def main(): client Hindsight(base_urlhttp://localhost:8888) spec HindsightToolSpec( clientclient, bank_iduser-123, missionTrack user preferences, ) tools spec.to_tool_list() agent ReActAgent(toolstools, llmOpenAI(modelgpt-4o)) response await agent.run(Remember that I prefer dark mode) print(response) asyncio.run(main())HindsightToolSpec默认暴露三个工具同步/异步成对见 tools.py 的spec_functions工具名异步实现作用retain_memoryaretain_memory将信息存入长期记忆recall_memoryarecall_memory搜索长期记忆返回编号列表reflect_on_memoryareflect_on_memory基于记忆综合出连贯、有理有据的回答异步 Agent如ReActAgent使用异步实现同步方法作为回退。还有一个便捷工厂create_hindsight_tools()支持用include_retain/include_recall/include_reflect三个布尔参数裁剪工具列表直接返回可供 Agent 使用的FunctionTool列表例如只保留 recallfrom hindsight_llamaindex import create_hindsight_tools tools create_hindsight_tools( bank_iduser-123, include_retainFalse, include_reflectFalse, # 只留下 recall_memory )源码级原理HindsightMemory 内部如何工作HindsightMemory直接继承 LlamaIndex 的BaseMemory核心行为memory.py如下put()/aput()把消息追加到本地会话缓冲同时调用client.retain()将 user / assistant 消息异步存入 Hindsight 长期记忆库。system消息与空白内容会被跳过。get()/aget()先用input未传入时回退到本地历史中最近一条 user 消息见_recall_query()作为查询调用recall()把返回的记忆按- 条目格式渲染并用system_prompt模板默认Below are relevant memories from previous conversations:\n{memories}\n...包装成一条 SYSTEM 消息前置到对话历史之前再返回给 Agent。本地缓冲与长期记忆分离_chat_history只保留当前会话默认上限 100 条chat_history_limit可调超出丢弃最旧消息Hindsight 存储的是跨会话长期记忆。因此每个新会话可以从零开始同时仍能回放过去记忆。ReAct 痕迹清洗assistant 消息若包含Thought:/Action:/Observation:等 ReAct 推理痕迹会只提取最后一段Answer:文本入库纯推理无答案的消息跳过 retain。这一逻辑在_extract_clean_content()中实现。Bank 自动创建传入mission时首次 put/get 会调用create_bank()自动建库幂等失败静默容忍并把 mission 作为事实抽取的引导。优雅降级retain / recall 失败只记日志并返回空结果绝不向上抛出导致 Agent 中断——test_memory.py 中的test_put_retain_failure_is_graceful、test_get_recall_failure_is_graceful均验证了这一点。HindsightMemory 参数速查参数默认值说明bank_id必填操作的 Hindsight 记忆库 IDmissionNone记忆库使命描述首次使用时自动建库并引导事实抽取contextllamaindexretain 操作的来源标签budgetmidrecall 预算级别low/mid/highmax_tokens4096recall 结果的最大 token 数tagsNoneretain 时附加的标签recall_tagsNonerecall 时用于过滤的标签recall_tags_matchany标签匹配模式any/all/any_strict/all_strictsystem_prompt内置模板记忆系统消息模板必须包含{memories}占位符chat_history_limit100本地缓冲最大消息数超出丢弃最旧除from_client()外还提供from_defaults()自动走云端默认地址与HINDSIGHT_API_KEY环境变量和from_url()只传 URL 即可两种构造方式。Step 4选择正确的 Bank 策略按用户建库per-user banks适合一个助手跟随同一个用户跨多个会话的场景。按项目建库per-project banks适合同一个用户跨多个不相关领域工作的场景避免记忆互相污染。关键在于一致性无论选择什么 key都要保持稳定确保aput()和aget()始终命中同一个 bank。如果每次运行都换一个新 bank ID连续性会被彻底破坏——这也是文档明确列出的最常见错误之一。Step 5验证记忆是否生效运行一次 Agent存储一条测试偏好或项目事实。使用相同的 bank ID 开启一个新会话并向 Agent 询问那条细节。确认HindsightMemory自动注入了之前的上下文而无需手动调用任何记忆工具。若 recall 失败检查 bank 是否被自动创建、以及是否复用了同一个 bank ID。如果第二次运行能回答出第一次运行留下的细节说明配置成功。若不能请打开 debug 日志、核对配置的 bank ID并确认 retain 调用确实完成了。仓库中的端到端测试 test_e2e.py 演示了完整的验证思路启动本地 Hindsighthttp://localhost:8888通过/health探活后test_retain_and_recall_roundtrip存储一条技术栈事实并轮询 recall 直到命中test_put_and_get_roundtrip则验证HindsightMemory.aget()能在约 12 秒内把上一轮put()的事实回放出来。这类测试需要真实 Hindsight 服务属于requires_real_llm标记的 E2E 测试桶单测桶mock 客户端则不依赖任何外部服务。常见错误每次运行使用新的 bank ID破坏了连续性在自动记忆更简单的场景选择了 tool spec 模式徒增 Agent 的工具决策负担mission 留空当 Agent 有专门领域时留空 mission 会损失更好的事实抽取引导导致记忆质量下降。FAQ应该先用 HindsightMemory 还是 HindsightToolSpec需要自动记忆行为时先用HindsightMemory当 Agent 需要自行决定何时存储或搜索记忆时切换到HindsightToolSpec。HindsightMemory 是否也保留本地缓冲是。本地聊天缓冲与长期记忆库是分离的每个新会话都可以从零开始同时仍能回放过去的记忆。从实现看本地缓冲由chat_history_limit默认 100控制reset()只清空本地缓冲而不会删除 Hindsight 中已存储的记忆。bank mission 应该写什么描述你希望被记住的事实与上下文例如项目决策、用户偏好、反复出现的工作流细节。mission 会在首次使用时通过create_bank()写入记忆库并作为后续事实抽取的引导依据。下一步自托管部署时参考 docker/docker-compose 下的编排示例与 hindsight-api 的 README获得一个本地 Hindsight API 端点深入了解集成包源码memory.py、tools.py、config.py对照单元测试理解行为契约test_memory.py、test_tools.py若想在其他 Agent 框架中复用同样的记忆能力可参考 hindsight-integrations 目录下其他框架的集成实现如 agno、langgraph、pydantic-ai 等底层 Python 客户端的完整用法见 hindsight-clients/python/README.md。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Hindsight 为 LlamaIndex Agent 添加跨会话持久记忆：HindsightMemory 与 HindsightToolSpec 实战指南
使用 Hindsight 为 LlamaIndex Agent 添加跨会话持久记忆HindsightMemory 与 HindsightToolSpec 实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南介绍如何为 LlamaIndex Agent 接入 Hindsight 持久记忆使用HindsightMemory实现自动化的跨会话记忆回放recall与存储retain或在需要 Agent 自主决策记忆时机时切换到HindsightToolSpec显式工具模式。读完本文你将掌握两种模式的接入步骤、bank 策略选择、参数调优与端到端验证方法并理解其底层基于 LlamaIndexBaseMemory/BaseToolSpec的实现原理。快速答案安装hindsight-llamaindex集成包或插件。将客户端指向 Hindsight Cloud 或本地自托管的 Hindsight API。使用一个稳定的 bank ID 将记忆接入 LlamaIndex 运行时。存储一条用户偏好或项目事实然后开启一次全新的运行会话。确认 recall 能自动带回之前的上下文。为什么这套方案可行LlamaIndex 本身已经提供了记忆抽象层Hindsight 可以在正确的层次上接入HindsightMemory在 Agent 运行前回放上下文recall、在每轮对话结束后存储消息retain而 tool spec 模式则在你希望获得显式工具控制权时提供retain、recall、reflect三个工具交给 Agent 自行决策。两种模式并存是这份集成设计的核心特色这一点在 集成包 README 和init.py 中均有明确说明工具模式HindsightToolSpec/create_hindsight_tools基于 LlamaIndex 的BaseToolSpec由 Agent 决定何时 retain / recall / reflect记忆模式HindsightMemory基于 LlamaIndex 的BaseMemory接口每一轮消息自动存储、自动以上下文形式回放。对于大多数场景自动记忆模式更平滑——它不需要把每个工作流都改造成手动的记忆调用。前置条件一个可运行的 LlamaIndex Agent 或 workflowPython 环境并已安装hindsight-llamaindex一个稳定的 bank ID代表你想要跨时间持久化的用户、项目或助手。根据 pyproject.toml 的声明该集成要求 Python 3.10、llama-index-core0.11.0、hindsight-client0.4.0。Step 1安装集成包pip install hindsight-llamaindex安装后建议顺手确认hindsight_client也可用它是本集成的底层 HTTP 客户端依赖用于调用 Hindsight 的 retain / recall / reflect API。Step 2连接 LlamaIndex 与 Hindsightfrom hindsight_client import Hindsight client Hindsight(base_urlhttp://localhost:8888)使用 Hindsight Cloud 时改用云 API 地址并按与其他 Python 集成相同的方式为客户端配置认证API key。从源码看客户端解析逻辑集中在 _client.py 的resolve_client()中其回退顺序是显式传入的client优先其次hindsight_api_url/api_key参数再其次全局configure()配置最后回退到默认 API 地址和HINDSIGHT_API_KEY环境变量。默认 API 地址定义在 config.pyDEFAULT_HINDSIGHT_API_URL https://api.hindsight.vectorize.io HINDSIGHT_API_KEY_ENV HINDSIGHT_API_KEY也就是说自托管用户可以只传base_url而使用云端时即使不显式传入 key只要设置了HINDSIGHT_API_KEY环境变量from_defaults()/create_hindsight_tools()等工厂方法也能自动读取。API key 在构造客户端时是可选的——缺失 key 只会在真正发起调用时报错。全局配置方式不想在每次构造时重复传参可以调用configure()设置全局默认值from hindsight_llamaindex import configure configure( hindsight_api_urlhttp://localhost:8888, api_keyyour-api-key, budgetmid, tags[source:llamaindex], contextmy-app, missionTrack user preferences, )configure()支持的全部字段及默认值见 config.pyhindsight_api_url默认https://api.hindsight.vectorize.io、api_key、budget默认mid、max_tokens默认 4096、tags、recall_tags、recall_tags_match默认any、context默认llamaindex、mission、verbose。Step 3将记忆接入运行时3.1 自动记忆模式推荐起步import asyncio from hindsight_client import Hindsight from hindsight_llamaindex import HindsightMemory from llama_index.core.agent import ReActAgent from llama_index.llms.openai import OpenAI async def main(): client Hindsight(base_urlhttp://localhost:8888) memory HindsightMemory.from_client( clientclient, bank_iduser-123, missionTrack user preferences and project context, ) agent ReActAgent(tools[], llmOpenAI(modelgpt-4o)) response await agent.run(Remember that I prefer dark mode, memorymemory) print(response) asyncio.run(main())关于记忆如何挂到 Agent 上memory.py 的类文档特别强调memory 是通过run(..., memorymemory)传入而不是传给构造函数——这与 LlamaIndex 新版本 workflow 型 Agentllama_index.core.agent.workflow.ReActAgent及同类的调用约定一致。3.2 显式工具模式如果你希望 Agent 显式决定何时存储或搜索记忆则创建HindsightToolSpec并将其工具传给 Agentimport asyncio from hindsight_client import Hindsight from hindsight_llamaindex import HindsightToolSpec from llama_index.llms.openai import OpenAI from llama_index.core.agent import ReActAgent async def main(): client Hindsight(base_urlhttp://localhost:8888) spec HindsightToolSpec( clientclient, bank_iduser-123, missionTrack user preferences, ) tools spec.to_tool_list() agent ReActAgent(toolstools, llmOpenAI(modelgpt-4o)) response await agent.run(Remember that I prefer dark mode) print(response) asyncio.run(main())HindsightToolSpec默认暴露三个工具同步/异步成对见 tools.py 的spec_functions工具名异步实现作用retain_memoryaretain_memory将信息存入长期记忆recall_memoryarecall_memory搜索长期记忆返回编号列表reflect_on_memoryareflect_on_memory基于记忆综合出连贯、有理有据的回答异步 Agent如ReActAgent使用异步实现同步方法作为回退。还有一个便捷工厂create_hindsight_tools()支持用include_retain/include_recall/include_reflect三个布尔参数裁剪工具列表直接返回可供 Agent 使用的FunctionTool列表例如只保留 recallfrom hindsight_llamaindex import create_hindsight_tools tools create_hindsight_tools( bank_iduser-123, include_retainFalse, include_reflectFalse, # 只留下 recall_memory )源码级原理HindsightMemory 内部如何工作HindsightMemory直接继承 LlamaIndex 的BaseMemory核心行为memory.py如下put()/aput()把消息追加到本地会话缓冲同时调用client.retain()将 user / assistant 消息异步存入 Hindsight 长期记忆库。system消息与空白内容会被跳过。get()/aget()先用input未传入时回退到本地历史中最近一条 user 消息见_recall_query()作为查询调用recall()把返回的记忆按- 条目格式渲染并用system_prompt模板默认Below are relevant memories from previous conversations:\n{memories}\n...包装成一条 SYSTEM 消息前置到对话历史之前再返回给 Agent。本地缓冲与长期记忆分离_chat_history只保留当前会话默认上限 100 条chat_history_limit可调超出丢弃最旧消息Hindsight 存储的是跨会话长期记忆。因此每个新会话可以从零开始同时仍能回放过去记忆。ReAct 痕迹清洗assistant 消息若包含Thought:/Action:/Observation:等 ReAct 推理痕迹会只提取最后一段Answer:文本入库纯推理无答案的消息跳过 retain。这一逻辑在_extract_clean_content()中实现。Bank 自动创建传入mission时首次 put/get 会调用create_bank()自动建库幂等失败静默容忍并把 mission 作为事实抽取的引导。优雅降级retain / recall 失败只记日志并返回空结果绝不向上抛出导致 Agent 中断——test_memory.py 中的test_put_retain_failure_is_graceful、test_get_recall_failure_is_graceful均验证了这一点。HindsightMemory 参数速查参数默认值说明bank_id必填操作的 Hindsight 记忆库 IDmissionNone记忆库使命描述首次使用时自动建库并引导事实抽取contextllamaindexretain 操作的来源标签budgetmidrecall 预算级别low/mid/highmax_tokens4096recall 结果的最大 token 数tagsNoneretain 时附加的标签recall_tagsNonerecall 时用于过滤的标签recall_tags_matchany标签匹配模式any/all/any_strict/all_strictsystem_prompt内置模板记忆系统消息模板必须包含{memories}占位符chat_history_limit100本地缓冲最大消息数超出丢弃最旧除from_client()外还提供from_defaults()自动走云端默认地址与HINDSIGHT_API_KEY环境变量和from_url()只传 URL 即可两种构造方式。Step 4选择正确的 Bank 策略按用户建库per-user banks适合一个助手跟随同一个用户跨多个会话的场景。按项目建库per-project banks适合同一个用户跨多个不相关领域工作的场景避免记忆互相污染。关键在于一致性无论选择什么 key都要保持稳定确保aput()和aget()始终命中同一个 bank。如果每次运行都换一个新 bank ID连续性会被彻底破坏——这也是文档明确列出的最常见错误之一。Step 5验证记忆是否生效运行一次 Agent存储一条测试偏好或项目事实。使用相同的 bank ID 开启一个新会话并向 Agent 询问那条细节。确认HindsightMemory自动注入了之前的上下文而无需手动调用任何记忆工具。若 recall 失败检查 bank 是否被自动创建、以及是否复用了同一个 bank ID。如果第二次运行能回答出第一次运行留下的细节说明配置成功。若不能请打开 debug 日志、核对配置的 bank ID并确认 retain 调用确实完成了。仓库中的端到端测试 test_e2e.py 演示了完整的验证思路启动本地 Hindsighthttp://localhost:8888通过/health探活后test_retain_and_recall_roundtrip存储一条技术栈事实并轮询 recall 直到命中test_put_and_get_roundtrip则验证HindsightMemory.aget()能在约 12 秒内把上一轮put()的事实回放出来。这类测试需要真实 Hindsight 服务属于requires_real_llm标记的 E2E 测试桶单测桶mock 客户端则不依赖任何外部服务。常见错误每次运行使用新的 bank ID破坏了连续性在自动记忆更简单的场景选择了 tool spec 模式徒增 Agent 的工具决策负担mission 留空当 Agent 有专门领域时留空 mission 会损失更好的事实抽取引导导致记忆质量下降。FAQ应该先用 HindsightMemory 还是 HindsightToolSpec需要自动记忆行为时先用HindsightMemory当 Agent 需要自行决定何时存储或搜索记忆时切换到HindsightToolSpec。HindsightMemory 是否也保留本地缓冲是。本地聊天缓冲与长期记忆库是分离的每个新会话都可以从零开始同时仍能回放过去的记忆。从实现看本地缓冲由chat_history_limit默认 100控制reset()只清空本地缓冲而不会删除 Hindsight 中已存储的记忆。bank mission 应该写什么描述你希望被记住的事实与上下文例如项目决策、用户偏好、反复出现的工作流细节。mission 会在首次使用时通过create_bank()写入记忆库并作为后续事实抽取的引导依据。下一步自托管部署时参考 docker/docker-compose 下的编排示例与 hindsight-api 的 README获得一个本地 Hindsight API 端点深入了解集成包源码memory.py、tools.py、config.py对照单元测试理解行为契约test_memory.py、test_tools.py若想在其他 Agent 框架中复用同样的记忆能力可参考 hindsight-integrations 目录下其他框架的集成实现如 agno、langgraph、pydantic-ai 等底层 Python 客户端的完整用法见 hindsight-clients/python/README.md。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考