在 Dify 中接入 Hindsight 长期记忆：Retain / Recall / Reflect 插件完整实战指南

在 Dify 中接入 Hindsight 长期记忆Retain / Recall / Reflect 插件完整实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文以 Hindsight 官方 Dify 集成插件为主线讲解如何在 Dify 工作流、Chatflow 与 Agent 应用中为每个流程注入跨运行的长期记忆。读完本文你将掌握插件的安装方式、凭据配置、三个记忆工具Retain、Recall、Reflect的参数语义以及一套可复现的验证流程并了解插件背后的源码实现与 API 行为。快速答案Quick Answer在 Dify 中进入Plugins → Install Plugin安装Hindsight插件。打开 Hindsight 插件填入API URL与API Key凭据。在 LLM 节点前放置一个Recall节点拉取相关历史上下文。放置一个Retain节点把新内容写入记忆库Bank。运行验证确认后续运行能召回此前运行存储的内容。为什么 Dify 需要 HindsightDify 是一个可视化的工作流构建器拥有日益丰富的工具与插件生态。但默认情况下Dify 的每次工作流执行都是**无状态stateless**的——上一次运行产生的信息不会自动带进下一次运行。这意味着基于 Dify 构建的客服机器人、销售助手或知识库 Agent每轮对话都要重新开始。Hindsight 插件解决的就是这个问题它为 Dify 提供跨运行的持久化长期记忆。插件以普通 Dify 节点Node的形式出现与工作流中已有的 LLM 节点、搜索节点、工具节点完全同构——放置一个Retain节点存储内容放置一个Recall节点在 LLM 步骤之前拉取相关上下文或放置一个Reflect节点对记忆库提出一个综合性的问题。整个接入过程不离开可视化画布。插件本身位于仓库的 hindsight-integrations/dify 目录manifest.yaml中定义插件名hindsight、版本0.1.0、类型plugin、作者vectorize采用 Python 3.12 运行环境runner.language: pythonrunner.version: 3.12并为插件分配了 256MB 内存资源、开启了工具权限resource.permission.tool.enabled: true。前置条件Prerequisites开始前请确认以下三项就绪一个可安装插件、可构建工作流的Dify 实例一个可访问的Hindsight 后端可以是 Hindsight Cloud也可以是自托管self-hosted的 Hindsight 服务器一份来自 Hindsight 控制台的API Key对于无需鉴权的自托管实例该项可选。对应仓库中的插件目录入口文件 main.py 通过DifyPluginEnv(MAX_REQUEST_TIMEOUT120)初始化插件即插件侧请求超时上限为 120 秒而底层 HTTP 客户端见下文源码分析默认超时为 30 秒。Step 1安装插件在 Dify 控制台进入Plugins → Install Plugin三种安装渠道任选其一安装方式操作说明Marketplace应用市场搜索Hindsight发布后可用GitHub从vectorize-io/hindsight仓库安装路径为hindsight-integrations/difyLocal本地上传.difypkg压缩包.difypkg本质上就是插件根目录的 zip 打包。仓库中的 build_package.sh 展示了打包过程脚本从manifest.yaml读取插件名与版本号生成hindsight-0.1.0.difypkg打包内容包含manifest.yaml、main.py、requirements.txt、PRIVACY.md、README.md、LICENSE、_assets、provider与tools目录并剔除__pycache__、*.pyc、.DS_Store等缓存文件。安装完成后Hindsight插件会出现在工作流编辑器的Tools工具列表中。Step 2添加 Hindsight 凭据打开 Hindsight 插件添加以下两项凭据API URL—— 默认值为https://api.hindsight.vectorize.io对应 Hindsight Cloud自托管时改为你的服务器地址。API Key—— 你的hsk_...密钥对于无需鉴权的自托管实例可选。这两项凭据在 provider/hindsight.yaml 中有精确定义api_url为必填文本框默认值https://api.hindsight.vectorize.io帮助文案中明确给出了自托管示例如http://localhost:8888api_key为密文输入框secret-input非必填占位符为hsk_...帮助文案注明以hsk_开头Hindsight Cloud 必填未鉴权的自托管实例可选。凭据如何生效看 tools/_client.py 的build_client实现它从凭据字典中读取api_url并去掉末尾斜杠读取api_key空值视为未设置然后构造Hindsight(base_url..., timeout30.0, api_key...)客户端——只有当 API Key 存在时才传入api_key参数。配套的 tests/test_helpers.py 覆盖了空 key 视为缺失去除末尾斜杠等边界行为。如果你还没有密钥可以注册 Hindsight Cloud 免费套餐并从控制台获取或者自行部署一个 Hindsight 服务器。Step 3把工具接入工作流插件提供三个工具放置方式与任何 Dify 节点相同。Retain —— 存储内容把自由文本内容写入记忆库。字段如下字段必填说明Bank ID是要写入的记忆库首次使用时自动创建Content是要保留的自由文本Tags否逗号分隔的标签如support,vipRetain 调用返回后Hindsight异步抽取其中的事实facts。其工具定义见 tools/retain.yaml实现见 tools/retain.py参数校验bank_id、content缺失时直接返回错误消息、通过parse_tags把逗号分隔的标签解析为列表、调用客户端client.retain(...)最后产出两条消息——JSON 消息包含success与bank_id文本消息形如Retained 1 memory in bank xxx.。测试 tests/test_tools.py 验证了缺少 bank_id / content 返回错误tags 解析为[a, b]并正确传给客户端等行为。Recall —— 按查询检索记忆在记忆库中搜索与查询相关的记忆返回results数组。字段如下字段必填默认值说明Bank ID是—要搜索的记忆库Query是—自然语言查询Budget否mid检索预算low/mid/high越高越彻底、越慢、越贵Max Tokens否4096返回结果的 token 上限Tags否—逗号分隔的标签过滤实现层面tools/recall.pybudget缺省取midmax_tokens缺省取4096返回的 JSON 消息包含results数组与count计数results中的每条记忆经_memory_to_dict序列化优先使用 Pydantic 的model_dump(exclude_noneTrue)否则回退到id/text/type三个字段有结果时输出编号列表文本无结果时输出No memories found.。参数定义同样可以在 tools/recall.yaml 中查看——注意budget是select类型low/mid/highmax_tokens是number类型。关于 Recall 的底层机制仓库文档 recall.mdx 说明Hindsight 召回时会并行运行四种检索策略——语义相似度、关键词BM25、图遍历graph traversal、时间temporal——再将结果融合、重排成单一排序列表返回的是结构化事实而非原始文档query 超过 500 token 会被拒绝。Reflect —— 对记忆库提出综合问题基于记忆库返回 LLM 综合生成的答案返回text字段。字段如下字段必填默认值说明Bank ID是—要查询的记忆库Query是—要回答的问题Budget否low预算low/mid/high实现见 tools/reflect.py与 Recall 不同Reflect 的budget缺省取low源码注释说明Reflect 涉及 LLM 综合生成、成本更高因此默认用低预算返回的 JSON 消息包含text字段无答案时输出(no answer)。参数定义见 tools/reflect.yaml。典型工作流形态一个典型结构是在LLM 步骤之前放置Recall节点把此前历史浮现出来作为上下文在运行结束后放置Retain节点把本轮新内容写回同一个记忆库。三个工具的参数校验、错误处理与消息产出在 tests/test_tools.py 中有完整覆盖provider 层provider/hindsight.py 与 tests/test_provider.py则验证了缺少 API URL 报错带 key / 不带 key 的健康检查401 与 500 的错误消息连接错误包含 URL等场景。若需了解更底层的 API 行为可阅读 recall API 文档 与 retain API 文档。接入后能得到什么What you get因为这三个工具就是普通的 Dify 节点你可以完全不离开可视化构建器把记忆塞进 Chatflow、工作流与 Agent 应用客服支持助手—— 每张关闭的工单触发一次 Retain记录解决方案每张新工单先用 Recall 检索记忆库、浮现相似历史问题再把上下文传给 LLM 节点起草第一封回复。销售通话教练—— 每次通话后 Retain 一份通话摘要下一次准备会议前用客户姓名做一次 Recall把所有历史触点拉进每日准备文档。知识库 Agent—— 上传的文档被 Retain 存储Chatflow 用 Recall 替代仅向量库检索获得经过事实抽取、去重、具备时间感知的结果。验证记忆确实在工作Verify推荐如下验证序列运行一个以Retain节点结尾、向某记忆库写入内容的工作流存储一条独特的事实——例如一个决策或一个客户细节运行第二个工作流其中Recall节点读取同一个 Bank ID用查询语句检索第一步存储的事实确认该事实出现在results数组中。如果 Recall 节点浮现了此前运行存储的内容说明整套配置已经生效。常见错误Common mistakesBank ID 不匹配Recall 与 Retain 只有在使用相同 Bank ID时才共享记忆。如果后续的 Recall 返回空结果请先检查它指向的 Bank 是否是之前 Retain 写入的那个。在 Retain 之后立刻 RecallRetain 在调用返回后异步抽取事实。如果 Retain 刚结束就立刻 Recall事实可能尚未进入可检索状态需要稍候片刻再查询。凭据缺失或错误工具报错时确认API URL指向你的后端API Key已正确填写Hindsight Cloud 必填。把 Reflect 当成 Recall 用Recall 返回results记忆数组供 LLM 步骤消费Reflect 直接返回综合生成的text答案。需要把记忆喂给 LLM 时用 Recall需要直接拿到综合答案时用 Reflect。常见问题FAQ我需要 Hindsight Cloud 吗不需要。自托管的 Hindsight 服务器同样可用——把插件的API URL指向它即可对于未鉴权的自托管实例API Key 可选。插件在 Dify 中显示在哪里安装完成后Hindsight 插件出现在工作流编辑器的Tools下。记忆的作用域如何划分按Bank ID划分。每个 Bank 都是独立的记忆存储由你决定每个工具节点从哪个 Bank 读、往哪个 Bank 写。应该用哪个工具Retain负责存储内容Recall负责在 LLM 步骤前拉取相关记忆Reflect负责对记忆库提出 LLM 综合问题。进一步探索想深入了解插件在仓库中的完整实现可通读 hindsight-integrations/dify 目录manifest.yaml、main.py、provider/、tools/、tests/想理解 Recall 的四路检索与融合重排机制阅读 Recall 架构文档想直接调用底层 API可参考 quickstart、recall 与 retain 三份接口文档仓库的examples/目录还提供了 Python / Node.js / Shell / Go 多种语言的调用示例。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考