refactor: 对齐最新记忆与commitments文档
This commit is contained in:
OpenClaw Backup Bot
@@ -1,54 +1,66 @@
|
|||||||
# openclaw-memory-config
|
# 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** — 基于向量的语义记忆搜索
|
## 默认 Embedding
|
||||||
2. **Dreaming** — 夜间自动记忆整理（短期 → 长期）
|
|
||||||
3. **Memory Wiki** — 结构化知识库（isolated 模式）
|
|
||||||
|
|
||||||
## Embedding 服务
|
- Provider：`openai-compatible`
|
||||||
|
- Base URL：`https://lapi.transiglobal.com/v1`
|
||||||
|
- Model：`bge-large-zh-v1.5`
|
||||||
|
- Credential：`TRAPI_API_KEY` SecretRef
|
||||||
|
|
||||||
默认使用传米科技 trapi 的 embedding 端点：
|
不会要求用户在聊天中粘贴明文 API Key。已有可解析 SecretRef 会优先保留。
|
||||||
|
|
||||||
| 项目 | 值 |
|
|
||||||
|------|-----|
|
|
||||||
| 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 信息
|
|
||||||
|
|
||||||
## 使用方式
|
## 使用方式
|
||||||
|
|
||||||
### 安装技能
|
|
||||||
|
|
||||||
```bash
|
|
||||||
openclaw skill install openclaw-memory-config.skill
|
|
||||||
```
|
|
||||||
|
|
||||||
### 配置
|
|
||||||
|
|
||||||
在 OpenClaw 对话中说：
|
在 OpenClaw 对话中说：
|
||||||
|
|
||||||
> "配置记忆"
|
> 配置记忆
|
||||||
|
|
||||||
技能会引导完成：
|
技能会先读取当前版本、Schema、active memory plugin、Memory Search、Dreaming、Commitments、Heartbeat 和 Wiki 状态，再给出最小变更方案。
|
||||||
1. **Memory Search**：配置 embedding → 构建索引 → 测试搜索
|
|
||||||
2. **Dreaming**：启用夜间记忆整理（每天 4:30 自动运行）
|
|
||||||
3. **Memory Wiki**：确认内容目录 → 初始化 vault → 导入内容 → 创建每日维护定时任务
|
|
||||||
|
|
||||||
### 安全说明
|
所有配置写入遵循：
|
||||||
|
|
||||||
- API Key 必须由用户提供，技能中不存储默认密钥
|
1. 创建配置备份。
|
||||||
- Memory Wiki 默认使用 isolated 模式，数据完全独立
|
2. 使用 `openclaw config set/patch --dry-run` 验证。
|
||||||
- 所有配置通过 `gateway config.patch` 标准方式写入
|
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)
|
||||||
|
|
||||||
## 许可证
|
## 许可证
|
||||||
|
|
||||||
|
|||||||
@@ -1,78 +1,129 @@
|
|||||||
---
|
---
|
||||||
name: openclaw-memory-config
|
name: "openclaw-memory-config"
|
||||||
description: |
|
description: "按最新官方 Memory 与 Commitments 文档安全配置 OpenClaw 记忆系统"
|
||||||
配置 OpenClaw 记忆系统：Memory Search（向量搜索）、Dreaming（记忆整理）、Memory Wiki（知识库）。触发词："配置记忆"、"配置 memory"、"memory search"、"配置搜索"、"配置 dreaming"、"配置梦境"、"配置 wiki"、"memory wiki"、"记忆配置"。使用本机已有 trapi embedding 端点，为用户提供完整的记忆系统初始化流程。
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# OpenClaw 记忆系统配置
|
# OpenClaw 记忆系统配置
|
||||||
|
|
||||||
一键配置 OpenClaw 记忆系统，包含 Memory Search（向量语义搜索）、Dreaming（夜间记忆整理）、Memory Wiki（知识库）三大模块。
|
依据当前 OpenClaw Schema 和官方文档做最小、可回滚的配置。默认使用 builtin memory；不得在未确认时替换第三方 memory slot、重建大索引、开启后台模型调用或创建对外通知。
|
||||||
|
|
||||||
## Embedding 服务信息（默认）
|
官方基线：
|
||||||
|
|
||||||
- **Provider**：`openai`（OpenAI 兼容格式）
|
- Memory overview: https://docs.openclaw.ai/concepts/memory
|
||||||
- **Base URL**：`https://lapi.transiglobal.com/v1`
|
- Memory search: https://docs.openclaw.ai/concepts/memory-search
|
||||||
- **默认模型**：`bge-large-zh-v1.5`
|
- Commitments: https://docs.openclaw.ai/concepts/commitments
|
||||||
- **API Key 来源**：优先复用本地已配置的 trapi provider；如未配置则要求用户提供
|
- 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 已安装并运行
|
- 先读当前 Schema 和配置，再写入；不同 OpenClaw 版本可能有字段差异。
|
||||||
2. 本机配置文件为 `openclaw.json`，使用 `gateway config.patch` 写入
|
- 使用 `openclaw config get/set/patch/validate`。所有写入先 `--dry-run`，成功后再执行正式写入。
|
||||||
3. Embedding API Key：
|
- `config get` 只用于读取脱敏快照。不得提取、打印或复制明文 API Key。
|
||||||
- **优先**：检查本地 `models.providers.trapi.apiKey` 是否已配置，已配置则复用
|
- 凭据优先使用 SecretRef；不得要求用户在聊天中粘贴密钥。
|
||||||
- **兜底**：如 trapi 未配置，向用户提供两种选择：
|
- 变更 `plugins.entries` 后按 CLI 提示重启 Gateway；不要自行停止 Gateway。
|
||||||
- a) 提供 trapi API Key（使用默认 trapi embedding 端点）
|
- 改变 embedding provider、模型、输入类型、来源、chunking 或 tokenizer 会改变索引身份。先说明重建成本，再运行 `openclaw memory index --force`。
|
||||||
- b) 提供其他 embedding provider 信息（provider、baseUrl、apiKey、model）
|
- 显式提醒和精确定时任务使用 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`，无需用户额外提供，跳到下一步
|
```bash
|
||||||
- **未配置 trapi**：向用户说明两种选择：
|
openclaw backup create --only-config --verify
|
||||||
- a) 提供 trapi API Key → 使用默认配置（baseUrl + bge-large-zh-v1.5）
|
```
|
||||||
- b) 提供自定义 embedding provider 信息（需确认 provider、baseUrl、apiKey、model）
|
|
||||||
|
|
||||||
如用户拒绝提供任何 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": {
|
agents: {
|
||||||
"defaults": {
|
defaults: {
|
||||||
"memorySearch": {
|
memorySearch: {
|
||||||
"provider": "openai",
|
enabled: true,
|
||||||
"model": "bge-large-zh-v1.5",
|
provider: "openai-compatible",
|
||||||
"remote": {
|
model: "bge-large-zh-v1.5",
|
||||||
"baseUrl": "https://lapi.transiglobal.com/v1",
|
remote: {
|
||||||
"apiKey": "<用户提供的API_KEY>"
|
baseUrl: "https://lapi.transiglobal.com/v1",
|
||||||
},
|
apiKey: {
|
||||||
"chunking": {
|
source: "env",
|
||||||
"tokens": 200,
|
provider: "default",
|
||||||
"overlap": 30
|
id: "TRAPI_API_KEY"
|
||||||
},
|
|
||||||
"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
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -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` 调整。
|
||||||
|
|
||||||
| 参数组 | 参数 | 值 | 说明 |
|
对需要 `input_type` 的非对称 embedding 模型，按供应商要求设置 `queryInputType` 与 `documentInputType`，并重建索引。
|
||||||
|--------|------|-----|------|
|
|
||||||
| **分块** | `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 等常驻文件不衰减 |
|
|
||||||
|
|
||||||
> 以上参数适用于大多数场景，用户一般无需调整。如需微调可在配置完成后通过 `gateway config.patch` 修改。
|
### 3.2 验证
|
||||||
|
|
||||||
配置写入后，立即执行：
|
若 active plugin 注册了官方 memory CLI：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
openclaw memory status --deep
|
||||||
openclaw memory index --force
|
openclaw memory index --force
|
||||||
|
openclaw memory search "一个确实存在于记忆中的关键词"
|
||||||
```
|
```
|
||||||
|
|
||||||
### 步骤 3：测试搜索
|
只在索引身份改变或索引损坏时强制重建。若 `openclaw memory` 未注册，先检查 active memory plugin 与 Gateway 状态；第三方插件使用其自带诊断工具，不把“未知命令”误判为索引为空。
|
||||||
|
|
||||||
索引构建完成后，用 `memory_search` 测试是否生效：
|
测试应选择当前 workspace 中已存在、非敏感的关键词，并检查命中来源和相关性。
|
||||||
|
|
||||||
1. 从用户的 memory 目录中找到已有内容的关键词
|
## 4. Automatic memory flush
|
||||||
2. 执行 `memory_search` 搜索
|
|
||||||
3. 确认能返回相关结果，报告搜索质量
|
|
||||||
|
|
||||||
**测试关键词示例**（根据实际记忆内容选择）：
|
compaction 前的 memory flush 默认开启。读取 `agents.defaults.compaction.memoryFlush`：
|
||||||
- 搜索 "传米科技" → 应找到公司相关信息
|
|
||||||
- 搜索 "Tailscale" → 应找到网络配置信息
|
|
||||||
- 搜索最近的日期 → 应找到当天的日记
|
|
||||||
|
|
||||||
### 验证报告
|
- 未配置：保留默认开启。
|
||||||
|
- 被明确关闭：说明上下文压缩前可能丢失尚未落盘的重要信息，再询问是否恢复。
|
||||||
|
- 仅在用户要求降低主模型成本时设置专用 `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
|
```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 init
|
||||||
openclaw wiki ingest <用户提供的内容目录>
|
openclaw wiki lint
|
||||||
openclaw wiki compile
|
openclaw wiki search "已导入内容中的关键词"
|
||||||
```
|
```
|
||||||
|
|
||||||
### 步骤 3：创建每日维护定时任务
|
只有用户提供并确认内容路径后才执行 `openclaw wiki ingest <path>` 和 `openclaw wiki compile`。
|
||||||
|
|
||||||
创建定时任务（参考已有配置），每天凌晨 5:00 执行 Wiki 维护：
|
## 8. 最终验证与报告
|
||||||
|
|
||||||
```
|
执行：
|
||||||
cron add:
|
|
||||||
name: "Wiki 每日维护（Sources 同步 + Lint）"
|
```bash
|
||||||
schedule: "0 5 * * *" (Asia/Shanghai)
|
openclaw config validate --json
|
||||||
sessionTarget: "isolated"
|
openclaw plugins doctor
|
||||||
payload:
|
openclaw gateway status --json --require-rpc
|
||||||
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"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 验证
|
按启用模块追加：
|
||||||
|
|
||||||
- `wiki_status` 确认 vault 模式和健康状态
|
- Memory Search：provider/模型/索引身份、深度状态、真实关键词搜索。
|
||||||
- `wiki_search` 测试能否搜到导入的内容
|
- Dreaming：`/dreaming status`、managed sweep 是否存在、下次运行时间。
|
||||||
- `wiki_lint` 检查结构完整性
|
- 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 失败**：确认目录路径和文件权限
|
|
||||||
|
|||||||
@@ -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。测试外发前需用户明确同意。
|
||||||
+26
-66
@@ -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：排序和暂存短期材料，不写 `MEMORY.md`。
|
||||||
|------|------|---------|
|
- REM：生成主题反思，不写 `MEMORY.md`。
|
||||||
| **Light** | 排序和暂存短期材料 | 否 |
|
- Deep：通过 score、recall count、query diversity 门槛后提升到 `MEMORY.md`。
|
||||||
| **Deep** | 评分并提升到长期记忆 | ✅ 写入 MEMORY.md |
|
|
||||||
| **REM** | 反思主题和重复模式 | 否 |
|
机器状态位于 `memory/.dreams/`；人类审阅输出位于 `DREAMS.md`，可选阶段报告位于 `memory/dreaming/<phase>/YYYY-MM-DD.md`。Diary/report 不作为 promotion 来源。
|
||||||
|
|
||||||
## 配置
|
## 配置
|
||||||
|
|
||||||
```json
|
路径：`plugins.entries.memory-core.config.dreaming`
|
||||||
{
|
|
||||||
"plugins": {
|
|
||||||
"entries": {
|
|
||||||
"memory-core": {
|
|
||||||
"enabled": true,
|
|
||||||
"config": {
|
|
||||||
"dreaming": {
|
|
||||||
"enabled": true,
|
|
||||||
"frequency": "0 3 * * *",
|
|
||||||
"timezone": "Asia/Shanghai"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
| 配置项 | 默认值 | 说明 |
|
- `enabled`: 默认 false
|
||||||
|--------|--------|------|
|
- `frequency`: 默认 `0 3 * * *`
|
||||||
| `enabled` | false | 是否启用 |
|
- `model`: 可选 Dream Diary 模型
|
||||||
| `frequency` | `0 3 * * *` | 执行频率（cron 表达式） |
|
- `phases.deep.maxPromotedSnippetTokens`: 默认 160
|
||||||
| `timezone` | 系统时区 | 时区 |
|
|
||||||
|
|
||||||
## 输出文件
|
设置 `dreaming.model` 时必须启用 `plugins.entries.memory-core.subagent.allowModelOverride`，并建议用 `allowedModels` 限制规范的 `provider/model`。
|
||||||
|
|
||||||
- `DREAMS.md`（或 `dreams.md`）：人类可读的梦境日记
|
## CLI
|
||||||
- `memory/dreaming/<phase>/YYYY-MM-DD.md`：阶段报告
|
|
||||||
- `memory/.dreams/`：机器状态（recall store、信号、检查点）
|
|
||||||
|
|
||||||
## 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`
|
||||||
|
|
||||||
| 信号 | 权重 | 说明 |
|
历史 backfill 先预览；`--stage-short-term` 只暂存候选，仍由 Deep 决定是否进入长期记忆。
|
||||||
|------|------|------|
|
|
||||||
| 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 生成的日记条目不参与短期提升
|
|
||||||
|
|||||||
+38
-102
@@ -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 找语义相似的笔记
|
- 默认 builtin 引擎使用 per-agent SQLite、FTS/BM25 与可选向量检索。
|
||||||
2. **BM25 Keyword Search（关键词搜索）**：找精确匹配（ID、错误字符串、配置键）
|
- 通用 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`
|
先用默认值。重复命中明显时启用 MMR；旧的 dated daily notes 经常压过新内容时启用 temporal decay。非日期文件和 `MEMORY.md` 不衰减。
|
||||||
- FTS5 全文索引 + 可选 sqlite-vec 向量扩展
|
|
||||||
- CJK 分词支持（中文/日文/韩文）
|
|
||||||
- 文件变更自动触发 reindex（1.5s debounce）
|
|
||||||
- 无额外依赖
|
|
||||||
|
|
||||||
## Embedding Provider 配置
|
## 可选能力
|
||||||
|
|
||||||
```json
|
- 非对称 embeddings：设置 `queryInputType` 与 `documentInputType`。
|
||||||
{
|
- session transcripts：同时启用 `experimental.sessionMemory` 并在 `sources` 加入 `sessions`；注意存储、隐私和索引成本。
|
||||||
"agents": {
|
- QMD session search 还需 `memory.qmd.sessions.enabled: true`。
|
||||||
"defaults": {
|
- multimodal：仅对 `extraPaths` 下的图像/音频生效，需 Gemini embedding-2；会上传二进制内容，应明确确认。
|
||||||
"memorySearch": {
|
- local embeddings：需要官方 llama.cpp provider 插件；安装和原生构建必须单独安全审计与确认。
|
||||||
"provider": "openai",
|
|
||||||
"model": "bge-large-zh-v1.5",
|
|
||||||
"remote": {
|
|
||||||
"baseUrl": "https://lapi.transiglobal.com/v1",
|
|
||||||
"apiKey": "YOUR_KEY"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 支持的 Provider
|
## 排障
|
||||||
|
|
||||||
| Provider | ID | 自动检测 | 说明 |
|
- 无结果：`openclaw memory status`，必要时重建索引。
|
||||||
|----------|----|---------|------|
|
- 只有关键词：用 `openclaw memory status --deep` 检查 embedding。
|
||||||
| OpenAI | `openai` | ✅ | 默认 text-embedding-3-small |
|
- 显式 provider 不可用：修复认证/网络；不会静默退回 FTS。
|
||||||
| Gemini | `gemini` | ✅ | 支持多模态（图片+音频） |
|
- CJK 检索异常：重建 FTS 索引。
|
||||||
| Voyage | `voyage` | ✅ | |
|
- `openclaw memory` 未注册：检查 active memory plugin，而不是直接重建。
|
||||||
| 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 加载失败**：自动降级为进程内余弦相似度计算
|
|
||||||
|
|||||||
+28
-105
@@ -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`
|
||||||
|
|
||||||
| 模式 | 说明 |
|
Bridge 模式可导入 active memory plugin 的 public artifacts、Dream reports、daily notes、memory root 和 event logs。Agent-scoped bridge 会按 artifact 所属 agent 过滤。
|
||||||
|------|------|
|
|
||||||
| `isolated` | 独立 vault，不依赖 memory-core |
|
|
||||||
| `bridge` | 从 memory-core 读取公开 artifact |
|
|
||||||
| `unsafe-local` | 本地文件系统直接访问（实验性） |
|
|
||||||
|
|
||||||
## 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
|
这些能力涉及依赖、网络、私有文件或 prompt 体积，不能默认开启。
|
||||||
{
|
|
||||||
"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
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 关键配置项
|
## CLI
|
||||||
|
|
||||||
| 配置项 | 说明 |
|
- `openclaw wiki status`
|
||||||
|--------|------|
|
- `openclaw wiki doctor`
|
||||||
| `vaultMode` | `isolated` / `bridge` / `unsafe-local` |
|
- `openclaw wiki init`
|
||||||
| `vault.renderMode` | `native` 或 `obsidian` |
|
- `openclaw wiki ingest <path>`
|
||||||
| `search.backend` | `shared`（共享记忆搜索）或 `local` |
|
- `openclaw wiki compile`
|
||||||
| `search.corpus` | `wiki` / `memory` / `all` |
|
- `openclaw wiki lint`
|
||||||
| `render.createBacklinks` | 生成相关链接 |
|
- `openclaw wiki search "query"`
|
||||||
| `render.createDashboards` | 生成仪表板页面 |
|
- `openclaw wiki bridge import`
|
||||||
| `ingest.autoCompile` | 自动编译 |
|
- `openclaw wiki obsidian status`
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user