企业官网建设流程全解析

Hindsight Memory Plugin for OpenClaw 集成指南：安装、三种部署模式与全量配置解析

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

Hindsight 是一个为 AI Agent 提供拟生物化（biomimetic）长期记忆的开源方案：自动捕获对话、提取事实（facts）、沉淀观察（observations），并在合适时机把相关记忆重新注入上下文。本文基于仓库中 hindsight-integrations/openclaw/README.md 展开，完整讲解 OpenClaw 记忆插件的快速安装、交互式向导、手动配置、0.5.x 迁移、动态银行（dynamic bank）隔离、会话过滤、历史回填等全部内容，并结合插件源码（openclaw.plugin.json、src/index.ts、src/bank-defaults.ts、src/session-patterns.ts）说明每个配置项的实际生效路径。读完你将能在 10 分钟内为 OpenClaw 网关接入 Hindsight 长期记忆，并学会针对多用户、多频道、多 Agent 场景精细调优。

插件是什么：OpenClaw 的专属 memory 槽位

@vectorize-io/hindsight-openclaw是一个注册在 OpenClawmemory槽位（kind）上的插件。在 openclaw.plugin.json 中可以看到它声明了agent_knowledge_list_pages、agent_knowledge_get_page、agent_knowledge_create_page、agent_knowledge_update_page、agent_knowledge_delete_page、agent_knowledge_recall、agent_knowledge_reflect、agent_knowledge_ingest共 8 个工具契约，并把llmApiKey、hindsightApiToken两个路径声明为secretInputs，因此敏感凭据可被 OpenClaw 的 SecretRef 机制安全解析（支持 env / file / exec 三种来源）。

插件的核心工作由 src/index.ts 承担：它实现before_prompt_build（recall 路径，在每个用户回合前注入相关记忆）与agent_end（retain 路径，在每次交互后自动保留对话）两个钩子，中间通过getClientForContext解析出当前会话对应的 Hindsight 银行（bank），并把召回的记忆注入系统提示词空间（<hindsight_memories>上下文块），使记忆既对模型可见、又不出现在可见的聊天记录中——这就是 README 中"auto-capture + auto-recall，注入 system prompt 空间"这一特性的实现原理。

快速开始：三步接入

# 1. 安装插件 openclaw plugins install @vectorize-io/hindsight-openclaw # 2. 运行交互式安装向导 npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-setup # 3. 启动 OpenClaw openclaw gateway

hindsight-openclaw-setup（对应源码 src/setup.ts 与 src/setup-lib.ts）会引导你从三种部署模式中选择一种：

三种模式在源码中分别对应usingExternalApi与本地HindsightServer两条初始化路径：外置 API 模式跳过本地 daemon 管理，直接使用hindsightApiUrl；嵌入式模式则通过uvx hindsight-embed@latest拉起本地服务（默认端口9077）。从源码看，插件还内置了Retain 队列（src/retain-queue.ts）：失败的 retain 会落到~/.openclaw/data/hindsight-retain-queue.jsonl，默认每 60 秒重试一次冲刷（retainQueueFlushIntervalMs），避免瞬时网络故障导致记忆丢失。

向导默认把凭据内联写入openclaw.json（粘贴时会被掩码）。对于 CI / 生产环境，推荐用非交互式参数--token-env/--api-key-env把凭据存成SecretRef（启动时从环境变量、文件或 exec 源解析），或者事后用以下命令把已有字段切换为引用：

openclaw config set ... --ref-source env --ref-id ...

手动配置：不用向导，直接 config set

向导只是便捷封装，所有字段都可以直接用openclaw config set设置：

# 嵌入式 daemon + OpenAI openclaw config set plugins.entries.hindsight-openclaw.config.llmProvider openai openclaw config set plugins.entries.hindsight-openclaw.config.llmApiKey \ --ref-source env --ref-provider default --ref-id OPENAI_API_KEY # 或者：Claude Code（无需 API Key） openclaw config set plugins.entries.hindsight-openclaw.config.llmProvider claude-code # 或者：指向外部 Hindsight API openclaw config set plugins.entries.hindsight-openclaw.config.hindsightApiUrl https://mcp.hindsight.example.com openclaw config set plugins.entries.hindsight-openclaw.config.hindsightApiToken \ --ref-source env --ref-id HINDSIGHT_API_TOKEN

从 0.5.x 迁移：环境变量 → 插件配置

0.6.0 起插件彻底移除了对进程环境变量的读取。所有原本来自 shell 环境变量的配置都必须改为走 OpenClaw 插件配置（凭据用 SecretRef）。具体映射：

如果你的 shell 已经导出了OPENAI_API_KEY，上面的 SecretRef 配置在启动时会解析到同一个值——无需改动 shell 设置，只需让插件显式引用该变量。迁移完成后运行openclaw config validate确认新配置结构可以正常解析。

核心特性

• 自动捕获与自动召回：每轮对话自动 retain 与 recall，召回的记忆注入系统提示词空间，不出现在可见聊天记录中。
• 记忆隔离：通过dynamicBankGranularity按 agent / channel / user / provider 维度隔离记忆。
• 历史回填 CLI：把既有 OpenClaw 会话历史导入 Hindsight，默认沿用插件的银行路由配置。
• 保留控制：选择保留哪些消息角色、开关自动 retain、为保留文档打上统一标签与 source 元数据。

完整配置参考（~/.openclaw/openclaw.json）

以下配置全部位于plugins.entries.hindsight-openclaw.config下。参数清单与默认值以 README.md 为准，并与 openclaw.plugin.json 中声明的 schema（含枚举值、最小值/最大值约束）相互印证。

部署与 LLM

银行（Bank）与记忆隔离

dynamicBankId开启后（默认），OpenClaw 会为每个上下文（例如每个 Slack 用户）推导一个独立的 Hindsight 银行，实现记忆隔离。关闭后所有用户共享一个openclaw银行。

首次使用即盖章：每用户动态银行的默认配置

新建银行默认只继承 Hindsight 服务端默认值（concise提取、无实体标签等）。通过在插件配置中设置以下选项，可以在首次 retain/recall 触碰该银行之前，把完整的银行默认值盖章（stamp）上去。其底层实现在 src/bank-defaults.ts：applyConfiguredBankDefaults通过createBank（写入 missions、提取模式、观察开关、disposition 特质）和PATCH /banks/{id}/config（写入entity_labels、enable_auto_consolidation）完成盖章，且每个进程生命周期内每个银行只盖章一次（banksWithDefaultsApplied集合去重）。

示例配置：

{ "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." }

未设置的选项不会发送——只配置 missions 时，既有行为不变。另外注意：normalizeDispositionTrait只接受 1–5 的整数、normalizeEntityLabels只透传列表或{ attributes: [...] }包装形状（其余形状服务端会静默忽略），这解释了为什么 README 强调"其他形状被忽略"。

Retain 保留行为

关于保留文档 ID 的细节值得展开：保留文档使用基于 OpenClawsessionKey的稳定会话级 ID（形如openclaw:agent:agentname:discord:channel:123），同一会话的所有轮次累积到同一个 Hindsight 文档。对于不支持update_mode: 'append'的旧版 API，集成会回退到按次保留的 ID（...:turn:<boot>:000001、...:window:<boot>:000002），避免覆盖前序轮次——其中<boot>是每个宿主进程铸造一次的随机令牌，防止重启后重放上一次运行已用过的 ID（源码见getDocumentIdBootToken，与 issue #3686 的修复相关）。保留文档携带丰富元数据：session_key、agent_id、provider、channel_id、thread_id、sender_id、turn_index、retention_scope。保留 JSON 中的每条消息还带有从 OpenClaw 每条消息时间提取的结构化timestamp（ISO 8601）字段，避免行内星期/日期前缀污染事实。

Recall 召回行为

另外还有两个源码确认、README 表格之外的实用配置：recallTimeoutMs（默认10000，自动召回超时，[src/index.ts](https://link.gitcode.com/i/7bd497021b41ed5b2023e6ba46c5c59e) 中通过Promise.race抛出TimeoutError实现）与debugPerfTiming（默认false，在每个before_prompt_build/agent_end钩子输出一行perf: hook_total=Xms …`，用于定位延迟来自插件还是上游）。

会话过滤与会话模式

ignoreSessionPatterns与statelessSessionPatterns接受与会话键（格式agent:<agentId>:<type>:<uuid>）匹配的 glob 模式。glob 语法与编译实现在 src/session-patterns.ts：*匹配除:之外的任意字符（单段），**匹配包含:的任意内容（多段）。

两个选项的区别：

示例——cron 任务完全不参与记忆，子 Agent 可读不可写：

{ "ignoreSessionPatterns": ["agent:*:cron:**"], "statelessSessionPatterns": ["agent:*:subagent:**"], "skipStatelessSessions": false }

其余选项

手动知识工具：agent_knowledge_*

当enableKnowledgeTools开启时，插件在自动召回之外注册显式工具。普通记忆查找用agent_knowledge_recall；只有刻意的综合、复盘或长期偏好/模式类问题才用agent_knowledge_reflect——它会先检索记忆，再调用配置的 Reflect LLM 生成答案。

知识工具与自动召回/保留解析同一个动态记忆银行：插件在工具会话上下文中先跑共享的身份解析路径resolveAndCacheIdentity，再推导银行 ID（源码见 src/index.ts）。当dynamicBankGranularity包含"user"时，工具定位该会话的按用户银行；如果发送者身份无法解析，工具执行会返回明确错误，而不是去查询共享的openclaw默认银行或anonymous回退银行。配置的银行默认值（missions、提取模式、实体标签等）在首次知识工具使用时应用，与getClientForContext行为一致。

agent_knowledge_reflect使用保守默认值：budget: "low"、max_tokens: 1024、fact_types: ["world", "experience", "observation"]。生产部署还应设置有限的银行级reflect_source_facts_max_tokens（如4096或8192），而不是让反思源事实无限。

保留细节：稳定的会话级文档

如"Retain 保留行为"一节所述，保留文档使用稳定的会话级 ID，所有轮次累积到单个文档；retainContext与对话文本分开发送，为 Hindsight 的提取 LLM 提供解释引导。默认引导语的完整文本可在源码DEFAULT_RETAIN_CONTEXT（src/index.ts）中查看——它解释了 sender/channel/provider 元数据是运维路由数据、assistant 第一人称属于 AI、银行 ID 或标签不应被当作讨论的项目。sender/channel/provider 保留在 retain 请求的元数据/context 中，不会被前置拼进保留的对话内容。

OpenClaw 版本兼容性

0.12.0 及以后版本兼容OpenClaw 2026.7.x 至 2026.9.x。插件同时读取新旧两种对话元数据标签，因此插件与 OpenClaw 版本不必精确匹配。

在 OpenClaw 2026.8.1 或更高版本上，请使用 0.12.0 或更高版本。2026.8.1 改变了 OpenClaw 附加到每条消息上的元数据标签方式；旧版插件不再识别，导致轮次以missing stable sender identity被跳过、路由 ID 被当成对话内容存储、自动召回甚至会用这些元数据而不是你的消息去搜索。

2026.8.1+ 上有两条预期的（非错误）消息：

• 安装时打印Exclusive slot "memory" switched from "memory-core" to "hindsight-openclaw"——这是正确的，Hindsight 替换了 OpenClaw 内置记忆；
• 随后openclaw plugins doctor报告memory-core未选入 memory 槽位——这只是 OpenClaw 说明其内置记忆让位了。

从 0.11.1 或更早升级：安装可能报npm error Cannot read properties of null (reading 'edgesOut')。这是插件自身的打包问题，已在 0.12.0 修复——用新版本重试即可。

本地开发：测试未发布的包

1. 在~/.openclaw/openclaw.json的插件配置中加入embedPackagePath：

{ "plugins": { "entries": { "hindsight-openclaw": { "enabled": true, "config": { "embedPackagePath": "/path/to/hindsight-wt3/hindsight-embed" } } } } }

2. 插件将改用uv run --directory <path> hindsight-embed，而不是uvx hindsight-embed@latest。

3. 测试指定 profile：

# 查看 daemon 状态 uvx hindsight-embed@latest -p openclaw daemon status # 查看日志 tail -f ~/.hindsight/profiles/openclaw.log # 列出 profiles uvx hindsight-embed@latest profile list

回填既有 OpenClaw 历史

包内置了配置感知的回填 CLI，用于把历史 OpenClaw 会话导入 Hindsight。默认它会镜像插件当前生效的设置：

• dynamicBankId
• dynamicBankGranularity
• bankIdPrefix
• 本地 daemon 与外部hindsightApiUrl的选择

干跑示例：

npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-backfill \ --openclaw-root ~/.openclaw \ --dry-run

从构建产物直接调用：

node dist/backfill.js --openclaw-root ~/.openclaw --dry-run

迁移导向的覆盖参数是显式的：

node dist/backfill.js \ --openclaw-root ~/.openclaw \ --bank-strategy agent \ --agent proj-run \ --resume \ --max-pending-operations 10

常用选项（实现见 src/backfill.ts 与 src/backfill-lib.ts）：

• --agent <id>只导入指定 Agent
• --exclude-archive忽略sessions-archive-from-migration_backup
• --bank-strategy mirror-config|agent|fixed银行路由策略
• --resume只跳过已标记为完成的条目
• --checkpoint <path>把进度存到默认位置之外
• --wait-until-drained阻塞到所触达银行队列处理完毕、checkpoint 状态可最终化

写在最后

本文覆盖了 Hindsight OpenClaw 插件的安装、三种部署模式、0.5.x → 0.6.0 迁移、动态银行与首次盖章默认值、retain/recall 全参数、会话模式过滤、知识工具、版本兼容、本地开发与历史回填。配置 schema 的权威定义在 openclaw.plugin.json，实现细节与测试用例分布在 src/index.ts、src/bank-defaults.ts、src/session-patterns.ts 以及 src/index.test.ts、src/backfill-lib.test.ts、tests/integration.test.ts 等测试中，可按需深入研读。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight