用 vectorize-io/hindsight-eliza 为 elizaOS Agent 接入 Hindsight 长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南围绕 Hindsight 官方提供的 elizaOS 集成插件vectorize-io/hindsight-eliza源码位于 hindsight-integrations/eliza讲解如何通过 Provider 与 Evaluator 两个组件为基于 elizaOS 的 Agent 叠加由 Hindsight 支撑的长期记忆能力。读完本文你将掌握插件的安装、配置、全部可调参数以及底层 recall / retain 调用链与容错设计可直接在自己的角色卡character中落地使用。一、插件定位一条插件两条记忆通路vectorize-io/hindsight-eliza的目标非常聚焦给 elizaOS Agent 提供会学习的长期记忆。它不做任何侵入式改造而是以标准 elizaOS 插件的形式注册两个组件HINDSIGHT_MEMORYprovider召回侧——在每次模型调用之前用当前消息文本向 Hindsight 发起语义召回把相关记忆以 Markdown 列表的形式注入到 Prompt 上下文中HINDSIGHT_RETAINevaluator留存侧——在每一轮对话处理完之后把会话消息写入 Hindsight 长期记忆库。两个组件默认同时启用且叠加在 elizaOS 现有记忆机制之上不冲突、不替换。最关键的设计原则是失败安全fail safeHindsight 服务一旦不可用插件会静默吞掉错误Agent 依然能正常响应绝不会因为记忆服务故障而阻塞对话。从源码看插件的组装逻辑位于 plugin.tscreateHindsightPlugin根据recall.enabled/retain.enabled决定是否挂载 provider 与 evaluator最终返回一个标准的 elizaOSPlugin对象name为vectorize-io/hindsight-eliza。二、安装与依赖要求在 Agent 项目中安装插件本体及其客户端依赖npm install vectorize-io/hindsight-eliza vectorize-io/hindsight-client安装时需满足以下前置条件见 package.jsonpeer dependencyelizaos/core^1.7.2开发环境锁定1.7.2Node.js22engines字段要求打包与测试工具tsup构建、vitest测试、typescript ^5.7.0。需要说明的是本插件对 Hindsight 客户端采用的是结构化鸭子类型structural subset源码 client.ts 中定义的HindsightClient接口只要求recall与retain两个方法与vectorize-io/hindsight-client的真实实现签名一致但插件本身不硬依赖客户端包——因此你也可以传入任何实现了相同接口的自定义客户端。三、快速接入三步启用长期记忆插件提供了开箱即用的createHindsightPlugin工厂函数最小接入代码如下与 README 示例一致import { createHindsightPlugin } from vectorize-io/hindsight-eliza; import { Hindsight } from vectorize-io/hindsight-client; const hindsightPlugin createHindsightPlugin({ client: new Hindsight({ apiKey: process.env.HINDSIGHT_API_KEY }), recall: { budget: high, includeEntities: true }, retain: { tags: [source:eliza] }, }); export const character { name: Ada, plugins: [hindsightPlugin], };三个要点值得展开client必填传入一个 Hindsight 客户端实例通常通过HINDSIGHT_API_KEY环境变量初始化recall/retain均为可选配置块不传则使用默认值见下文参数表直接挂到角色卡插件作为标准Plugin放进character.plugins数组即可elizaOS 会自动加载 provider 与 evaluator。记忆按银行隔离bank 的解析逻辑默认情况下记忆按用户隔离存储——每条消息以message.entityId作为 bank 标识即每个用户/Agent 拥有独立的记忆空间。你也可以传入固定字符串或按消息动态求值的函数// 固定 bank所有消息读写同一个记忆库 createHindsightPlugin({ client, bank: team-bank }); // 动态 bank按房间或用户维度隔离 createHindsightPlugin({ client, bank: (message) room:${message.roomId}, });这一逻辑的实现位于 options.ts 的resolveBank函数函数形式优先调用求值非空字符串作为固定 bank否则回落到message.entityId。测试 plugin.test.ts 验证了bank: team-bank时 recall 会以team-bank作为第一个参数调用客户端。四、完整参数表一次读懂全部配置以下参数表完整覆盖 README 内容并结合 options.ts 的类型定义补充了语义说明OptionDescriptionDefaultclient一个 Hindsight 客户端实例必填必填bank固定 bank 字符串或(message) string函数message.entityIdrecall.enabled是否启用 recall providertruerecall.budget处理预算low \| mid \| high控制延迟与深度权衡midrecall.types限制召回的事实类型全部allrecall.maxTokens召回结果 token 上限API 默认recall.includeEntities是否包含实体观测entity observationsfalserecall.heading召回记忆上方渲染的标题# Relevant long-term memoriesretain.enabled是否启用 retain evaluatortrueretain.async是否异步fire-and-forget不增加对话延迟trueretain.tags附加到每条留存记忆上的标签—retain.metadata附加到每条留存记忆上的元数据—retain.includeAgentMessages是否同时留存 Agent 自己的回复false关于recall.types与budget的底层类型types支持的事实类型由 client.ts 定义为联合类型world | experience | observation。其中observation对应实体观测这也解释了为何recall.includeEntities默认关闭——开启后会把实体观测一并纳入召回结果。budget的类型为low | mid | high见 client.ts它控制 Hindsight 在召回时投入的处理强度low偏向低延迟、浅处理high偏向深度处理、更高质量的召回默认mid是两者之间的平衡点。五、召回侧原理HINDSIGHT_MEMORY Provider 的内部实现recall provider 的实现位于 provider.ts核心调用链如下空消息短路get首先取message.content?.text并 trim若无文本则直接返回空结果不会触发 recall 调用测试 provider.test.ts 验证了这一点调用客户端以resolveBank解析出的 bank、消息文本为 query携带types/maxTokens/budget/includeEntities调用client.recall(...)格式化注入formatMemories将每条结果的texttrim 后按- item的 Markdown 列表格式拼接前面加上标题默认# Relevant long-term memories整体作为 provider 的text注入 Prompt无结果时返回空字符串不渲染标题结果透传除了注入文本provider 还在返回值中携带结构化数据——values.hindsightMemoryCount为召回条数data.hindsight为完整召回响应方便后续逻辑如追踪读取。容错设计整个 recall 包裹在try/catch中任何异常包括 Hindsight 服务 503都会被吞掉返回空文本并置hindsightMemoryCount 0、把错误信息放入data.hindsightError。测试 provider.test.ts 分别验证了Error与普通字符串两种异常形态的兜底行为。这就是记忆服务故障绝不阻塞 Agent 响应的实现保证。provider 的元信息name: HINDSIGHT_MEMORY、dynamic: false在 provider.test.ts 中有对应断言。六、留存侧原理HINDSIGHT_RETAIN Evaluator 的内部实现retain evaluator 的实现位于 evaluator.ts它在每一轮对话结束后执行alwaysRun: true每轮都运行validate仅当消息content.texttrim 后非空才真正执行留存空文本、纯空白消息直接跳过handler 逻辑解析 bank 后判断触发消息是否来自 Agent 本身message.entityId runtime.agentId默认只存用户消息若触发消息来自 Agent 且未开启includeAgentMessages则跳过测试 evaluator.test.tsincludeAgentMessages: true时除用户消息外还会逐条留存本轮 Agent 的回复responses数组空文本回复同样会被跳过测试见 evaluator.test.ts。异步与失败隔离retain.async默认为true此时client.retain被 fire-and-forget 地触发handler 立即返回不会为对话增加任何延迟——即使底层 retain 永不返回测试中模拟了永不 settle 的 Promisehandler 也能正常 resolve见 evaluator.test.ts。同时所有 retain 调用都带有.catch(() undefined)同步模式下的写入失败同样不会让整轮对话报错evaluator.test.ts。留存调用会把tags与metadata一并透传给客户端evaluator.ts测试 evaluator.test.ts 验证了{ channel: discord }这类元数据会原样传递。七、进阶拆开用 Provider 与 Evaluator 自行组装如果你的使用场景只需要只召回不留存或只留存不召回createHindsightPlugin内部其实只是把两个部件拼在一起见 plugin.ts。你也可以跳过工厂函数直接使用导出的底层构造函数createHindsightProvider(client, bank, recallOptions)——返回HINDSIGHT_MEMORYprovidercreateHindsightEvaluator(client, bank, retainOptions)——返回HINDSIGHT_RETAINevaluatorresolveBank(bank, message)——bank 解析工具函数。所有公开 API 均从 index.ts 统一导出包括类型HindsightPluginOptions、RecallOptions、RetainOptions、BankResolver、HindsightClient、RecallResult、RecallResponse、RetainResponse、Budget、FactType。例如若你想做一个纯记忆写入的 Agent可以直接构造 evaluator 挂到自己的插件里而不必引入 recall provider 的开销。八、开发与验证本地构建与测试仓库内该插件是一个完整的 TypeScript 包本地开发命令见 package.jsonnpm install npm test # vitest run运行单元测试 npm run build # tsup 构建到 dist/测试套件位于 hindsight-integrations/eliza/tests共三组用例可作为理解插件行为的权威参考plugin.test.ts——验证插件默认同时注册 provider 与 evaluator、可独立禁用 recall / retain、参数透传与失败兜底provider.test.ts——覆盖默认/自定义标题渲染、空结果、空白文本过滤、bank 解析、错误吞并等 11 个场景evaluator.test.ts——覆盖异步 fire-and-forget、tags/metadata 透传、Agent 消息留存开关等 11 个场景。九、常见配置场景速查想让记忆更深recall: { budget: high, includeEntities: true }——提升召回质量并纳入实体观测只想记录、不注入recall: { enabled: false }保留纯留存管线对话延迟敏感保持retain.async: true默认留存完全异步化给记忆打来源标记retain: { tags: [source:eliza, env:prod] }便于后续按标签检索过滤多用户/多房间隔离传bank: (message) \room:${message.roomId} 实现按房间分库把 Agent 的回答也沉淀为记忆retain: { includeAgentMessages: true }。该插件遵循 MIT 许可证见 hindsight-integrations/eliza/README.md 与 package.json可直接集成到你的 elizaOS Agent 项目中。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 @vectorize-io/hindsight-eliza 为 elizaOS Agent 接入 Hindsight 长期记忆
用 vectorize-io/hindsight-eliza 为 elizaOS Agent 接入 Hindsight 长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南围绕 Hindsight 官方提供的 elizaOS 集成插件vectorize-io/hindsight-eliza源码位于 hindsight-integrations/eliza讲解如何通过 Provider 与 Evaluator 两个组件为基于 elizaOS 的 Agent 叠加由 Hindsight 支撑的长期记忆能力。读完本文你将掌握插件的安装、配置、全部可调参数以及底层 recall / retain 调用链与容错设计可直接在自己的角色卡character中落地使用。一、插件定位一条插件两条记忆通路vectorize-io/hindsight-eliza的目标非常聚焦给 elizaOS Agent 提供会学习的长期记忆。它不做任何侵入式改造而是以标准 elizaOS 插件的形式注册两个组件HINDSIGHT_MEMORYprovider召回侧——在每次模型调用之前用当前消息文本向 Hindsight 发起语义召回把相关记忆以 Markdown 列表的形式注入到 Prompt 上下文中HINDSIGHT_RETAINevaluator留存侧——在每一轮对话处理完之后把会话消息写入 Hindsight 长期记忆库。两个组件默认同时启用且叠加在 elizaOS 现有记忆机制之上不冲突、不替换。最关键的设计原则是失败安全fail safeHindsight 服务一旦不可用插件会静默吞掉错误Agent 依然能正常响应绝不会因为记忆服务故障而阻塞对话。从源码看插件的组装逻辑位于 plugin.tscreateHindsightPlugin根据recall.enabled/retain.enabled决定是否挂载 provider 与 evaluator最终返回一个标准的 elizaOSPlugin对象name为vectorize-io/hindsight-eliza。二、安装与依赖要求在 Agent 项目中安装插件本体及其客户端依赖npm install vectorize-io/hindsight-eliza vectorize-io/hindsight-client安装时需满足以下前置条件见 package.jsonpeer dependencyelizaos/core^1.7.2开发环境锁定1.7.2Node.js22engines字段要求打包与测试工具tsup构建、vitest测试、typescript ^5.7.0。需要说明的是本插件对 Hindsight 客户端采用的是结构化鸭子类型structural subset源码 client.ts 中定义的HindsightClient接口只要求recall与retain两个方法与vectorize-io/hindsight-client的真实实现签名一致但插件本身不硬依赖客户端包——因此你也可以传入任何实现了相同接口的自定义客户端。三、快速接入三步启用长期记忆插件提供了开箱即用的createHindsightPlugin工厂函数最小接入代码如下与 README 示例一致import { createHindsightPlugin } from vectorize-io/hindsight-eliza; import { Hindsight } from vectorize-io/hindsight-client; const hindsightPlugin createHindsightPlugin({ client: new Hindsight({ apiKey: process.env.HINDSIGHT_API_KEY }), recall: { budget: high, includeEntities: true }, retain: { tags: [source:eliza] }, }); export const character { name: Ada, plugins: [hindsightPlugin], };三个要点值得展开client必填传入一个 Hindsight 客户端实例通常通过HINDSIGHT_API_KEY环境变量初始化recall/retain均为可选配置块不传则使用默认值见下文参数表直接挂到角色卡插件作为标准Plugin放进character.plugins数组即可elizaOS 会自动加载 provider 与 evaluator。记忆按银行隔离bank 的解析逻辑默认情况下记忆按用户隔离存储——每条消息以message.entityId作为 bank 标识即每个用户/Agent 拥有独立的记忆空间。你也可以传入固定字符串或按消息动态求值的函数// 固定 bank所有消息读写同一个记忆库 createHindsightPlugin({ client, bank: team-bank }); // 动态 bank按房间或用户维度隔离 createHindsightPlugin({ client, bank: (message) room:${message.roomId}, });这一逻辑的实现位于 options.ts 的resolveBank函数函数形式优先调用求值非空字符串作为固定 bank否则回落到message.entityId。测试 plugin.test.ts 验证了bank: team-bank时 recall 会以team-bank作为第一个参数调用客户端。四、完整参数表一次读懂全部配置以下参数表完整覆盖 README 内容并结合 options.ts 的类型定义补充了语义说明OptionDescriptionDefaultclient一个 Hindsight 客户端实例必填必填bank固定 bank 字符串或(message) string函数message.entityIdrecall.enabled是否启用 recall providertruerecall.budget处理预算low \| mid \| high控制延迟与深度权衡midrecall.types限制召回的事实类型全部allrecall.maxTokens召回结果 token 上限API 默认recall.includeEntities是否包含实体观测entity observationsfalserecall.heading召回记忆上方渲染的标题# Relevant long-term memoriesretain.enabled是否启用 retain evaluatortrueretain.async是否异步fire-and-forget不增加对话延迟trueretain.tags附加到每条留存记忆上的标签—retain.metadata附加到每条留存记忆上的元数据—retain.includeAgentMessages是否同时留存 Agent 自己的回复false关于recall.types与budget的底层类型types支持的事实类型由 client.ts 定义为联合类型world | experience | observation。其中observation对应实体观测这也解释了为何recall.includeEntities默认关闭——开启后会把实体观测一并纳入召回结果。budget的类型为low | mid | high见 client.ts它控制 Hindsight 在召回时投入的处理强度low偏向低延迟、浅处理high偏向深度处理、更高质量的召回默认mid是两者之间的平衡点。五、召回侧原理HINDSIGHT_MEMORY Provider 的内部实现recall provider 的实现位于 provider.ts核心调用链如下空消息短路get首先取message.content?.text并 trim若无文本则直接返回空结果不会触发 recall 调用测试 provider.test.ts 验证了这一点调用客户端以resolveBank解析出的 bank、消息文本为 query携带types/maxTokens/budget/includeEntities调用client.recall(...)格式化注入formatMemories将每条结果的texttrim 后按- item的 Markdown 列表格式拼接前面加上标题默认# Relevant long-term memories整体作为 provider 的text注入 Prompt无结果时返回空字符串不渲染标题结果透传除了注入文本provider 还在返回值中携带结构化数据——values.hindsightMemoryCount为召回条数data.hindsight为完整召回响应方便后续逻辑如追踪读取。容错设计整个 recall 包裹在try/catch中任何异常包括 Hindsight 服务 503都会被吞掉返回空文本并置hindsightMemoryCount 0、把错误信息放入data.hindsightError。测试 provider.test.ts 分别验证了Error与普通字符串两种异常形态的兜底行为。这就是记忆服务故障绝不阻塞 Agent 响应的实现保证。provider 的元信息name: HINDSIGHT_MEMORY、dynamic: false在 provider.test.ts 中有对应断言。六、留存侧原理HINDSIGHT_RETAIN Evaluator 的内部实现retain evaluator 的实现位于 evaluator.ts它在每一轮对话结束后执行alwaysRun: true每轮都运行validate仅当消息content.texttrim 后非空才真正执行留存空文本、纯空白消息直接跳过handler 逻辑解析 bank 后判断触发消息是否来自 Agent 本身message.entityId runtime.agentId默认只存用户消息若触发消息来自 Agent 且未开启includeAgentMessages则跳过测试 evaluator.test.tsincludeAgentMessages: true时除用户消息外还会逐条留存本轮 Agent 的回复responses数组空文本回复同样会被跳过测试见 evaluator.test.ts。异步与失败隔离retain.async默认为true此时client.retain被 fire-and-forget 地触发handler 立即返回不会为对话增加任何延迟——即使底层 retain 永不返回测试中模拟了永不 settle 的 Promisehandler 也能正常 resolve见 evaluator.test.ts。同时所有 retain 调用都带有.catch(() undefined)同步模式下的写入失败同样不会让整轮对话报错evaluator.test.ts。留存调用会把tags与metadata一并透传给客户端evaluator.ts测试 evaluator.test.ts 验证了{ channel: discord }这类元数据会原样传递。七、进阶拆开用 Provider 与 Evaluator 自行组装如果你的使用场景只需要只召回不留存或只留存不召回createHindsightPlugin内部其实只是把两个部件拼在一起见 plugin.ts。你也可以跳过工厂函数直接使用导出的底层构造函数createHindsightProvider(client, bank, recallOptions)——返回HINDSIGHT_MEMORYprovidercreateHindsightEvaluator(client, bank, retainOptions)——返回HINDSIGHT_RETAINevaluatorresolveBank(bank, message)——bank 解析工具函数。所有公开 API 均从 index.ts 统一导出包括类型HindsightPluginOptions、RecallOptions、RetainOptions、BankResolver、HindsightClient、RecallResult、RecallResponse、RetainResponse、Budget、FactType。例如若你想做一个纯记忆写入的 Agent可以直接构造 evaluator 挂到自己的插件里而不必引入 recall provider 的开销。八、开发与验证本地构建与测试仓库内该插件是一个完整的 TypeScript 包本地开发命令见 package.jsonnpm install npm test # vitest run运行单元测试 npm run build # tsup 构建到 dist/测试套件位于 hindsight-integrations/eliza/tests共三组用例可作为理解插件行为的权威参考plugin.test.ts——验证插件默认同时注册 provider 与 evaluator、可独立禁用 recall / retain、参数透传与失败兜底provider.test.ts——覆盖默认/自定义标题渲染、空结果、空白文本过滤、bank 解析、错误吞并等 11 个场景evaluator.test.ts——覆盖异步 fire-and-forget、tags/metadata 透传、Agent 消息留存开关等 11 个场景。九、常见配置场景速查想让记忆更深recall: { budget: high, includeEntities: true }——提升召回质量并纳入实体观测只想记录、不注入recall: { enabled: false }保留纯留存管线对话延迟敏感保持retain.async: true默认留存完全异步化给记忆打来源标记retain: { tags: [source:eliza, env:prod] }便于后续按标签检索过滤多用户/多房间隔离传bank: (message) \room:${message.roomId} 实现按房间分库把 Agent 的回答也沉淀为记忆retain: { includeAgentMessages: true }。该插件遵循 MIT 许可证见 hindsight-integrations/eliza/README.md 与 package.json可直接集成到你的 elizaOS Agent 项目中。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考