docs: 添加 memory-search/dreaming/memory-wiki 官方参考文档

2026-04-21 13:44:35 +08:00
parent 147846c665
commit b7e1a5d34f
4 changed files with 321 additions and 0 deletions
@@ -281,6 +281,19 @@ cron add:
 | 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` 强制重建
@@ -0,0 +1,79 @@
+# Dreaming 参考文档
+
+> 来源：OpenClaw 官方文档
+> - https://docs.openclaw.ai/concepts/dreaming
+
+## 概述
+
+Dreaming 是后台记忆整理系统，将短期信号整理为持久记忆。**默认禁用，需手动开启。**
+
+## 三个阶段
+
+| 阶段 | 目的 | 持久写入 |
+|------|------|---------|
+| **Light** | 排序和暂存短期材料 | 否 |
+| **Deep** | 评分并提升到长期记忆 | ✅ 写入 MEMORY.md |
+| **REM** | 反思主题和重复模式 | 否 |
+
+## 配置
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memory-core": {
+        "enabled": true,
+        "config": {
+          "dreaming": {
+            "enabled": true,
+            "frequency": "0 3 * * *",
+            "timezone": "Asia/Shanghai"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | false | 是否启用 |
+| `frequency` | `0 3 * * *` | 执行频率（cron 表达式） |
+| `timezone` | 系统时区 | 时区 |
+
+## 输出文件
+
+- `DREAMS.md`（或 `dreams.md`）：人类可读的梦境日记
+- `memory/dreaming/<phase>/YYYY-MM-DD.md`：阶段报告
+- `memory/.dreams/`：机器状态（recall store、信号、检查点）
+
+## Deep 排序信号（6个权重）
+
+| 信号 | 权重 | 说明 |
+|------|------|------|
+| 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 生成的日记条目不参与短期提升
@@ -0,0 +1,113 @@
+# 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 工作原理
+
+两路并行检索，加权合并：
+
+1. **Vector Search（向量搜索）**：通过 embedding 找语义相似的笔记
+2. **BM25 Keyword Search（关键词搜索）**：找精确匹配（ID、错误字符串、配置键）
+
+如只有一路可用，另一路单独运行。
+
+## Builtin Memory Engine（默认）
+
+- 索引存储在 SQLite（per-agent）：`~/.openclaw/memory/<agentId>.sqlite`
+- FTS5 全文索引 + 可选 sqlite-vec 向量扩展
+- CJK 分词支持（中文/日文/韩文）
+- 文件变更自动触发 reindex（1.5s debounce）
+- 无额外依赖
+
+## Embedding Provider 配置
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "provider": "openai",
+        "model": "bge-large-zh-v1.5",
+        "remote": {
+          "baseUrl": "https://lapi.transiglobal.com/v1",
+          "apiKey": "YOUR_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+### 支持的 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 加载失败**：自动降级为进程内余弦相似度计算
@@ -0,0 +1,116 @@
+# Memory Wiki 参考文档
+
+> 来源：OpenClaw 官方文档
+> - https://docs.openclaw.ai/plugins/memory-wiki
+
+## 概述
+
+Memory Wiki 将持久记忆编译为结构化知识库，不替代 active memory plugin。
+
+## Vault 模式
+
+| 模式 | 说明 |
+|------|------|
+| `isolated` | 独立 vault，不依赖 memory-core |
+| `bridge` | 从 memory-core 读取公开 artifact |
+| `unsafe-local` | 本地文件系统直接访问（实验性） |
+
+## Vault 目录结构
+
+```text
+<vault>/
+  AGENTS.md
+  WIKI.md
+  index.md
+  inbox.md
+  entities/      # 实体（人、系统、项目）
+  concepts/      # 概念、模式、策略
+  syntheses/     # 编译摘要
+  sources/       # 导入的原始材料
+  reports/       # 仪表板报告
+  _attachments/
+  _views/
+  .openclaw-wiki/
+```
+
+## 配置（isolated 模式）
+
+```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
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## 关键配置项
+
+| 配置项 | 说明 |
+|--------|------|
+| `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