OpenCode 接入 Hindsight 记忆插件给 AI 编程助手装上跨会话的长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读Hindsight 是一个聚焦「Agent 记忆」的开源项目而vectorize-io/opencode-hindsight是它针对 OpenCodeopencode.ai 的命令行 AI 编程代理推出的官方记忆插件。插件以 OpenCode plugin 的形式运行为 Agent 提供三个显式调用的自定义工具hindsight_retain/hindsight_recall/hindsight_reflect并在会话空闲时自动保存对话、在会话启动时自动注入相关记忆、在上下文压缩时保住关键信息。本文以 hindsight-integrations/opencode/README.md 为骨架结合插件源码与测试用例完整讲解安装启用、Hindsight Cloud 与自托管接入、全部配置项与优先级、动态 memory bank 设计以及底层工具与 hook 的实现原理读完即可在自己的 OpenCode 环境中落地一套可持续累积的长期记忆系统。插件核心能力一览从 src/index.ts 的模块注释可以看到插件围绕四条能力展开自定义工具Custom tools向 Agent 暴露hindsight_retain、hindsight_recall、hindsight_reflect三个工具Agent 可以在需要时显式调用——保存事实、搜索记忆、生成综合回答。自动保留Auto-retain监听 OpenCode 的session.idle事件把整段会话按规则写入 Hindsight。记忆注入Memory injection新会话启动时通过experimental.chat.system.transform钩子召回相关记忆并拼入 system prompt。压缩保全Compaction hook在 OpenCode 触发上下文压缩experimental.session.compacting时先把已有会话内容写入记忆再把相关记忆注入压缩上下文避免关键信息随窗口裁剪丢失。从包元数据看插件名为vectorize-io/opencode-hindsight版本 0.2.8要求 Node.js 22运行时依赖opencode-ai/pluginOpenCode 插件 SDK与vectorize-io/hindsight-clientHindsight 官方 TypeScript 客户端见 package.json。快速开始插件默认连接Hindsight Cloudhttps://api.hindsight.vectorize.io因此最快路径只需要两步启用插件、提供 API Key。第 1 步启用插件在项目级opencode.json或全局~/.config/opencode/opencode.json中加入{ $schema: https://opencode.ai/config.json, plugin: [vectorize-io/opencode-hindsight] }OpenCode 会在启动时自动安装plugin数组中列出的插件无需手动执行npm install。第 2 步配置 Hindsight Cloud API Keyexport HINDSIGHT_API_TOKENyour-api-key # 可选覆盖默认 memory bank ID默认为 opencode export HINDSIGHT_BANK_IDmy-project完成这两步后插件即可对 Cloud 上的 bank 进行读写。注意hindsightApiUrl始终会被解析为默认值插件初始化不会因为 URL 未设置而失败真正的鉴权失败会在调用时由服务端返回清晰可操作的错误而不是静默禁用插件见 src/index.ts。使用自托管的 Hindsight 实例把HINDSIGHT_API_URL指向你自己的服务此时 API Key 变为可选export HINDSIGHT_API_URLhttp://localhost:8888也可以直接在opencode.json里以插件选项方式内联配置{ $schema: https://opencode.ai/config.json, plugin: [ [ vectorize-io/opencode-hindsight, { hindsightApiUrl: http://localhost:8888 } ] ] }配置详解插件的配置分为三个层次插件选项写在opencode.json、配置文件~/.hindsight/opencode.json和环境变量。插件选项Plugin Options在opencode.json中把插件写成「包名 选项对象」的二元组即可传入选项{ plugin: [ [ vectorize-io/opencode-hindsight, { hindsightApiUrl: http://localhost:8888, bankId: my-project, autoRecall: true, autoRetain: true, recallBudget: mid } ] ] }配置文件Config File创建~/.hindsight/opencode.json可以保存持久化配置适合与仓库内配置解耦的全局偏好{ hindsightApiUrl: http://localhost:8888, hindsightApiToken: your-api-key, recallBudget: mid, retainEveryNTurns: 3, debug: false }环境变量Environment Variables以下为 README 给出的完整环境变量表以及各变量的默认值VariableDescriptionDefaultHINDSIGHT_API_URLHindsight API base URLhttps://api.hindsight.vectorize.ioHINDSIGHT_API_TOKENAPI key for authentication(none — required for Hindsight Cloud)HINDSIGHT_BANK_IDStatic memory bank IDopencodeHINDSIGHT_AGENT_NAMEAgent name for dynamic bank IDsopencodeHINDSIGHT_AUTO_RECALLAuto-recall on session starttrueHINDSIGHT_AUTO_RETAINAuto-retain on session idletrueHINDSIGHT_RETAIN_MODEfull-sessionorlast-turnfull-sessionHINDSIGHT_RECALL_BUDGETRecall budget:low,mid,highmidHINDSIGHT_RECALL_MAX_TOKENSMax tokens for recall results1024HINDSIGHT_RECALL_TAGSComma-separated, filter recalls(none)HINDSIGHT_RECALL_TAGS_MATCHTag match mode:any,all,any_strict,all_strictanyHINDSIGHT_RETAIN_TAGSComma-separated, added to every retain(none)HINDSIGHT_DYNAMIC_BANK_IDEnable dynamic bank ID derivationfalseHINDSIGHT_BANK_MISSIONBank mission/context(none)关于 Debug 日志调试开关只通过配置文件开启opencode.json插件选项或~/.hindsight/opencode.json中的debug: true故意不提供HINDSIGHT_DEBUG环境变量——因为 OpenCode 的插件运行时尤其在 Windows 上环境变量并不可靠。无论debug是否开启错误信息与解析后的 API URL / bank 都会输出debug只是额外增加详细追踪。所有插件日志都汇入 OpenCode 的日志流servicehindsight可通过--print-logs或在 OpenCode 的日志文件中查看。源码级补充配置项比 README 更细实际配置结构比 README 展示的更多。从 src/config.ts 的HindsightConfig接口可以看到更多可调项它们的默认值见 DEFAULTS配置键默认值作用recallTypes[world, experience]召回哪些记忆类型recallContextTurns1构造召回查询时携带多少轮历史上下文recallMaxQueryChars800召回查询最大字符数超限优先保留最新用户消息见 content.ts 的截断策略recallPromptPreamble一段引导语注入 system prompt 前附带的提示文本提示模型「只使用与当前对话直接相关的记忆」retainEveryNTurns3每 N 个用户轮次自动保留一次retainOverlapTurns2滑窗模式下与上一片的重叠轮数retainContextopencoderetain 时的上下文标签retainMetadata{}每次 retain 附带的元数据bankIdPrefixbank ID 前缀最终形如prefix-bankretainMissionnull与bankMission配合指定 retain 阶段的使命agentNameopencode动态 bank ID 中agent维度取值debugfalse调试日志开关另外环境变量实际支持的范围也比表格更广例如HINDSIGHT_RECALL_MAX_QUERY_CHARS、HINDSIGHT_RECALL_CONTEXT_TURNS、HINDSIGHT_RETAIN_EVERY_N_TURNS、HINDSIGHT_RETAIN_OVERLAP_TURNS、HINDSIGHT_BANK_ID_PREFIX、HINDSIGHT_RECALL_PROMPT_PREAMBLE、HINDSIGHT_RETAIN_CONTEXT等都已注册见 config.ts。布尔环境变量按true/1/yes不区分大小写解析为真整型解析失败则忽略该变量见 castEnv。逗号分隔的HINDSIGHT_RECALL_TAGS/HINDSIGHT_RETAIN_TAGS会先 trim 再过滤空串见 config.ts。loadConfig还会对三类枚举字段做防呆校验非法值会在控制台告警并回退到默认值见 config.tsretainMode仅允许full-session、last-turn否则回退full-sessionrecallTagsMatch仅允许any、all、any_strict、all_strict否则回退anyrecallBudget仅允许low、mid、high否则回退mid。HINDSIGHT_DEBUG不生效这一点有专门测试覆盖即使设置了该环境变量loadConfig().debug仍为false见 config.test.ts。配置优先级Configuration Priority设置按如下顺序加载后加载者覆盖先加载者内置默认值~/.hindsight/opencode.jsonopencode.json中的插件选项环境变量该顺序在 loadConfig 中逐层实现并有测试验证「环境变量覆盖插件选项」「插件选项覆盖默认值」见 config.test.ts。三个记忆工具插件向 Agent 注册三个工具定义见 src/tools.ts其能力如下hindsight_retain保存信息到长期记忆。Agent 用它记录重要事实、用户偏好、项目上下文与决策。参数为content必填要求具体且自包含尽量写清 who / what / when / why和可选的context。执行时底层调用 HindsightClient 的retain见 tools.ts。hindsight_recall搜索长期记忆。Agent 在回答「过去聊过什么、用户偏好、项目历史」等需要先验上下文的问题前应主动调用。参数为query自然语言查询。底层调用client.recall并把召回结果按- 文本 [type] (日期)的格式拼装返回同时带上 UTC 当前时间见 tools.ts。召回还支持按budget、maxTokens、types、tags/tagsMatch过滤最终透传给 TypeScript 客户端的 recall 接口。hindsight_reflect基于长期记忆生成综合回答。与 recall 返回「原始记忆片段」不同reflect 会综合多条记忆产出一段连贯的总结适合回答「关于这个用户你都知道些什么」「总结一下我们的项目决策」这类问题。参数为query与可选context底层调用client.reflect见 tools.ts服务端实现对应 TypeScript 客户端的 reflect 接口。三个工具还共享两个细节若配置了bankMission首次调用会先确保 bank 已创建并写入使命ensureBankMissionretain 时若配置了retainTags/retainMetadata会一并随记忆写入。自动记忆hook 如何工作插件默认行为不止于显式工具还包括三套自动化钩子实现见 src/hooks.ts。session.idle 自动保留当 OpenCode 触发session.idle事件时插件会通过 OpenCode client 拉取该会话的全部消息opencodeClient.session.messages只保留user/assistant角色下的文本部分见 hooks.ts统计用户轮次只有距上次保留新增了至少retainEveryNTurns轮时才真正执行保留避免重复写入见 handleSessionIdle按retainMode决定保留范围并调用retainfull-session默认保留整段会话且以sessionId作为documentId——同一会话的多次保留会 upsert 到同一文档last-turn / 滑窗只保留最后retainEveryNTurns retainOverlapTurns轮按用户消息边界切分并用sessionId-时间戳作为每次唯一的documentId形成分片见 retainSession。写入的 transcript 使用[role: user]...[user:end]标记结构见 prepareRetentionTranscript并会先剥离hindsight_memories/relevant_memories块防止「记忆又被当作新记忆存入」的反馈循环见 stripMemoryTags。保留调用还附带context、tags与metadata至少包含session_id并以async: true异步提交。对应的行为有专门测试覆盖见 hooks.test.ts。会话启动自动召回记忆注入新会话启动时的记忆注入不依赖session.created事件而是由experimental.chat.system.transform钩子驱动。原因在源码注释里写得很清楚session.created与system.transform的相对触发顺序是 OpenCode 未文档化的实现细节且在不同版本间存在差异依赖它会导致召回被静默关闭见 hooks.ts。具体流程见 systemTransformrecalledSessions集合记录已注入过的会话保证每个会话只注入一次只有 API 调用成功即便结果为空才标记瞬时故障会在下一条消息到来时重试直接拉取会话消息用用户最新消息 前recallContextTurns轮历史动态构造查询没有用户消息时退回固定查询project context and recent work——这比固定字符串更能贴合用户实际问的内容查询超过recallMaxQueryChars时截断优先保留最新用户消息、从旧到新丢弃上下文行见 truncateRecallQuery把结果拼成hindsight_memories.../hindsight_memories块含 recall preamble 与当前 UTC 时间追加到system[0]而不是新增 system 段——因为 OpenCode 会把每个system[]条目作为独立 system message 发出部分模型只认第一条追加到首位才能保证召回被模型看到。上下文压缩保全OpenCode 在上下文超长时会触发压缩此时experimental.session.compacting钩子做两件事见 compacting压缩前先保留把当前会话消息先写入记忆复用retainSession逻辑并清掉lastRetainedTurn记录避免压缩后消息变少导致后续 idle 保留被旧的轮次计数挡住把相关记忆注入压缩上下文用最后一条用户消息动态构造查询并召回把结果 push 进output.context让压缩产物也携带历史记忆。这样即便上下文窗口被裁剪关键信息也已经沉淀到长期记忆中且压缩后新生成的上下文仍能看到相关记忆。动态 Bank ID多项目记忆隔离默认情况下所有会话写入同一个静态 bankopencode。对于多项目/多用户场景可以开启动态 bank IDexport HINDSIGHT_DYNAMIC_BANK_IDtrue开启后 bank ID 由粒度字段组合而成默认粒度是agent::project支持的字段有agent、project、gitProject、channel、user实现见 src/bank.ts。project 与 gitProject 的区别project取工作目录的 basename。它的副作用是同一仓库的不同 git worktree 因路径不同会得到不同的 bank ID记忆互不相通。gitProject通过git rev-parse --git-common-dir解析到主 worktree 的 basename因此同一仓库的所有 linked worktree 共享同一个 bank当 git 不可用或目录不是仓库时回退到工作目录 basename。想让 worktree 之间共享记忆就用gitProject替换project{ dynamicBankId: true, dynamicBankGranularity: [agent, gitProject] }维度解析细节agent取配置的agentName默认opencodechannel取环境变量HINDSIGHT_CHANNEL_ID缺省为defaultuser取环境变量HINDSIGHT_USER_ID缺省为anonymous非法粒度字段会在控制台告警最终该段解析为unknowngitProject采用惰性解析只有粒度里包含该字段时才 spawn git 命令见 bank.ts对应测试验证了静态模式与不含gitProject的粒度下不会调用 git见 bank.test.ts。重要限制bank ID 在插件加载时OpenCode 启动前设置的环境变量一次性推导这些维度是进程级的——运行中的 OpenCode 进程内不会随会话变化。要做多用户隔离需在每个用户的 OpenCode 实例启动前设置环境变量export HINDSIGHT_CHANNEL_IDslack-general export HINDSIGHT_USER_IDuser123bank ID 推导、worktree 共享、bare 仓库等边界情况在 bank.test.ts 中有系统测试例如主仓库与 linked worktree 得到相同 bank ID、隐藏 bare 仓库.bare解析为 hub 名称、gitProject在非 git 目录回退目录名等。附加能力bankIdPrefix 与 bankMissionbankIdPrefix静态模式下拼成prefix-bank动态模式下拼成prefix-agent::projectbankMission首次使用某 bank 时自动调用createBank写入reflectMission与可选retainMission之后用进程内Set记住已设置过的 bank避免重复调用设置失败不会中断主流程见 ensureBankMission测试见 bank.test.ts。本地开发与构建插件源码位于仓库的 hindsight-integrations/opencode 目录采用 TypeScript vitest tsup 工程化npm install npm test # 运行单元测试vitest npm run build # 构建到 dist/test:e2e设置HINDSIGHT_LIVE_E2E1后运行真实服务端联测见 package.json 的 scripts测试覆盖包括配置加载与优先级config.test.ts、bank ID 推导与 missionbank.test.ts、内容处理与截断content.test.ts、hook 行为hooks.test.ts、工具定义tools.test.ts、日志logger.test.ts以及端到端流程e2e.test.ts。日志与排障所有日志通过 OpenCode 的 server log API 写入其日志流标识为servicehindsight可通过--print-logs或日志文件查看OpenCode client 不可用时回退到console.error见 src/logger.ts。error/warn/info级别始终输出——包括初始化时解析到的 API URL、bank、是否已鉴权等关键信息见 index.ts这是排查「记忆没存上」最常见的原因连到了错误的实例只有debug级别需要显式开启配置文件中的debug: true。常见排障路径记忆没有保存先看插件初始化日志确认api/bank是否指向预期实例Cloud 场景报鉴权错误确认HINDSIGHT_API_TOKEN已设置自托管场景确认HINDSIGHT_API_URL可达例如http://localhost:8888多项目记忆串了检查HINDSIGHT_DYNAMIC_BANK_ID与dynamicBankGranularity配置是否符合预期。总结vectorize-io/opencode-hindsight以「显式工具 自动钩子」双轨方式把 Hindsight 的长期记忆能力接入 OpenCodeAgent 主动用hindsight_retain/hindsight_recall/hindsight_reflect读写记忆插件在后台于会话空闲、会话启动、上下文压缩三个关键节点自动完成保留与召回。配置上支持opencode.json插件选项、~/.hindsight/opencode.json配置文件与环境变量三层来源默认值 配置文件 插件选项 环境变量并可通过动态 bank IDagent::project/gitProject/channel/user等粒度实现多项目、多 worktree、多用户的记忆隔离。结合 README 与 src 目录下的源码和测试可以进一步理解其底层调用链retain/recall/reflect均通过 vectorize-io/hindsight-client 与 Hindsight 服务端通信从而按需定制记忆策略。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
