refactor: 对齐最新记忆与commitments文档

2026-07-15 13:41:03 +08:00
parent b7e1a5d34f
commit ebd3e3194c
6 changed files with 433 additions and 557 deletions
@@ -1,78 +1,129 @@
 ---
-name: openclaw-memory-config
-description: |
-  配置 OpenClaw 记忆系统：Memory Search（向量搜索）、Dreaming（记忆整理）、Memory Wiki（知识库）。触发词："配置记忆"、"配置 memory"、"memory search"、"配置搜索"、"配置 dreaming"、"配置梦境"、"配置 wiki"、"memory wiki"、"记忆配置"。使用本机已有 trapi embedding 端点，为用户提供完整的记忆系统初始化流程。
+name: "openclaw-memory-config"
+description: "按最新官方 Memory 与 Commitments 文档安全配置 OpenClaw 记忆系统"
 ---

 # OpenClaw 记忆系统配置

-一键配置 OpenClaw 记忆系统，包含 Memory Search（向量语义搜索）、Dreaming（夜间记忆整理）、Memory Wiki（知识库）三大模块。
+依据当前 OpenClaw Schema 和官方文档做最小、可回滚的配置。默认使用 builtin memory；不得在未确认时替换第三方 memory slot、重建大索引、开启后台模型调用或创建对外通知。

-## Embedding 服务信息（默认）
+官方基线：

- **Provider**：`openai`（OpenAI 兼容格式）
- **Base URL**：`https://lapi.transiglobal.com/v1`
- **默认模型**：`bge-large-zh-v1.5`
- **API Key 来源**：优先复用本地已配置的 trapi provider；如未配置则要求用户提供
+- Memory overview: https://docs.openclaw.ai/concepts/memory
+- Memory search: https://docs.openclaw.ai/concepts/memory-search
+- Commitments: https://docs.openclaw.ai/concepts/commitments
+- Dreaming: https://docs.openclaw.ai/concepts/dreaming
+- Memory config: https://docs.openclaw.ai/reference/memory-config
+- Memory Wiki: https://docs.openclaw.ai/plugins/memory-wiki

-## 前置条件
+## 原则

-1. OpenClaw 已安装并运行
-2. 本机配置文件为 `openclaw.json`，使用 `gateway config.patch` 写入
-3. Embedding API Key：
-   - **优先**：检查本地 `models.providers.trapi.apiKey` 是否已配置，已配置则复用
-   - **兜底**：如 trapi 未配置，向用户提供两种选择：
-     - a) 提供 trapi API Key（使用默认 trapi embedding 端点）
-     - b) 提供其他 embedding provider 信息（provider、baseUrl、apiKey、model）
+- 先读当前 Schema 和配置，再写入；不同 OpenClaw 版本可能有字段差异。
+- 使用 `openclaw config get/set/patch/validate`。所有写入先 `--dry-run`，成功后再执行正式写入。
+- `config get` 只用于读取脱敏快照。不得提取、打印或复制明文 API Key。
+- 凭据优先使用 SecretRef；不得要求用户在聊天中粘贴密钥。
+- 变更 `plugins.entries` 后按 CLI 提示重启 Gateway；不要自行停止 Gateway。
+- 改变 embedding provider、模型、输入类型、来源、chunking 或 tokenizer 会改变索引身份。先说明重建成本，再运行 `openclaw memory index --force`。
+- 显式提醒和精确定时任务使用 scheduled tasks/cron；Commitments 只用于推断出的短期跟进。
+- Memory、Commitments、Dreaming、Wiki 可以分别启用，不把它们误写成严格串行依赖。

---
+## 0. 预检与备份

-## 模块 1：Memory Search（语义记忆搜索）
+先执行只读检查：

-### 步骤 1：配置 Embedding
+```bash
+openclaw --version
+openclaw config validate --json
+openclaw config get memory --json
+openclaw config get agents.defaults.memorySearch --json
+openclaw config get agents.defaults.compaction.memoryFlush --json
+openclaw config get plugins.slots.memory --json
+openclaw config get plugins.entries.memory-core --json
+openclaw config get commitments --json
+openclaw config get agents.defaults.heartbeat --json
+openclaw plugins list
+openclaw plugins doctor
+```

-**检测 trapi**：先通过 `gateway config.get` 检查 `models.providers.trapi` 是否已存在：
+缺失路径可视为未配置，不是失败。需要写配置前创建配置备份：

- **已配置 trapi**：直接从配置中提取 `apiKey`，无需用户额外提供，跳到下一步
- **未配置 trapi**：向用户说明两种选择：
-  - a) 提供 trapi API Key → 使用默认配置（baseUrl + bge-large-zh-v1.5）
-  - b) 提供自定义 embedding provider 信息（需确认 provider、baseUrl、apiKey、model）
+```bash
+openclaw backup create --only-config --verify
+```

-如用户拒绝提供任何 Key，终止流程。
+再用 `openclaw config schema` 或当前版本官方文档确认目标字段存在。若当前版本不支持 `commitments`、目标 provider 或 Wiki 字段，停止并建议先升级 OpenClaw，不写未知字段。

-使用 `gateway config.patch` 配置 `agents.defaults.memorySearch`：
+## 1. 明确记忆层级

-```json
+向用户说明：
+
+- `MEMORY.md`：精炼的长期事实、偏好和决策；会进入会话启动上下文，需控制体积。
+- `memory/YYYY-MM-DD.md`：每日工作层；用于详细日志和近期上下文。
+- `DREAMS.md`：可选的人类审阅面；不是普通长期记忆来源。
+- Commitments：短期、会话与渠道绑定的待跟进状态，不写入 `MEMORY.md`。
+- Wiki：独立的结构化知识层，不替代 active memory plugin。
+
+涉及权限、时效、交接、解锁条件或来源权威的记忆，应同时写明“何时可以行动、何时失效、禁止什么、谁有授权”。记忆只保存上下文，不代替审批、沙箱或调度器。
+
+## 2. 选择 active memory plugin
+
+`memory_search` / `memory_get` 由当前 memory slot 插件提供。默认插件是内置 `memory-core`，但现场可能使用 LanceDB、Honcho 等第三方插件。
+
+判断：
+
+- slot 已是 `memory-core`：保留。
+- slot 为空且 builtin 正常：不必为了显式化而写配置。
+- slot 是第三方插件：报告其能力和迁移影响；只有用户明确同意才切回 `memory-core`。
+- 选择 QMD：读取官方 QMD 文档并单独设计；不要沿用 builtin embedding 配置。
+
+切换到 builtin + memory-core 时：
+
+1. 先备份。
+2. 用 `openclaw plugins enable memory-core` 启用内置插件，避免手工覆盖 `plugins.allow` 数组。
+3. 对以下写入先加 `--dry-run`，通过后去掉该参数正式执行：
+
+```bash
+openclaw config set plugins.slots.memory memory-core --dry-run
+openclaw config set memory.backend builtin --dry-run
+```
+
+4. 按 CLI 提示使用 `openclaw gateway restart`。
+5. 运行 `openclaw plugins doctor` 和该插件提供的 memory CLI/工具验证。
+
+不得在未确认时禁用或卸载原 memory 插件。
+
+## 3. Memory Search
+
+### 3.1 默认 trapi 路径
+
+传米 trapi 是通用 OpenAI-compatible embeddings 端点，应使用：
+
+- provider: `openai-compatible`
+- base URL: `https://lapi.transiglobal.com/v1`
+- model: `bge-large-zh-v1.5`
+- SecretRef 环境变量: `TRAPI_API_KEY`
+
+若现有 `agents.defaults.memorySearch.remote.apiKey` 已是可解析 SecretRef，保留它。若只有 `models.providers.trapi.apiKey`：
+
+- 它是 SecretRef 时，可在用户确认后复用同一引用。
+- 它是明文时，不读取或回显；引导迁移到 `TRAPI_API_KEY` SecretRef。
+
+确保环境变量对 Gateway 服务可见，而不只是当前交互 shell。使用最小 JSON5 patch；先 dry-run，再正式写入：
+
+```json5
 {
-  "agents": {
-    "defaults": {
-      "memorySearch": {
-        "provider": "openai",
-        "model": "bge-large-zh-v1.5",
-        "remote": {
-          "baseUrl": "https://lapi.transiglobal.com/v1",
-          "apiKey": "<用户提供的API_KEY>"
-        },
-        "chunking": {
-          "tokens": 200,
-          "overlap": 30
-        },
-        "query": {
-          "maxResults": 10,
-          "minScore": 0.35,
-          "hybrid": {
-            "enabled": true,
-            "vectorWeight": 0.85,
-            "textWeight": 0.15,
-            "candidateMultiplier": 8,
-            "mmr": {
-              "enabled": true,
-              "lambda": 0.5
-            },
-            "temporalDecay": {
-              "enabled": true,
-              "halfLifeDays": 30
-            }
+  agents: {
+    defaults: {
+      memorySearch: {
+        enabled: true,
+        provider: "openai-compatible",
+        model: "bge-large-zh-v1.5",
+        remote: {
+          baseUrl: "https://lapi.transiglobal.com/v1",
+          apiKey: {
+            source: "env",
+            provider: "default",
+            id: "TRAPI_API_KEY"
          }
        }
      }
@@ -81,224 +132,167 @@ description: |
 }
 ```

-### 步骤 2：搜索参数说明
+```bash
+openclaw config patch --file ./memory-search.patch.json5 --dry-run
+openclaw config patch --file ./memory-search.patch.json5
+openclaw config validate --json
+```

-配置中已包含以下优化参数（均已在上方 JSON 中预设，无需额外修改）：
+不要默认覆盖官方检索参数。当前默认值为：chunk 400/80、maxResults 6、minScore 0.35、hybrid 0.7/0.3、candidateMultiplier 4，MMR 和 temporal decay 默认关闭。只有出现重复结果、旧记录压过新记录或精确/语义权重失衡时才按 `references/memory-search.md` 调整。

-| 参数组 | 参数 | 值 | 说明 |
-|--------|------|-----|------|
-| **分块** | `chunking.tokens` | 200 | 每个文本块 200 token |
-| | `chunking.overlap` | 30 | 块间重叠 30 token，避免截断语义 |
-| **基础查询** | `query.maxResults` | 10 | 最多返回 10 条结果 |
-| | `query.minScore` | 0.35 | 最低相关度阈值，低于此分数不返回 |
-| **混合搜索** | `hybrid.enabled` | true | 同时使用向量搜索 + BM25 关键词搜索 |
-| | `hybrid.vectorWeight` | 0.85 | 向量搜索权重 85%（语义匹配优先） |
-| | `hybrid.textWeight` | 0.15 | 关键词搜索权重 15%（精确匹配补充） |
-| | `hybrid.candidateMultiplier` | 8 | 候选池倍数，越大召回越全但越慢 |
-| **MMR 去重** | `mmr.enabled` | true | 减少重复结果，不同话题覆盖更广 |
-| | `mmr.lambda` | 0.5 | 0=最多样，1=最相关，0.5 平衡 |
-| **时间衰减** | `temporalDecay.enabled` | true | 旧记忆逐渐降权，新记忆优先展示 |
-| | `temporalDecay.halfLifeDays` | 30 | 每 30 天权重减半，MEMORY.md 等常驻文件不衰减 |
+对需要 `input_type` 的非对称 embedding 模型，按供应商要求设置 `queryInputType` 与 `documentInputType`，并重建索引。

-> 以上参数适用于大多数场景，用户一般无需调整。如需微调可在配置完成后通过 `gateway config.patch` 修改。
+### 3.2 验证

-配置写入后，立即执行：
+若 active plugin 注册了官方 memory CLI：

 ```bash
+openclaw memory status --deep
 openclaw memory index --force
+openclaw memory search "一个确实存在于记忆中的关键词"
 ```

-### 步骤 3：测试搜索
+只在索引身份改变或索引损坏时强制重建。若 `openclaw memory` 未注册，先检查 active memory plugin 与 Gateway 状态；第三方插件使用其自带诊断工具，不把“未知命令”误判为索引为空。

-索引构建完成后，用 `memory_search` 测试是否生效：
+测试应选择当前 workspace 中已存在、非敏感的关键词，并检查命中来源和相关性。

-1. 从用户的 memory 目录中找到已有内容的关键词
-2. 执行 `memory_search` 搜索
-3. 确认能返回相关结果，报告搜索质量
+## 4. Automatic memory flush

-**测试关键词示例**（根据实际记忆内容选择）：
- 搜索 "传米科技" → 应找到公司相关信息
- 搜索 "Tailscale" → 应找到网络配置信息
- 搜索最近的日期 → 应找到当天的日记
+compaction 前的 memory flush 默认开启。读取 `agents.defaults.compaction.memoryFlush`：

-### 验证报告
+- 未配置：保留默认开启。
+- 被明确关闭：说明上下文压缩前可能丢失尚未落盘的重要信息，再询问是否恢复。
+- 仅在用户要求降低主模型成本时设置专用 `model`；该模型覆盖只作用于 memory-flush turn，不继承会话 fallback 链。

-| 测试项 | 关键词 | 结果 |
-|--------|--------|------|
-| 语义搜索 | <实际关键词> | ✅/❌ |
-| 索引状态 | `openclaw memory status` | ✅/❌ |
+不要为了“显式化默认值”写冗余配置。

---
+## 5. Dreaming

-## 模块 2：Dreaming（夜间记忆整理）
+Dreaming 属于 `memory-core`，默认关闭。它自管一个去重后的 full-sweep cron；不要再创建第二个外部 Dreaming cron。

-### 配置
+启用前确认：

-使用 `gateway config.patch` 启用 dreaming：
+- active memory plugin 为 `memory-core`
+- 接受后台模型调用和长期记忆写入
+- frequency、timezone 与现有维护窗口不冲突
+- 是否需要可选 Dream Diary 模型覆盖

-```json
-{
-  "plugins": {
-    "entries": {
-      "memory-core": {
-        "enabled": true,
-        "config": {
-          "dreaming": {
-            "enabled": true,
-            "frequency": "30 4 * * *",
-            "timezone": "Asia/Shanghai"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
- **频率**：每天凌晨 4:30（在安全巡检和系统升级之后）
- **三个阶段**：Light（排序）→ REM（反思）→ Deep（提升到长期记忆）
- **输出**：`memory/dreaming/` 下的阶段报告 + `DREAMS.md` 日记
- **长期记忆**：Deep 阶段会将高价值内容写入 `MEMORY.md`
-
-### 验证
-
-运行 `/dreaming status` 确认 dreaming 已启用并显示下次执行时间。
-
---
-
-## 模块 3：Memory Wiki（知识库）
-
-### 前置确认
-
-**必须先向用户确认**：是否有需要放入 Wiki 的内容目录。
-
- **有**：继续配置
- **没有**：跳过此模块，告知用户后续可随时配置
-
-### 步骤 1：配置 Wiki
-
-使用 `gateway config.patch` 启用 memory-wiki（isolated 模式）：
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "memory-wiki": {
-        "enabled": true,
-        "config": {
-          "vaultMode": "isolated",
-          "vault": {
-            "path": "~/.openclaw/wiki/main",
-            "renderMode": "obsidian"
-          },
-          "bridge": {
-            "enabled": false,
-            "readMemoryArtifacts": true,
-            "indexDreamReports": true,
-            "indexDailyNotes": true,
-            "indexMemoryRoot": true,
-            "followMemoryEvents": true
-          },
-          "search": {
-            "backend": "shared",
-            "corpus": "all"
-          },
-          "context": {
-            "includeCompiledDigestPrompt": false
-          },
-          "render": {
-            "preserveHumanBlocks": true,
-            "createBacklinks": true,
-            "createDashboards": true
-          },
-          "ingest": {
-            "autoCompile": true,
-            "maxConcurrentJobs": 1
-          },
-          "obsidian": {
-            "enabled": true
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### 步骤 2：导入内容
-
-用户提供内容目录后，使用 CLI 导入：
+基础配置路径：

 ```bash
+openclaw config set plugins.entries.memory-core.config.dreaming.enabled true --strict-json --dry-run
+openclaw config set plugins.entries.memory-core.config.dreaming.enabled true --strict-json
+```
+
+默认频率是 `0 3 * * *`。仅在用户指定维护窗口时设置 `frequency` 和 `timezone`。若设置 `dreaming.model`，还必须：
+
+- `plugins.entries.memory-core.subagent.allowModelOverride: true`
+- 建议同时限制 `plugins.entries.memory-core.subagent.allowedModels`
+- 使用规范的 `provider/model` 名称
+
+插件配置变化后按 CLI 提示重启。验证：
+
+```text
+/dreaming status
+```
+
+可选只读/预览检查：
+
+```bash
+openclaw memory status --deep
+openclaw memory promote
+openclaw memory promote-explain "关键词" --json
+openclaw memory rem-harness --json
+```
+
+不要把 Light、REM、Deep 当作三个独立 cron；执行顺序是 Light → REM → Deep。历史回填先预览，写入前确认；回填 staged candidates 仍需 Deep 才能进入 `MEMORY.md`。
+
+## 6. Inferred Commitments
+
+Commitments 默认关闭，是“记忆与自动化之间”的短期跟进层。开启前必须说明并确认：
+
+- 每个合格对话后可能增加一次隐藏 LLM 提取，产生模型成本。
+- 提取会读取判断跟进所需的近期对话。
+- 记录保存在本地 OpenClaw 状态，绑定原 agent、session、channel 与 delivery target。
+- 到期项通过 heartbeat 投递；若 heartbeat `target: "none"`，只保留内部状态，不外发。
+- 到期 heartbeat turn 不带 OpenClaw 工具，且不会重放原始对话。
+- Commitments 不是精确提醒；“3 点提醒我”等需求必须走 scheduled tasks。
+
+用户确认后，默认每天每个 agent session 最多投递 3 个：
+
+```bash
+openclaw config set commitments.enabled true --strict-json --dry-run
+openclaw config set commitments.maxPerDay 3 --strict-json --dry-run
+openclaw config set commitments.enabled true --strict-json
+openclaw config set commitments.maxPerDay 3 --strict-json
+openclaw config validate --json
+```
+
+检查 heartbeat 是否运行、投递目标和安静时段是否符合用户预期。不要为了测试而主动向外发送消息。
+
+管理与验证：
+
+```bash
+openclaw config get commitments --json
+openclaw commitments
+openclaw commitments --all
+openclaw commitments --agent main
+openclaw commitments --status snoozed
+openclaw commitments dismiss cm_abc123
+```
+
+Commitment 不会在创建后立即投递；最早时间至少是创建后的一个 heartbeat interval。功能测试需用户同意，使用一个非紧急、非精确定时的自然跟进场景，等待 heartbeat 后核对同一 agent/channel 是否收到自然 check-in；无需外发测试时只做配置和列表验证。
+
+关闭：
+
+```bash
+openclaw config set commitments.enabled false --strict-json
+```
+
+关闭功能不会把 commitments 转成长期记忆。
+
+## 7. Memory Wiki（可选）
+
+仅在用户需要结构化知识库时配置。先选择：
+
+- `vaultMode`: `isolated`（默认）、`bridge`、`unsafe-local`
+- `vault.scope`: `global`（默认）或 `agent`
+- `vault.renderMode`: `native`（默认）或 `obsidian`
+- `search.corpus`: `wiki`（默认）、`memory`、`all`
+
+单 agent、独立知识库优先使用最小 isolated 配置。多 agent 需要隔离时使用 `vault.scope: "agent"`；这只是同进程知识边界，不是操作系统安全边界。切换 scope 不会自动迁移旧 vault，移动前必须备份并确认。
+
+Bridge 模式才启用 `bridge.enabled` 并选择 memory artifacts、Dream reports、daily notes 与 event logs。不要在 isolated 模式下误以为 bridge 索引开关会产生导入。
+
+Obsidian CLI、URL ingest、unsafe-local、compiled digest prompt 和每日维护 cron 均为可选能力，逐项确认；不要默认安装依赖、开放 URL 导入或向飞书发送维护报告。
+
+验证：
+
+```bash
+openclaw wiki status
+openclaw wiki doctor
 openclaw wiki init
-openclaw wiki ingest <用户提供的内容目录>
-openclaw wiki compile
+openclaw wiki lint
+openclaw wiki search "已导入内容中的关键词"
 ```

-### 步骤 3：创建每日维护定时任务
+只有用户提供并确认内容路径后才执行 `openclaw wiki ingest <path>` 和 `openclaw wiki compile`。

-创建定时任务（参考已有配置），每天凌晨 5:00 执行 Wiki 维护：
+## 8. 最终验证与报告

-```
-cron add:
-  name: "Wiki 每日维护（Sources 同步 + Lint）"
-  schedule: "0 5 * * *" (Asia/Shanghai)
-  sessionTarget: "isolated"
-  payload:
-    kind: "agentTurn"
-    message: |
-      执行每日 Wiki 维护任务：
-      1. 执行 wiki_lint 检查
-      2. 自动修复可修复的问题（缺失 frontmatter、匹配 sourceIds）
-      3. 无法自动修复的问题（broken wikilinks）跳过
-      4. 再跑一次 wiki_lint 确认
-      5. 汇报结果
-    toolsAllow: ["exec", "read", "edit", "write", "wiki_lint", "wiki_apply", "wiki_search", "wiki_get"]
-    timeoutSeconds: 600
-  delivery:
-    mode: "announce"
-    channel: "feishu"
+执行：
+
+```bash
+openclaw config validate --json
+openclaw plugins doctor
+openclaw gateway status --json --require-rpc
 ```

-### 验证
+按启用模块追加：

- `wiki_status` 确认 vault 模式和健康状态
- `wiki_search` 测试能否搜到导入的内容
- `wiki_lint` 检查结构完整性
+- Memory Search：provider/模型/索引身份、深度状态、真实关键词搜索。
+- Dreaming：`/dreaming status`、managed sweep 是否存在、下次运行时间。
+- Commitments：配置、heartbeat 投递条件、pending/all 列表；外发测试仅在用户同意后进行。
+- Wiki：status、doctor、lint 和真实内容搜索。

---
-
-## 完整验证报告
-
-全部模块配置完成后，输出汇总表：
-
-| 模块 | 配置项 | 状态 |
-|------|--------|------|
-| Memory Search | Embedding + 索引 | ✅/❌ |
-| Memory Search | 语义搜索测试 | ✅/❌ |
-| Dreaming | 启用 + cron | ✅/❌ |
-| Memory Wiki | Vault 初始化 | ✅/❌（可能跳过） |
-| Memory Wiki | 内容导入 | ✅/❌（可能跳过） |
-| Memory Wiki | 定时维护任务 | ✅/❌（可能跳过） |
-
-## 参考文档
-
-遇到问题时，读取对应参考文件获取 OpenClaw 官方文档摘要：
-
-| 问题场景 | 参考文件 | 在线文档 |
-|---------|---------|---------|
-| Memory Search 配置/搜索问题 | `references/memory-search.md` | https://docs.openclaw.ai/concepts/memory-search |
-| Dreaming 配置/阶段问题 | `references/dreaming.md` | https://docs.openclaw.ai/concepts/dreaming |
-| Memory Wiki 配置/bridge 问题 | `references/memory-wiki.md` | https://docs.openclaw.ai/plugins/memory-wiki |
-| Builtin Engine / 索引问题 | `references/memory-search.md` | https://docs.openclaw.ai/concepts/memory-builtin |
-| 完整 Memory 配置参考 | `references/memory-search.md` | https://docs.openclaw.ai/reference/memory-config |
-| Memory 总览 | `references/memory-search.md` | https://docs.openclaw.ai/concepts/memory |
-
-## 故障排查
-
- **索引为空**：`openclaw memory index --force` 强制重建
- **只有关键词匹配**：embedding provider 未配好，检查 API Key 和网络
- **CJK 搜索失败**：`openclaw memory index --force` 重建 FTS
- **Dreaming 未运行**：检查 `/dreaming status` 和 cron 任务
- **Wiki bridge 无数据**：isolated 模式下 bridge 关闭是正常的
- **Wiki ingest 失败**：确认目录路径和文件权限
+报告必须列出：变更前后、备份位置、实际写入路径、是否重启、索引是否重建、后台模型成本、外发条件、跳过项和未解决告警。