hindsight-openclaw 0.6 实战指南OpenClaw 持久化记忆插件的设置向导、按渠道记忆库与可靠性升级【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightvectorize-io/hindsight-openclaw0.6 是 Hindsight OpenClaw 记忆插件的一次重要版本更新用交互式设置向导取代手工环境变量配置把全部插件设置收敛进openclaw.json同时带来按渠道隔离的记忆库Memory Bank、外部 Hindsight API 后端、召回注入位置控制、JSONL 本地保留队列与会话过滤等能力。本文以 0.6 发布说明为骨架结合仓库内插件源码hindsight-integrations/openclaw逐项拆解每个新特性的配置方式、默认值与底层实现帮助你在几分钟内完成从零到可用的持久化记忆接入并理解升级路径与排障要点。Setup Wizard一条命令完成记忆接入在 0.6.0 之前接入hindsight-openclaw需要在正确的位置设置正确的环境变量0.6.0 将其替换为交互式向导npx --package vectorize-io/hindsight-openclaw hindsight-openclaw-setup向导会引导你选择三种运行模式之一Cloud推荐直连托管的 Hindsight Cloud 服务。只需粘贴 Cloud API Token无需任何本地基础设施External API连接自托管的 Hindsight 服务端。提示输入 URL 与可选 TokenEmbedded daemon在本机拉起一个本地hindsight-embed守护进程。提示选择 LLM 提供商并输入 API Key。向导完成后会把结果写入~/.openclaw/openclaw.json之后openclaw gateway启动时自动读取该配置。针对脚本化或 CI 场景向导同样支持非交互模式# Cloud 模式 npx --package vectorize-io/hindsight-openclaw hindsight-openclaw-setup \ --mode cloud --token hsk_your_cloud_token # Embedded 模式 OpenAI npx --package vectorize-io/hindsight-openclaw hindsight-openclaw-setup \ --mode embedded --provider openai --api-key sk-... # Embedded 模式 Claude Code通过 Claude Code CLI 认证无需单独 API Key npx --package vectorize-io/hindsight-openclaw hindsight-openclaw-setup \ --mode embedded --provider claude-code向导的源码级实现细节从源码看向导的实现被拆成了两个模块便于单元测试与安全审计setup.ts 是clack/prompts驱动的 CLI 入口负责交互式 TUI 与命令行参数解析setup-lib.ts 承载全部纯逻辑配置读写、三种模式的应用与凭证处理。几个值得注意的实现事实对应 setup-lib.tsNO_KEY_PROVIDERS集合claude-code、github-copilot、openai-codex、ollama四类提供商无需 API Key。选择这些提供商时向导会直接删除llmApiKey字段而不是要求输入凭证两种落盘形式既可以把 Token 明文内联写入openclaw.json交互模式默认粘贴时会被掩码显示也可以用--token-env/--api-key-env指定环境变量名落盘为SecretRef{ source: env, provider: default, id: ... }由 OpenClaw 在启动时解析适合 CI 与生产环境自动写入hooks.allowConversationAccess: trueOpenClaw 2026.4.24 会阻止非内置插件使用会话类 hook如触发 retain 的agent_end若不显式声明该字段插件看似加载成功但 hook 被静默丢弃、记忆永远不会被保留。向导每次运行都会补齐此字段除非用户显式设为false自动加入plugins.allow白名单避免 OpenClaw 2026.2.19 在启动时对非内置插件打印告警配置写入采用原子替换先写临时文件再rename避免写入中途崩溃破坏openclaw.json模式切换自动清理残留字段applyCloudMode/applyApiMode会清空本地 LLM 相关字段applyEmbeddedMode会清空外部 API 相关字段防止切换模式后残留陈旧配置。关键前提向导中配置的 LLM仅用于记忆抽取memory extraction。你的 OpenClaw Agent 本身使用什么模型由 OpenClaw 侧单独配置两者互不影响。从零开始的完整安装与配置教程可参考仓库内文档 Adding Persistent Memory to OpenClaw with Hindsight。Config Overhaul配置全面迁移至 openclaw.json破坏性变更0.6.0 之前插件配置来自环境变量这导致脚本化配置别扭且设置散落在 shell 配置文件中而非 OpenClaw 配置旁边。0.6.0 起所有配置统一放在~/.openclaw/openclaw.json的插件条目下{ plugins: { entries: { hindsight-openclaw: { enabled: true, config: { hindsightApiUrl: http://localhost:9077, provider: openai, model: gpt-4o-mini, apiKey: sk-... } } } } }注意这是发布文档中的示例键名。仓库当前版本 README 与 types.ts 中实际使用的字段名为llmProvider/llmModel/llmApiKey详见下文「升级路径」的字段对照表配置时请以当前版本的字段名为准。升级迁移对照如果你之前设置了HINDSIGHT_EMBED_API_URL、HINDSIGHT_PROVIDER之类的环境变量请把值搬进上面的config块。仓库 README.md 给出了 0.5.x → 0.6.0 的完整字段映射核心几条旧0.5.x新0.6.0OPENAI_API_KEY…自动探测config.llmProvideropenaiconfig.llmApiKey配置为SecretRef--ref-source env --ref-id OPENAI_API_KEYHINDSIGHT_API_LLM_PROVIDER…config.llmProvider…HINDSIGHT_API_LLM_MODEL…config.llmModel…HINDSIGHT_API_LLM_API_KEY…config.llmApiKey配置为SecretRefHINDSIGHT_API_LLM_BASE_URL…config.llmBaseUrl…HINDSIGHT_EMBED_API_URL…config.hindsightApiUrl…HINDSIGHT_EMBED_API_TOKEN…config.hindsightApiToken配置为SecretRefHINDSIGHT_BANK_ID…config.bankId…0.6.0 起插件不再读取任何进程环境变量即使你的 shell 已经导出OPENAI_API_KEY也需要显式将llmApiKey指向该变量SecretRef 在启动时解析为同样的值迁移完成后建议运行openclaw config validate确认新配置形状可被正确解析。完整配置项参考仓库内集成文档 docs-integrations/openclaw.md。Per-Channel Memory Banks按 Agent / 渠道 / 用户隔离记忆默认情况下插件现在基于 agent、channel、user 上下文创建互相隔离的记忆库。同一个用户在 Slack 私聊与 Telegram 群聊中会得到两个独立的记忆存储。该行为由dynamicBankGranularity控制{ config: { dynamicBankGranularity: [agent, channel, user] } }可用的隔离维度字段说明agentBot 身份channel会话或群组 IDuser与 Bot 交互的人provider消息平台Slack、Telegram 等默认值为[agent, channel, user]即每个用户在每个渠道、每个 Agent 下完全隔离。若希望某个用户的记忆跨渠道共享可设为[user]若希望所有内容使用单一共享记忆库则设置dynamicBankId: false。静态记忆库配置现在支持bankId{ config: { dynamicBankId: false, bankId: my-shared-bank } }使用bankIdPrefix可为不同环境命名空间化记忆库 ID例如prod与staging。记忆库 ID 的推导实现从 index.ts 的deriveBankId源码看插件按照dynamicBankGranularity中声明的字段顺序拼接上下文agent / provider / channel / user组成形如openclaw:agent:provider:channel:user的记忆库 ID遇到未识别的粒度字段会解析为unknown并打印告警。bankIdPrefix会在派生出的 ID 前追加前缀如prod-slack-C123。需要留意的是动态记忆库的默认行为dynamicBankId开启时新建的记忆库默认继承 Hindsight 服务端的默认配置concise抽取模式、无实体标签等。若希望每个新记忆库在首次使用时自动打上统一的配置可以在插件配置里声明「银行默认值」——见 bank-defaults.ts 的实现它会在记忆库首次被 retain/recall 触及前通过createBank()与PATCH /banks/{id}/config一次性写入{ dynamicBankId: true, dynamicBankGranularity: [agent, channel, user], retainExtractionMode: verbose, enableObservations: true, enableAutoConsolidation: true, dispositionSkepticism: 3, dispositionLiteralism: 3, dispositionEmpathy: 4, entityLabels: [ { name: person, description: A human user or contact }, { name: project, description: A software project or product } ], retainMission: Extract durable preferences, decisions, and project context., observationsMission: Synthesise stable user preferences and active projects., bankMission: You are a helpful assistant with long-term memory across channels. }相关字段语义见 types.tsbankMission只影响reflect操作写入reflect_mission列不干预 retain/recall不设置时可通过PATCH /banks/{id}在外部管理retainMission写入retain_mission列决定 retain 时抽取哪些事实observationsMission写入observations_mission列控制 consolidation 时合成哪些观察entityLabels只接受属性定义列表或{ attributes: [...] }对象两种形状其他形状会被服务端忽略未设置的字段不会被发送因此只配置 mission 不会改变已有行为每个记忆库在每个 gateway 进程生命周期内最多被配置一次。跨平台按用户隔离记忆的完整示例可参考 Per-User Memory Across Channels 指南。External API Backend多实例共享记忆库你可以让插件指向自托管的 Hindsight API 服务端而不是在本地跑 embedded 守护进程。当多个 OpenClaw 实例需要共享同一个记忆存储、或希望把记忆服务与 gateway 机器分离时这是正确的架构选择。{ config: { hindsightApiUrl: https://your-hindsight-server.example.com, hindsightApiToken: YOUR_API_TOKEN } }插件在启动时会对远程 API 执行健康检查。从 index.ts 的实现看健康检查会请求{apiUrl}/health带 10 秒超时检查失败时 gateway 记录警告但仍会正常启动不会阻塞启动流程。API 不可达期间发生的 retain 操作会被本地排队见下文 JSONL Retain Queue。Hindsight Cloud 本身就是一种外部 API 端点——使用 Cloud URL 与 Token或在向导中选择--mode cloud即可。基础设施要求可参考自托管快速入门相关文档。Recall Injection Controls控制召回记忆的注入位置0.5.0 引入的recallInjectionPosition控制召回的记忆插入上下文的哪个位置值行为prepend注入到系统提示词之前默认append注入到系统提示词之后user作为一条用户消息注入当你有较大的静态系统提示词并希望受益于提示词缓存prompt caching时append很有用把记忆注入在其后静态部分在轮次之间保持稳定缓存命中率更高。{ config: { recallInjectionPosition: append } }实现注意仓库当前 README 与 types.ts 将默认值记录为user注入到用户消息之前同样能保住系统提示词缓存而 0.6 发布说明中的表格默认值为prepend。两者的语义都在代码中支持请以你安装版本的字段注释为准控制召回注入的完整调优教程见 Control Recall Injection 指南。完整的召回控制项选项默认值说明autoRecalltrue每轮自动注入记忆recallBudgetmid召回力度low、mid、highrecallMaxTokens1024注入记忆的最大 token 数recallTypes[world, experience]包含的记忆类型recallTopK不限每轮注入记忆的硬上限recallContextTurns1用于构成召回查询的先前用户轮次数recallInjectionPositionprepend召回记忆的注入位置发布文档表格中的recallTypes默认值为[world, experience]仓库当前实现types.ts默认值为[observation]——只返回合并去重后的观察视图避免大量原始记忆表述同一答案时重复出现。配套的preferObservations默认false在开启时会让召回丢弃已被合并进 observation 的原始事实、保留未合并的从而在不重复合并内容的前提下第一时间浮现刚保留的事实。保留retention控制项选项默认值说明autoRetaintrue每轮后自动保留会话retainEveryNTurns1每 N 轮保留一次retainOverlapTurns0分块保留触发时额外包含的先前轮次当retainEveryNTurns 1时启用分块保留滑动窗口大小为retainEveryNTurns retainOverlapTurns。ReliabilityJSONL 保留队列断网不丢记忆在外部 API 模式下若 API 临时不可达retain 操作不再被丢弃而是排队写入本地 JSONL 文件连接恢复后队列被重放会话照常保留。该能力无需任何配置队列文件位于插件工作目录旁成功重放后自动清理。从 retain-queue.ts 源码看队列实现有几个工程细节零运行时依赖仅用 Node 内置模块本地 spawned daemon 启动期间或崩溃后同样适用「本地守护进程与远程 API 一样可能暂时不可达」FIFO 重放peek(limit)默认每次取 50 条最旧的待发送项成功后按 id 批量移除幂等重试每条排队项会持久化一个operationIdensureOperationId在发送请求前同步写入即使重放过程中再丢一次确认服务端也能据此识别重复请求可配置项retainQueuePath默认~/.openclaw/data/hindsight-retain-queue.jsonl、retainQueueMaxAgeMs默认-1永久保留、retainQueueFlushIntervalMs默认 60000ms 尝试 flush 一次原子重写写临时文件后rename替换全部清空时直接删除队列文件。Session Filtering将特定会话标记为无状态某些会话不应被保留或召回来自 Bot 的操作消息、内部系统事件或任何本质无状态的会话。0.6.0 新增会话模式过滤{ config: { skipSessionPatterns: [^bot-, ^system-event-] } }会话 ID 匹配skipSessionPatterns中任一正则的会话被整体视为无状态不保留、不召回、不执行任何记忆操作。仓库当前版本将正则过滤演进为两套 glob 会话模式见 README.md 与 session-patterns.tsignoreSessionPatterns完全跳过——不召回、不保留statelessSessionPatterns只读会话——始终跳过保留skipStatelessSessions: true默认时也跳过召回glob 语法*匹配单个段不含:**匹配任意内容可跨:会话键格式为agent:agentId:type:uuid。例如[agent:*:cron:**]匹配任意 Agent 的全部 cron 会话[agent:*:subagent:**]匹配全部子代理会话。典型用法让 cron 会话完全不进入记忆子代理会话只读不写skipStatelessSessions: false。Configurable Tags为记忆打标签插件保留的记忆现在可以打上标签便于组织与过滤召回{ config: { retainTags: [openclaw, env:prod] } }标签会出现在该插件实例保留的所有记忆上。用途包括限定召回查询范围、区分环境、或区分共享同一记忆库的不同部署。实现上types.ts标签会做修剪与去重且自动 retain 还会把用户消息内嵌的retain_tags.../retain_tags/hindsight_retain_tags.../hindsight_retain_tags指令块与配置标签合并同时可用retainSource默认openclaw为保留文档写入来源元数据例如source_system:openclaw、agent:agentname这类跨 Agent 标注。Backfill CLI回填历史会话如果你是在现有 OpenClaw 部署上启用 Hindsight 记忆backfill CLI 可以追溯式地导入历史会话npx --package vectorize-io/hindsight-openclaw hindsight-openclaw-backfill该 CLI 读取你的openclaw.json插件配置把历史会话数据处理进配置好的 Hindsight 后端。建议在启用插件后、用户与 Agent 交互前运行一次预热记忆存储。默认情况下它会镜像当前插件的dynamicBankId、dynamicBankGranularity、bankIdPrefix以及「本地 daemon vs 外部hindsightApiUrl」的路由配置见 backfill-lib.ts 与 backfill.ts。常用选项来自 README.md# 干跑预览 npx --package vectorize-io/hindsight-openclaw hindsight-openclaw-backfill \ --openclaw-root ~/.openclaw \ --dry-run # 迁移导向的显式覆盖 node dist/backfill.js \ --openclaw-root ~/.openclaw \ --bank-strategy agent \ --agent proj-run \ --resume \ --max-pending-operations 10--agent id只导入指定 Agent--exclude-archive忽略sessions-archive-from-migration_backup归档--bank-strategy mirror-config|agent|fixed选择记忆库路由策略--resume跳过已标记完成的条目--checkpoint path把进度存到自定义位置--wait-until-drained阻塞直到受影响的记忆库队列处理完毕、checkpoint 可最终确定。Conversation Format0.6.2Anthropic 风格会话格式从 0.6.2 起会话以 Anthropic 风格 JSON 格式存储完整保留tool_use与tool_result内容块。此前工具交互在保留时要么被丢弃、要么被压平成纯文本。这一改动提升了存储会话在分析与回放时的保真度确保复杂的 Agentic 交互工具调用链被完整捕获而非丢失工具调用结构。实现上由retainFormat与retainToolCalls两个配置共同控制types.tsretainFormat: json默认输出{role, content}结构化消息数组与 Claude Code 一致text输出旧的[role: x] ... [x:end]标记格式retainToolCalls: true默认时每条消息的 content 是 Anthropic 形状的块数组text/tool_use/tool_result工具结果截断为 2000 字符且会过滤 Hindsight 自己的 MCP 工具recall/retain/search 等以防止反馈循环设为false则只保留纯文本内容。0.6.2 还包含会话稳定性改进会话身份在轮次间更加一致且保留时会跳过非用户的操作轮次减少记忆存储中的噪声。保留文档使用基于 OpenClawsessionKey派生的稳定会话级 ID形如openclaw:agent:agentname:discord:channel:123同一会话的所有轮次累积到单个 Hindsight 文档下依赖update_mode: append能力探测不支持时回退为按轮次独立 ID并携带session_key、agent_id、provider、channel_id、thread_id、sender_id、turn_index、retention_scope等丰富元数据。升级路径安装最新版本openclaw plugins install vectorize-io/hindsight-openclaw如果你之前用环境变量配置运行设置向导完成迁移npx --package vectorize-io/hindsight-openclaw hindsight-openclaw-setup向导会检测你已有的配置并把等价配置写入openclaw.json。迁移完成后建议运行openclaw config validate校验。开始使用使用 Hindsight Cloud 是接入工作记忆最快的路径无需任何本地基础设施完整配置参考见集成文档 docs-integrations/openclaw.md0.5.0 以来的全部变更见 changelog/integrations/openclaw.md插件 READMEhindsight-integrations/openclaw/README.md包含快速开始、完整配置表、会话模式过滤、保留细节与 OpenClaw 版本兼容性说明当前版本支持 OpenClaw 2026.7.x 至 2026.9.x2026.8.1 需使用 0.12.0更深度的场景方案可参考仓库内系列指南共享记忆、团队记忆库策略、项目级记忆等。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
