在 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）

1. 在 Dify 中进入Plugins → Install Plugin，安装Hindsight插件。
2. 打开 Hindsight 插件，填入API URL与API Key凭据。
3. 在 LLM 节点前放置一个Recall节点，拉取相关历史上下文。
4. 放置一个Retain节点，把新内容写入记忆库（Bank）。
5. 运行验证：确认后续运行能召回此前运行存储的内容。

为什么 Dify 需要 Hindsight

Dify 是一个可视化的工作流构建器，拥有日益丰富的工具与插件生态。但默认情况下，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: python，runner.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_TIMEOUT=120)初始化插件，即插件侧请求超时上限为 120 秒；而底层 HTTP 客户端（见下文源码分析）默认超时为 30 秒。

Step 1：安装插件

在 Dify 控制台进入Plugins → Install Plugin，三种安装渠道任选其一：

.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:8888）；api_key为密文输入框（secret-input），非必填，占位符为hsk_...，帮助文案注明"以hsk_开头，Hindsight Cloud 必填，未鉴权的自托管实例可选"。

凭据如何生效？看 tools/_client.py 的build_client实现：它从凭据字典中读取api_url并去掉末尾斜杠，读取api_key（空值视为未设置），然后构造Hindsight(base_url=..., timeout=30.0, api_key=...)客户端——只有当 API Key 存在时才传入api_key参数。配套的 tests/test_helpers.py 覆盖了"空 key 视为缺失""去除末尾斜杠"等边界行为。

如果你还没有密钥，可以注册 Hindsight Cloud 免费套餐并从控制台获取，或者自行部署一个 Hindsight 服务器。

Step 3：把工具接入工作流

插件提供三个工具，放置方式与任何 Dify 节点相同。

Retain —— 存储内容

把自由文本内容写入记忆库。字段如下：

Retain 调用返回后，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数组。字段如下：

实现层面（tools/recall.py）：budget缺省取"mid"，max_tokens缺省取4096，返回的 JSON 消息包含results数组与count计数，results中的每条记忆经_memory_to_dict序列化（优先使用 Pydantic 的model_dump(exclude_none=True)，否则回退到id/text/type三个字段）；有结果时输出编号列表文本，无结果时输出No memories found.。参数定义同样可以在 tools/recall.yaml 中查看——注意budget是select类型（low/mid/high），max_tokens是number类型。

关于 Recall 的底层机制，仓库文档 recall.mdx 说明：Hindsight 召回时会并行运行四种检索策略——语义相似度、关键词（BM25）、图遍历（graph traversal）、时间（temporal）——再将结果融合、重排成单一排序列表，返回的是结构化事实而非原始文档；query 超过 500 token 会被拒绝。

Reflect —— 对记忆库提出综合问题

基于记忆库返回 LLM 综合生成的答案，返回text字段。字段如下：

实现见 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）

推荐如下验证序列：

1. 运行一个以Retain节点结尾、向某记忆库写入内容的工作流；
2. 存储一条独特的事实——例如一个决策或一个客户细节；
3. 运行第二个工作流，其中Recall节点读取同一个 Bank ID；
4. 用查询语句检索第一步存储的事实；
5. 确认该事实出现在results数组中。

如果 Recall 节点浮现了此前运行存储的内容，说明整套配置已经生效。

常见错误（Common mistakes）

Bank ID 不匹配

Recall 与 Retain 只有在使用相同 Bank ID时才共享记忆。如果后续的 Recall 返回空结果，请先检查它指向的 Bank 是否是之前 Retain 写入的那个。

在 Retain 之后立刻 Recall

Retain 在调用返回后异步抽取事实。如果 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