Hindsight n8n 集成节点演进解析从社区节点包到零运行时依赖的 Retain / Recall / Reflect 实现【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文围绕 Hindsight 仓库中 n8n 集成节点的版本变更记录Changelog展开梳理vectorize-io/n8n-nodes-hindsight从 v0.1.1 到 v0.1.3 的演进脉络并结合仓库源码与测试深入剖析节点的三种核心操作Retain、Recall、Reflect如何被实现、打包与鉴权。读完本文你将掌握 n8n 工作流接入 Hindsight 持久化记忆的完整方案如何安装社区节点、配置 Hindsight API 凭证、理解每个操作对应的 HTTP 端点与参数以及节点为何能做到零运行时依赖。一、版本演进总览三版迭代解决了什么vectorize-io/n8n-nodes-hindsight是 Hindsight 官方发布的 n8n 社区节点包其版本变更记录位于 skills/hindsight-docs/references/changelog/integrations/n8n.md。从变更记录可以清晰看到一条演进主线版本类型核心变更0.1.1Feature / Bug Fix新增 n8n 社区节点包将 Hindsight Memory 集成进 n8n 工作流修复节点打包与鉴权使其能正确加载并发送Authorization请求头0.1.2Bug Fix同步 Hindsight 集成与近期配置变更保持文档与节点行为一致0.1.3Improvement移除对 Hindsight 客户端的运行时依赖改为直接发起 HTTP 请求提升节点可靠性与兼容性这条演进路径背后有明确的工程动机作为 n8n 社区节点分发包体积、依赖面与鉴权正确性直接决定安装成功率。v0.1.3 的“去客户端化”是关键转折——它让节点在任意 n8n 环境包括 n8n Cloud 的验证节点分发流程中都能以最小依赖运行。二、v0.1.1社区节点包诞生与鉴权修复2.1 包的形态v0.1.1 首次以 n8n 社区节点包的形式发布把 Hindsight Memory 能力封装成工作流内可直接拖拽的节点。包结构位于仓库的 hindsight-integrations/n8n 目录hindsight-integrations/n8n/ ├── credentials/ │ └── HindsightApi.credentials.ts # Hindsight API 凭证类型 ├── nodes/ │ └── Hindsight/ │ ├── Hindsight.node.ts # 节点主实现三种操作 │ └── hindsight.svg # 节点图标 ├── test/ │ ├── credentials.test.ts # 凭证测试 │ ├── node-execute.test.ts # 节点执行测试 │ └── node.test.ts # 节点描述测试 ├── index.ts # 导出节点与凭证 └── package.json # npm 包元信息包入口 index.ts 同时导出Hindsight节点与HindsightApi凭证这是 n8n 社区包的标准形态。2.2 打包与鉴权修复变更记录明确指出 v0.1.1 修复了“节点打包/鉴权使其正确加载并发送 authorization header”。从源码可以印证这两处设计打包配置package.json 的files字段只发布dist目录n8n字段声明了节点与凭证的构建产物路径dist/credentials/HindsightApi.credentials.js与dist/nodes/Hindsight/Hindsight.node.js并声明n8nNodesApiVersion: 1。构建脚本build会执行tsc并复制图标到dist。鉴权实现credentials/HindsightApi.credentials.ts 通过 n8n 的authenticate机制在每次请求自动附加请求头authenticate: IAuthenticateGeneric { type: generic, properties: { headers: { Authorization: {{ $credentials.apiKey ? Bearer $credentials.apiKey : }}, }, }, };这里的表达式正是“正确发送授权头”的代码级答案当凭证中配置了 API Key 时自动加上Bearer前缀留空自托管无需鉴权时不附加。凭证的连通性测试则请求GET {apiUrl}/health对云端与自托管部署均有效。三、v0.1.3移除客户端依赖直连 HTTPv0.1.3 是技术形态上最重要的一次迭代移除对 Hindsight 客户端的运行时依赖改为直接 HTTP 请求。这一改动在两个层面得到源码佐证零运行时依赖package.json中没有任何运行时dependencies仅有devDependenciesn8n-workflow、typescript、vitest等与peerDependenciesn8n-workflow。节点实现完全不 import Hindsight 客户端包。使用 n8n 内建 HTTP 助手Hindsight.node.ts 的注释说明了动机——所有 HTTP 调用都走 n8n 内建的httpRequestWithAuthentication助手它自动从配置的凭证中附加 Bearer 头因此包无需携带任何 HTTP 客户端依赖符合 n8n Cloud 验证节点分发的约束。执行逻辑中还有一个工程细节const baseUrl (credentials.apiUrl || ).replace(/\/$/, )会剥离 API URL 末尾的斜杠避免拼接端点时出现双斜杠。测试用例strips trailing slash from apiUrl when building request URL专门覆盖了这一行为。四、节点核心实现三种操作对应的端点与参数节点在 Hindsight.node.ts 中定义了Operation下拉框retain/recall/reflect默认retain所有操作共用必填的Bank ID字段首次使用时自动创建记忆库并针对不同操作显示不同的参数。每次执行会遍历输入的所有数据项逐项构建请求并输出结果。4.1 Retain —— 存入记忆库端点POST {apiUrl}/v1/default/banks/{bank_id}/memories字段类型必填说明Bank IDstring是目标记忆库首次使用时自动创建Contentstring多行是要存入的文本Hindsight 异步抽取结构化事实Tagsstring否逗号分隔的标签如user:alex,scope:profile请求体结构与 Hindsight 客户端的retain()方法保持一致{ items: [{ content, tags? }] }。源码中标签通过parseTags()按逗号切分、去空白、过滤空串无标签时不发送tags字段对应测试retain omits tags from item when tags is empty。返回结果包含operation_id与status等字段事实抽取在调用返回后异步进行。4.2 Recall —— 检索记忆端点POST {apiUrl}/v1/default/banks/{bank_id}/memories/recall字段类型必填默认值说明Bank IDstring是—要检索的记忆库Querystring是—自然语言查询Budgetoptions否midlow/mid/high控制检索深度Max Tokensnumber否4096返回记忆的 token 上限Tags Filterstring否空逗号分隔的标签过滤留空不过滤请求体为{ query, max_tokens, budget, tags? }测试用例验证了budget: high与tags: [pref]的正确传递。返回结构{ results: [{ text, score, ... }, ...] }可供后续节点如 OpenAI、Anthropic直接消费。4.3 Reflect —— LLM 综合作答端点POST {apiUrl}/v1/default/banks/{bank_id}/reflect字段类型必填默认值说明Bank IDstring是—要综合的记忆库Querystring是—需要基于记忆库回答的问题Budgetoptions否midlow/mid/high请求体为{ query, budget }。返回结构{ text: ..., citations: [...] }其中text是 LLM 基于记忆库综合出的答案citations为引用信息。4.4 错误处理与失败语义执行循环内对每个数据项单独 try/catch若节点启用了 n8n 的 “Continue On Fail”失败项会输出{ error: message }的 JSON 并继续处理后续项否则抛出异常终止执行。此外bankId为空时会抛出NodeOperationError测试用例throws NodeOperationError when bankId is empty覆盖未知操作同样会抛错。五、安装与凭证配置5.1 安装节点方式一n8n 界面进入Settings → Community Nodes → Install输入包名vectorize-io/n8n-nodes-hindsight方式二自托管 n8n在自定义节点目录中通过 npm 安装cd ~/.n8n/custom npm install vectorize-io/n8n-nodes-hindsight重启 n8n 后节点面板中即可看到Hindsight节点。注意包的engines字段要求 Node.js20.15。5.2 配置 Hindsight API 凭证注册 Hindsight Cloud 账号并获取 API Key密钥以hsk_开头或使用自托管部署此时 API Key 可留空。在 n8n 中新建Hindsight API凭证字段默认值说明API URLhttps://api.hindsight.vectorize.ioHindsight API 基地址自托管改为你的部署地址如http://localhost:8888API Key空云端密钥hsk_...自托管免鉴权时留空凭证定义位于 credentials/HindsightApi.credentials.ts其中test请求指向/health云端与自托管均可用于连通性校验。六、测试驱动的正确性保障节点的三个端点在 test/node-execute.test.ts 中有完整的参数化验证值得作为“节点行为说明书”阅读retain验证 URL/v1/default/banks/bank-1/memories与请求体{ items: [{ content, tags }] }recall验证 URL/v1/default/banks/bank-1/memories/recall与{ query, max_tokens, budget, tags? }的传递reflect验证 URL/v1/default/banks/bank-1/reflect与{ query, budget }边界用例空bankId抛错、continueOnFail时输出{ error }、API URL 尾斜杠剥离、空标签字段不参与请求体。这些测试不仅验证了 HTTP 形状也间接确认了 v0.1.3 之后“直接 HTTP 请求”这一架构决策的正确性——不再依赖客户端库端点契约由测试固化。七、典型工作流示例结合 skills/hindsight-docs/references/sdks/integrations/n8n.md 与 hindsight-integrations/n8n/README.mdn8n 节点最常见的落地场景有三类客服支持助手每个已关闭的 Zendesk 工单通过 Retain 存入解决方案每个新工单先用 Recall 检索记忆中相似的历史问题再把上下文传给 OpenAI 起草首条回复。销售通话教练Gong Webhook 触发 Retain 存储通话摘要每次下一次准备通话前按客户姓名 Recall 拉取全部历史触点整理成每日准备文档。个人 Slack 机器人Slack DM 触发 → 对用户问题执行 Recall → 交给 OpenAI 生成答案 → Slack 回复。机器人跨会话记住每段对话实现真正有状态的自动化。结语从 v0.1.1 的“新增社区节点包”到 v0.1.3 的“零运行时依赖直连 HTTP”vectorize-io/n8n-nodes-hindsight用三个版本完成了从“能用”到“好分发、好维护”的蜕变。对 n8n 使用者而言这意味着无需关心客户端库版本兼容只需在任意工作流中拖入节点、配置好凭证即可通过 Retain / Recall / Reflect 三个操作为原本无状态的自动化流程注入持久的长期记忆。想深入阅读实现细节可直接查看 节点源码、凭证源码 与 执行测试。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight n8n 集成节点演进解析：从社区节点包到零运行时依赖的 Retain / Recall / Reflect 实现
Hindsight n8n 集成节点演进解析从社区节点包到零运行时依赖的 Retain / Recall / Reflect 实现【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文围绕 Hindsight 仓库中 n8n 集成节点的版本变更记录Changelog展开梳理vectorize-io/n8n-nodes-hindsight从 v0.1.1 到 v0.1.3 的演进脉络并结合仓库源码与测试深入剖析节点的三种核心操作Retain、Recall、Reflect如何被实现、打包与鉴权。读完本文你将掌握 n8n 工作流接入 Hindsight 持久化记忆的完整方案如何安装社区节点、配置 Hindsight API 凭证、理解每个操作对应的 HTTP 端点与参数以及节点为何能做到零运行时依赖。一、版本演进总览三版迭代解决了什么vectorize-io/n8n-nodes-hindsight是 Hindsight 官方发布的 n8n 社区节点包其版本变更记录位于 skills/hindsight-docs/references/changelog/integrations/n8n.md。从变更记录可以清晰看到一条演进主线版本类型核心变更0.1.1Feature / Bug Fix新增 n8n 社区节点包将 Hindsight Memory 集成进 n8n 工作流修复节点打包与鉴权使其能正确加载并发送Authorization请求头0.1.2Bug Fix同步 Hindsight 集成与近期配置变更保持文档与节点行为一致0.1.3Improvement移除对 Hindsight 客户端的运行时依赖改为直接发起 HTTP 请求提升节点可靠性与兼容性这条演进路径背后有明确的工程动机作为 n8n 社区节点分发包体积、依赖面与鉴权正确性直接决定安装成功率。v0.1.3 的“去客户端化”是关键转折——它让节点在任意 n8n 环境包括 n8n Cloud 的验证节点分发流程中都能以最小依赖运行。二、v0.1.1社区节点包诞生与鉴权修复2.1 包的形态v0.1.1 首次以 n8n 社区节点包的形式发布把 Hindsight Memory 能力封装成工作流内可直接拖拽的节点。包结构位于仓库的 hindsight-integrations/n8n 目录hindsight-integrations/n8n/ ├── credentials/ │ └── HindsightApi.credentials.ts # Hindsight API 凭证类型 ├── nodes/ │ └── Hindsight/ │ ├── Hindsight.node.ts # 节点主实现三种操作 │ └── hindsight.svg # 节点图标 ├── test/ │ ├── credentials.test.ts # 凭证测试 │ ├── node-execute.test.ts # 节点执行测试 │ └── node.test.ts # 节点描述测试 ├── index.ts # 导出节点与凭证 └── package.json # npm 包元信息包入口 index.ts 同时导出Hindsight节点与HindsightApi凭证这是 n8n 社区包的标准形态。2.2 打包与鉴权修复变更记录明确指出 v0.1.1 修复了“节点打包/鉴权使其正确加载并发送 authorization header”。从源码可以印证这两处设计打包配置package.json 的files字段只发布dist目录n8n字段声明了节点与凭证的构建产物路径dist/credentials/HindsightApi.credentials.js与dist/nodes/Hindsight/Hindsight.node.js并声明n8nNodesApiVersion: 1。构建脚本build会执行tsc并复制图标到dist。鉴权实现credentials/HindsightApi.credentials.ts 通过 n8n 的authenticate机制在每次请求自动附加请求头authenticate: IAuthenticateGeneric { type: generic, properties: { headers: { Authorization: {{ $credentials.apiKey ? Bearer $credentials.apiKey : }}, }, }, };这里的表达式正是“正确发送授权头”的代码级答案当凭证中配置了 API Key 时自动加上Bearer前缀留空自托管无需鉴权时不附加。凭证的连通性测试则请求GET {apiUrl}/health对云端与自托管部署均有效。三、v0.1.3移除客户端依赖直连 HTTPv0.1.3 是技术形态上最重要的一次迭代移除对 Hindsight 客户端的运行时依赖改为直接 HTTP 请求。这一改动在两个层面得到源码佐证零运行时依赖package.json中没有任何运行时dependencies仅有devDependenciesn8n-workflow、typescript、vitest等与peerDependenciesn8n-workflow。节点实现完全不 import Hindsight 客户端包。使用 n8n 内建 HTTP 助手Hindsight.node.ts 的注释说明了动机——所有 HTTP 调用都走 n8n 内建的httpRequestWithAuthentication助手它自动从配置的凭证中附加 Bearer 头因此包无需携带任何 HTTP 客户端依赖符合 n8n Cloud 验证节点分发的约束。执行逻辑中还有一个工程细节const baseUrl (credentials.apiUrl || ).replace(/\/$/, )会剥离 API URL 末尾的斜杠避免拼接端点时出现双斜杠。测试用例strips trailing slash from apiUrl when building request URL专门覆盖了这一行为。四、节点核心实现三种操作对应的端点与参数节点在 Hindsight.node.ts 中定义了Operation下拉框retain/recall/reflect默认retain所有操作共用必填的Bank ID字段首次使用时自动创建记忆库并针对不同操作显示不同的参数。每次执行会遍历输入的所有数据项逐项构建请求并输出结果。4.1 Retain —— 存入记忆库端点POST {apiUrl}/v1/default/banks/{bank_id}/memories字段类型必填说明Bank IDstring是目标记忆库首次使用时自动创建Contentstring多行是要存入的文本Hindsight 异步抽取结构化事实Tagsstring否逗号分隔的标签如user:alex,scope:profile请求体结构与 Hindsight 客户端的retain()方法保持一致{ items: [{ content, tags? }] }。源码中标签通过parseTags()按逗号切分、去空白、过滤空串无标签时不发送tags字段对应测试retain omits tags from item when tags is empty。返回结果包含operation_id与status等字段事实抽取在调用返回后异步进行。4.2 Recall —— 检索记忆端点POST {apiUrl}/v1/default/banks/{bank_id}/memories/recall字段类型必填默认值说明Bank IDstring是—要检索的记忆库Querystring是—自然语言查询Budgetoptions否midlow/mid/high控制检索深度Max Tokensnumber否4096返回记忆的 token 上限Tags Filterstring否空逗号分隔的标签过滤留空不过滤请求体为{ query, max_tokens, budget, tags? }测试用例验证了budget: high与tags: [pref]的正确传递。返回结构{ results: [{ text, score, ... }, ...] }可供后续节点如 OpenAI、Anthropic直接消费。4.3 Reflect —— LLM 综合作答端点POST {apiUrl}/v1/default/banks/{bank_id}/reflect字段类型必填默认值说明Bank IDstring是—要综合的记忆库Querystring是—需要基于记忆库回答的问题Budgetoptions否midlow/mid/high请求体为{ query, budget }。返回结构{ text: ..., citations: [...] }其中text是 LLM 基于记忆库综合出的答案citations为引用信息。4.4 错误处理与失败语义执行循环内对每个数据项单独 try/catch若节点启用了 n8n 的 “Continue On Fail”失败项会输出{ error: message }的 JSON 并继续处理后续项否则抛出异常终止执行。此外bankId为空时会抛出NodeOperationError测试用例throws NodeOperationError when bankId is empty覆盖未知操作同样会抛错。五、安装与凭证配置5.1 安装节点方式一n8n 界面进入Settings → Community Nodes → Install输入包名vectorize-io/n8n-nodes-hindsight方式二自托管 n8n在自定义节点目录中通过 npm 安装cd ~/.n8n/custom npm install vectorize-io/n8n-nodes-hindsight重启 n8n 后节点面板中即可看到Hindsight节点。注意包的engines字段要求 Node.js20.15。5.2 配置 Hindsight API 凭证注册 Hindsight Cloud 账号并获取 API Key密钥以hsk_开头或使用自托管部署此时 API Key 可留空。在 n8n 中新建Hindsight API凭证字段默认值说明API URLhttps://api.hindsight.vectorize.ioHindsight API 基地址自托管改为你的部署地址如http://localhost:8888API Key空云端密钥hsk_...自托管免鉴权时留空凭证定义位于 credentials/HindsightApi.credentials.ts其中test请求指向/health云端与自托管均可用于连通性校验。六、测试驱动的正确性保障节点的三个端点在 test/node-execute.test.ts 中有完整的参数化验证值得作为“节点行为说明书”阅读retain验证 URL/v1/default/banks/bank-1/memories与请求体{ items: [{ content, tags }] }recall验证 URL/v1/default/banks/bank-1/memories/recall与{ query, max_tokens, budget, tags? }的传递reflect验证 URL/v1/default/banks/bank-1/reflect与{ query, budget }边界用例空bankId抛错、continueOnFail时输出{ error }、API URL 尾斜杠剥离、空标签字段不参与请求体。这些测试不仅验证了 HTTP 形状也间接确认了 v0.1.3 之后“直接 HTTP 请求”这一架构决策的正确性——不再依赖客户端库端点契约由测试固化。七、典型工作流示例结合 skills/hindsight-docs/references/sdks/integrations/n8n.md 与 hindsight-integrations/n8n/README.mdn8n 节点最常见的落地场景有三类客服支持助手每个已关闭的 Zendesk 工单通过 Retain 存入解决方案每个新工单先用 Recall 检索记忆中相似的历史问题再把上下文传给 OpenAI 起草首条回复。销售通话教练Gong Webhook 触发 Retain 存储通话摘要每次下一次准备通话前按客户姓名 Recall 拉取全部历史触点整理成每日准备文档。个人 Slack 机器人Slack DM 触发 → 对用户问题执行 Recall → 交给 OpenAI 生成答案 → Slack 回复。机器人跨会话记住每段对话实现真正有状态的自动化。结语从 v0.1.1 的“新增社区节点包”到 v0.1.3 的“零运行时依赖直连 HTTP”vectorize-io/n8n-nodes-hindsight用三个版本完成了从“能用”到“好分发、好维护”的蜕变。对 n8n 使用者而言这意味着无需关心客户端库版本兼容只需在任意工作流中拖入节点、配置好凭证即可通过 Retain / Recall / Reflect 三个操作为原本无状态的自动化流程注入持久的长期记忆。想深入阅读实现细节可直接查看 节点源码、凭证源码 与 执行测试。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考