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

2026-07-15 13:41:03 +08:00
parent b7e1a5d34f
commit ebd3e3194c
6 changed files with 433 additions and 557 deletions
@@ -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。测试外发前需用户明确同意。
@@ -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 决定是否进入长期记忆。
@@ -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，而不是直接重建。
@@ -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`