diff --git a/README.md b/README.md
index 263909f..29de865 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,66 @@
 # openclaw-memory-config
 
-OpenClaw 技能（Skill）：一键配置 OpenClaw 记忆系统。
+用于配置和诊断 OpenClaw 记忆系统的 Workspace Skill，按当前 OpenClaw Schema 和官方文档执行最小、可回滚的变更。
 
-## 简介
+## 覆盖能力
 
-本技能帮助用户在 OpenClaw 实例上配置完整的记忆系统，包含三大模块：
+1. **Memory Core / active memory plugin**：识别当前 memory slot，避免误覆盖 LanceDB、Honcho 等第三方插件。
+2. **Memory Search**：配置 builtin SQLite 混合检索、Embedding、索引和搜索质量。
+3. **Automatic memory flush**：检查 compaction 前自动落盘，减少上下文压缩造成的记忆丢失。
+4. **Dreaming**：启用 `memory-core` 的后台整理、Dream Diary 和长期记忆提升。
+5. **Inferred Commitments**：配置短期、会话和渠道绑定的自然跟进。
+6. **Memory Wiki**：按需配置 isolated、bridge 或 per-agent vault。
 
-1. **Memory Search** — 基于向量的语义记忆搜索
-2. **Dreaming** — 夜间自动记忆整理（短期 → 长期）
-3. **Memory Wiki** — 结构化知识库（isolated 模式）
+## 默认 Embedding
 
-## Embedding 服务
+- Provider：`openai-compatible`
+- Base URL：`https://lapi.transiglobal.com/v1`
+- Model：`bge-large-zh-v1.5`
+- Credential：`TRAPI_API_KEY` SecretRef
 
-默认使用传米科技 trapi 的 embedding 端点：
-
-| 项目 | 值 |
-|------|-----|
-| Provider | `openai`（OpenAI 兼容） |
-| Base URL | `https://lapi.transiglobal.com/v1` |
-| 模型 | `bge-large-zh-v1.5` |
-
-### API Key
-
-- **优先复用**：如本地已配置 trapi provider，自动提取 API Key，无需额外提供
-- **兜底**：如未配置 trapi，用户需提供 trapi Key 或自定义 embedding provider 信息
+不会要求用户在聊天中粘贴明文 API Key。已有可解析 SecretRef 会优先保留。
 
 ## 使用方式
 
-### 安装技能
-
-```bash
-openclaw skill install openclaw-memory-config.skill
-```
-
-### 配置
-
 在 OpenClaw 对话中说：
 
-> "配置记忆"
+> 配置记忆
 
-技能会引导完成：
-1. **Memory Search**：配置 embedding → 构建索引 → 测试搜索
-2. **Dreaming**：启用夜间记忆整理（每天 4:30 自动运行）
-3. **Memory Wiki**：确认内容目录 → 初始化 vault → 导入内容 → 创建每日维护定时任务
+技能会先读取当前版本、Schema、active memory plugin、Memory Search、Dreaming、Commitments、Heartbeat 和 Wiki 状态，再给出最小变更方案。
 
-### 安全说明
+所有配置写入遵循：
 
-- API Key 必须由用户提供，技能中不存储默认密钥
-- Memory Wiki 默认使用 isolated 模式，数据完全独立
-- 所有配置通过 `gateway config.patch` 标准方式写入
+1. 创建配置备份。
+2. 使用 `openclaw config set/patch --dry-run` 验证。
+3. 正式写入并运行 `openclaw config validate`。
+4. 仅在 CLI 明确提示时重启 Gateway。
+5. 使用真实但非敏感的记忆内容验证检索质量。
+
+## Commitments 边界
+
+Commitments 默认关闭。启用前会说明隐藏 LLM 提取的模型成本、近期对话读取范围和 Heartbeat 外发条件。
+
+- “我明天有面试”这类自然跟进可使用 Commitments。
+- “下午 3 点提醒我”或周期任务必须使用 scheduled tasks/cron。
+- Heartbeat `target: "none"` 时，到期 Commitment 只保留内部状态，不会外发。
+
+## 安全约束
+
+- 不在未确认时替换第三方 memory slot。
+- 不直接覆盖 `plugins.allow` 数组。
+- 不默认改写官方搜索参数或强制重建大索引。
+- Dreaming 使用 `memory-core` 自管的去重 cron，不额外创建重复任务。
+- Wiki 的 URL ingest、unsafe-local、Obsidian CLI、compiled digest prompt 和通知任务均需单独确认。
+- 不执行 `gateway stop`；需要时使用 `openclaw gateway restart`。
+
+## 官方文档
+
+- [Memory overview](https://docs.openclaw.ai/concepts/memory)
+- [Memory search](https://docs.openclaw.ai/concepts/memory-search)
+- [Inferred commitments](https://docs.openclaw.ai/concepts/commitments)
+- [Dreaming](https://docs.openclaw.ai/concepts/dreaming)
+- [Memory configuration reference](https://docs.openclaw.ai/reference/memory-config)
+- [Memory Wiki](https://docs.openclaw.ai/plugins/memory-wiki)
 
 ## 许可证
 
diff --git a/SKILL.md b/SKILL.md
index 05baeb6..8c0d3f1 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -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 失败**：确认目录路径和文件权限
+报告必须列出：变更前后、备份位置、实际写入路径、是否重启、索引是否重建、后台模型成本、外发条件、跳过项和未解决告警。
diff --git a/references/commitments.md b/references/commitments.md
new file mode 100644
index 0000000..4cf83fe
--- /dev/null
+++ b/references/commitments.md
@@ -0,0 +1,51 @@
+# Inferred Commitments 参考
+
+官方来源：https://docs.openclaw.ai/concepts/commitments
+
+Commitments 是可选的短期跟进记忆，默认关闭。它不是长期记忆，也不是精确定时提醒。
+
+## 运行方式
+
+- Agent 回复后可能触发隐藏 LLM 提取，工具禁用。
+- 高置信度候选保存 agent id、session key、原 channel/target、due window 和建议 check-in。
+- 到期后通过同一 agent/channel 的 heartbeat 处理。
+- heartbeat `target: "none"` 时不外发。
+- 到期 turn 不重放原对话，且不带 OpenClaw 工具。
+- 最早投递时间至少是创建后的一个 heartbeat interval。
+
+## 配置
+
+```json
+{
+  "commitments": {
+    "enabled": true,
+    "maxPerDay": 3
+  }
+}
+```
+
+`maxPerDay` 是每个 agent session 的 rolling-day 投递上限，默认 3。
+
+## 适用边界
+
+Commitments：
+
+- “我明天有面试”
+- “我昨晚完全没睡”
+- 对话形成了明确但未精确定时的开放跟进
+
+Scheduled tasks：
+
+- “下午 3 点提醒我”
+- “20 分钟后通知我”
+- “每个工作日运行报告”
+
+## 管理
+
+- `openclaw commitments`
+- `openclaw commitments --all`
+- `openclaw commitments --agent <id>`
+- `openclaw commitments --status pending|sent|dismissed|snoozed|expired`
+- `openclaw commitments dismiss <id>`
+
+启用会增加后台模型使用，并读取判断所需的近期对话。Stored commitments 是本地 operational state。测试外发前需用户明确同意。
diff --git a/references/dreaming.md b/references/dreaming.md
index 7a4a956..b1822bd 100644
--- a/references/dreaming.md
+++ b/references/dreaming.md
@@ -1,79 +1,39 @@
-# Dreaming 参考文档
+# Dreaming 参考
 
-> 来源：OpenClaw 官方文档
-> - https://docs.openclaw.ai/concepts/dreaming
+官方来源：https://docs.openclaw.ai/concepts/dreaming
 
-## 概述
+Dreaming 是 `memory-core` 的可选后台 consolidation，默认关闭。启用后由插件自动管理一个去重后的 full-sweep cron。
 
-Dreaming 是后台记忆整理系统，将短期信号整理为持久记忆。**默认禁用，需手动开启。**
+## 阶段与输出
 
-## 三个阶段
+顺序固定为 Light → REM → Deep：
 
-| 阶段 | 目的 | 持久写入 |
-|------|------|---------|
-| **Light** | 排序和暂存短期材料 | 否 |
-| **Deep** | 评分并提升到长期记忆 | ✅ 写入 MEMORY.md |
-| **REM** | 反思主题和重复模式 | 否 |
+- Light：排序和暂存短期材料，不写 `MEMORY.md`。
+- REM：生成主题反思，不写 `MEMORY.md`。
+- Deep：通过 score、recall count、query diversity 门槛后提升到 `MEMORY.md`。
+
+机器状态位于 `memory/.dreams/`；人类审阅输出位于 `DREAMS.md`，可选阶段报告位于 `memory/dreaming/<phase>/YYYY-MM-DD.md`。Diary/report 不作为 promotion 来源。
 
 ## 配置
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "memory-core": {
-        "enabled": true,
-        "config": {
-          "dreaming": {
-            "enabled": true,
-            "frequency": "0 3 * * *",
-            "timezone": "Asia/Shanghai"
-          }
-        }
-      }
-    }
-  }
-}
-```
+路径：`plugins.entries.memory-core.config.dreaming`
 
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enabled` | false | 是否启用 |
-| `frequency` | `0 3 * * *` | 执行频率（cron 表达式） |
-| `timezone` | 系统时区 | 时区 |
+- `enabled`: 默认 false
+- `frequency`: 默认 `0 3 * * *`
+- `model`: 可选 Dream Diary 模型
+- `phases.deep.maxPromotedSnippetTokens`: 默认 160
 
-## 输出文件
+设置 `dreaming.model` 时必须启用 `plugins.entries.memory-core.subagent.allowModelOverride`，并建议用 `allowedModels` 限制规范的 `provider/model`。
 
-- `DREAMS.md`（或 `dreams.md`）：人类可读的梦境日记
-- `memory/dreaming/<phase>/YYYY-MM-DD.md`：阶段报告
-- `memory/.dreams/`：机器状态（recall store、信号、检查点）
+## CLI
 
-## Deep 排序信号（6个权重）
+- `/dreaming status|on|off|help`
+- `openclaw memory promote`
+- `openclaw memory promote --apply`
+- `openclaw memory promote-explain "关键词" --json`
+- `openclaw memory rem-harness --json`
+- `openclaw memory rem-backfill --path ./memory`
+- `openclaw memory rem-backfill --rollback`
+- `openclaw memory rem-backfill --rollback-short-term`
 
-| 信号 | 权重 | 说明 |
-|------|------|------|
-| Frequency | 0.24 | 短期信号累计次数 |
-| Relevance | 0.30 | 平均检索质量 |
-| Query diversity | 0.15 | 不同查询/天上下文 |
-| Recency | 0.15 | 时间衰减新鲜度 |
-| Consolidation | 0.10 | 跨天重复强度 |
-| Conceptual richness | 0.06 | 概念标签密度 |
-
-## CLI 命令
-
-```bash
-/dreaming status    # 查看状态
-/dreaming on        # 启用
-/dreaming off       # 禁用
-
-openclaw memory promote          # 预览待提升项
-openclaw memory promote --apply  # 执行提升
-openclaw memory promote-explain "关键词"  # 解释某候选
-openclaw memory rem-harness      # 预览 REM 反思
-```
-
-## 关键点
-
-- Deep 阶段需要 `minScore`、`minRecallCount`、`minUniqueQueries` 都通过才提升
-- 提升前会从原始文件重新验证片段，已删除的跳过
-- Dreaming 生成的日记条目不参与短期提升
+历史 backfill 先预览；`--stage-short-term` 只暂存候选，仍由 Deep 决定是否进入长期记忆。
diff --git a/references/memory-search.md b/references/memory-search.md
index 8c8b6c6..1cd934f 100644
--- a/references/memory-search.md
+++ b/references/memory-search.md
@@ -1,113 +1,49 @@
-# Memory Search 参考文档
+# Memory Search 参考
 
-> 来源：OpenClaw 官方文档
-> - https://docs.openclaw.ai/concepts/memory-search
-> - https://docs.openclaw.ai/reference/memory-config
-> - https://docs.openclaw.ai/concepts/memory-builtin
-> - https://docs.openclaw.ai/concepts/memory
+官方来源：
 
-## Memory Search 工作原理
+- https://docs.openclaw.ai/concepts/memory-search
+- https://docs.openclaw.ai/reference/memory-config
+- https://docs.openclaw.ai/concepts/memory
 
-两路并行检索，加权合并：
+## 当前关键点
 
-1. **Vector Search（向量搜索）**：通过 embedding 找语义相似的笔记
-2. **BM25 Keyword Search（关键词搜索）**：找精确匹配（ID、错误字符串、配置键）
+- 默认 builtin 引擎使用 per-agent SQLite、FTS/BM25 与可选向量检索。
+- 通用 OpenAI-compatible embeddings 端点使用 `provider: "openai-compatible"`，避免继承 OpenAI chat 凭据。
+- provider 也可指向兼容的 `models.providers.<id>`。
+- 显式远程 provider 运行时不可用会 fail closed；`provider: "none"` 才是明确的 FTS-only。
+- 改 provider、model、输入类型、sources、scope、chunking 或 tokenizer 后需要显式重建索引。
+- API Key 使用 SecretRef；Codex OAuth 不能用于 embeddings。
 
-如只有一路可用，另一路单独运行。
+## 官方默认值
 
-## Builtin Memory Engine（默认）
+- `chunking.tokens`: 400
+- `chunking.overlap`: 80
+- `query.maxResults`: 6
+- `query.minScore`: 0.35
+- `hybrid.enabled`: true
+- `hybrid.vectorWeight`: 0.7
+- `hybrid.textWeight`: 0.3
+- `hybrid.candidateMultiplier`: 4
+- `mmr.enabled`: false
+- `mmr.lambda`: 0.7
+- `temporalDecay.enabled`: false
+- `temporalDecay.halfLifeDays`: 30
 
-- 索引存储在 SQLite（per-agent）：`~/.openclaw/memory/<agentId>.sqlite`
-- FTS5 全文索引 + 可选 sqlite-vec 向量扩展
-- CJK 分词支持（中文/日文/韩文）
-- 文件变更自动触发 reindex（1.5s debounce）
-- 无额外依赖
+先用默认值。重复命中明显时启用 MMR；旧的 dated daily notes 经常压过新内容时启用 temporal decay。非日期文件和 `MEMORY.md` 不衰减。
 
-## Embedding Provider 配置
+## 可选能力
 
-```json
-{
-  "agents": {
-    "defaults": {
-      "memorySearch": {
-        "provider": "openai",
-        "model": "bge-large-zh-v1.5",
-        "remote": {
-          "baseUrl": "https://lapi.transiglobal.com/v1",
-          "apiKey": "YOUR_KEY"
-        }
-      }
-    }
-  }
-}
-```
+- 非对称 embeddings：设置 `queryInputType` 与 `documentInputType`。
+- session transcripts：同时启用 `experimental.sessionMemory` 并在 `sources` 加入 `sessions`；注意存储、隐私和索引成本。
+- QMD session search 还需 `memory.qmd.sessions.enabled: true`。
+- multimodal：仅对 `extraPaths` 下的图像/音频生效，需 Gemini embedding-2；会上传二进制内容，应明确确认。
+- local embeddings：需要官方 llama.cpp provider 插件；安装和原生构建必须单独安全审计与确认。
 
-### 支持的 Provider
+## 排障
 
-| Provider | ID | 自动检测 | 说明 |
-|----------|----|---------|------|
-| OpenAI | `openai` | ✅ | 默认 text-embedding-3-small |
-| Gemini | `gemini` | ✅ | 支持多模态（图片+音频） |
-| Voyage | `voyage` | ✅ | |
-| Mistral | `mistral` | ✅ | |
-| Ollama | `ollama` | ❌ 需显式设置 | 本地 |
-| Local | `local` | ✅ 优先级最高 | GGUF 模型，~0.6GB |
-
-自定义 OpenAI 兼容端点通过 `remote.baseUrl` + `remote.apiKey` 配置。
-
-## 搜索参数详解
-
-### 分块（Chunking）
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `chunking.tokens` | 400 | 每块 token 数 |
-| `chunking.overlap` | 80 | 块间重叠 |
-
-### 基础查询
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `query.maxResults` | — | 最大返回结果数 |
-| `query.minScore` | — | 最低相关度阈值 |
-
-### 混合搜索（Hybrid）
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `hybrid.enabled` | true | 启用混合搜索 |
-| `hybrid.vectorWeight` | 0.7 | 向量权重 |
-| `hybrid.textWeight` | 0.3 | 关键词权重 |
-| `hybrid.candidateMultiplier` | 4 | 候选池倍数 |
-
-### MMR 去重
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `mmr.enabled` | false | 启用 MMR 重排序 |
-| `mmr.lambda` | 0.7 | 0=最多样，1=最相关 |
-
-### 时间衰减
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `temporalDecay.enabled` | false | 启用时间衰减 |
-| `temporalDecay.halfLifeDays` | 30 | 半衰期天数 |
-
-> MEMORY.md 等常驻文件不参与衰减。
-
-## CLI 命令
-
-```bash
-openclaw memory status          # 查看索引状态
-openclaw memory status --deep   # 深度检查（含 embedding）
-openclaw memory index --force   # 强制重建索引
-openclaw memory search "query"  # 命令行搜索
-```
-
-## 故障排查
-
-- **无结果**：`openclaw memory status` 检查索引，空则 `openclaw memory index --force`
-- **只有关键词匹配**：embedding provider 未配置，检查 `openclaw memory status --deep`
-- **CJK 搜索失败**：`openclaw memory index --force` 重建 FTS
-- **sqlite-vec 加载失败**：自动降级为进程内余弦相似度计算
+- 无结果：`openclaw memory status`，必要时重建索引。
+- 只有关键词：用 `openclaw memory status --deep` 检查 embedding。
+- 显式 provider 不可用：修复认证/网络；不会静默退回 FTS。
+- CJK 检索异常：重建 FTS 索引。
+- `openclaw memory` 未注册：检查 active memory plugin，而不是直接重建。
diff --git a/references/memory-wiki.md b/references/memory-wiki.md
index 4af8528..3d1e142 100644
--- a/references/memory-wiki.md
+++ b/references/memory-wiki.md
@@ -1,116 +1,39 @@
-# Memory Wiki 参考文档
+# Memory Wiki 参考
 
-> 来源：OpenClaw 官方文档
-> - https://docs.openclaw.ai/plugins/memory-wiki
+官方来源：https://docs.openclaw.ai/plugins/memory-wiki
 
-## 概述
+Memory Wiki 是结构化知识层，不替代 active memory plugin。
 
-Memory Wiki 将持久记忆编译为结构化知识库，不替代 active memory plugin。
+## 当前配置选择
 
-## Vault 模式
+- `vaultMode`: `isolated`（默认）、`bridge`、`unsafe-local`
+- `vault.scope`: `global`（默认）或 `agent`
+- `vault.path`: global 默认 `~/.openclaw/wiki/main`；agent scope 默认父目录 `~/.openclaw/wiki`
+- `vault.renderMode`: `native`（默认）或 `obsidian`
+- `search.backend`: `shared`（默认）或 `local`
+- `search.corpus`: `wiki`（默认）、`memory`、`all`
 
-| 模式 | 说明 |
-|------|------|
-| `isolated` | 独立 vault，不依赖 memory-core |
-| `bridge` | 从 memory-core 读取公开 artifact |
-| `unsafe-local` | 本地文件系统直接访问（实验性） |
+Bridge 模式可导入 active memory plugin 的 public artifacts、Dream reports、daily notes、memory root 和 event logs。Agent-scoped bridge 会按 artifact 所属 agent 过滤。
 
-## Vault 目录结构
+`vault.scope` 改变不会复制或拆分现有 vault。多 agent 的 per-agent vault 是同进程知识边界，不是操作系统安全边界。
 
-```text
-<vault>/
-  AGENTS.md
-  WIKI.md
-  index.md
-  inbox.md
-  entities/      # 实体（人、系统、项目）
-  concepts/      # 概念、模式、策略
-  syntheses/     # 编译摘要
-  sources/       # 导入的原始材料
-  reports/       # 仪表板报告
-  _attachments/
-  _views/
-  .openclaw-wiki/
-```
+## 可选项
 
-## 配置（isolated 模式）
+- Obsidian 官方 CLI：`obsidian.useOfficialCli`
+- URL 导入：`ingest.allowUrlIngest`
+- compiled digest prompt：`context.includeCompiledDigestPrompt`
+- unsafe-local：必须显式允许 private memory-core access 并限定 paths
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "memory-wiki": {
-        "enabled": true,
-        "config": {
-          "vaultMode": "isolated",
-          "vault": {
-            "path": "~/.openclaw/wiki/main",
-            "renderMode": "obsidian"
-          },
-          "bridge": {
-            "enabled": false
-          },
-          "search": {
-            "backend": "shared",
-            "corpus": "all"
-          },
-          "render": {
-            "preserveHumanBlocks": true,
-            "createBacklinks": true,
-            "createDashboards": true
-          },
-          "ingest": {
-            "autoCompile": true,
-            "maxConcurrentJobs": 1
-          },
-          "obsidian": {
-            "enabled": true
-          }
-        }
-      }
-    }
-  }
-}
-```
+这些能力涉及依赖、网络、私有文件或 prompt 体积，不能默认开启。
 
-## 关键配置项
+## CLI
 
-| 配置项 | 说明 |
-|--------|------|
-| `vaultMode` | `isolated` / `bridge` / `unsafe-local` |
-| `vault.renderMode` | `native` 或 `obsidian` |
-| `search.backend` | `shared`（共享记忆搜索）或 `local` |
-| `search.corpus` | `wiki` / `memory` / `all` |
-| `render.createBacklinks` | 生成相关链接 |
-| `render.createDashboards` | 生成仪表板页面 |
-| `ingest.autoCompile` | 自动编译 |
-
-## Agent 工具
-
-| 工具 | 说明 |
-|------|------|
-| `wiki_status` | vault 模式、健康状态 |
-| `wiki_search` | 搜索 wiki 页面 |
-| `wiki_get` | 读取 wiki 页面 |
-| `wiki_apply` | 窄范围修改（synthesis/metadata） |
-| `wiki_lint` | 结构检查、provenance、矛盾、问题 |
-
-## CLI 命令
-
-```bash
-openclaw wiki status      # 状态
-openclaw wiki doctor      # 诊断
-openclaw wiki init        # 初始化
-openclaw wiki ingest <path>  # 导入内容
-openclaw wiki compile     # 编译
-openclaw wiki lint        # 检查
-openclaw wiki search "query"  # 搜索
-```
-
-## Bridge 模式可索引的内容
-
-- exported memory artifacts
-- dream reports
-- daily notes
-- memory root files
-- memory event logs
+- `openclaw wiki status`
+- `openclaw wiki doctor`
+- `openclaw wiki init`
+- `openclaw wiki ingest <path>`
+- `openclaw wiki compile`
+- `openclaw wiki lint`
+- `openclaw wiki search "query"`
+- `openclaw wiki bridge import`
+- `openclaw wiki obsidian status`