---
name: "openclaw-memory-config"
description: "按最新官方 Memory 与 Commitments 文档安全配置 OpenClaw 记忆系统"
---

# OpenClaw 记忆系统配置

依据当前 OpenClaw Schema 和官方文档做最小、可回滚的配置。默认使用 builtin memory；不得在未确认时替换第三方 memory slot、重建大索引、开启后台模型调用或创建对外通知。

官方基线：

- 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

## 原则

- 先读当前 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. 预检与备份

先执行只读检查：

```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
```

缺失路径可视为未配置，不是失败。需要写配置前创建配置备份：

```bash
openclaw backup create --only-config --verify
```

再用 `openclaw config schema` 或当前版本官方文档确认目标字段存在。若当前版本不支持 `commitments`、目标 provider 或 Wiki 字段，停止并建议先升级 OpenClaw，不写未知字段。

## 1. 明确记忆层级

向用户说明：

- `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: {
        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"
          }
        }
      }
    }
  }
}
```

```bash
openclaw config patch --file ./memory-search.patch.json5 --dry-run
openclaw config patch --file ./memory-search.patch.json5
openclaw config validate --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`，并重建索引。

### 3.2 验证

若 active plugin 注册了官方 memory CLI：

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

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

测试应选择当前 workspace 中已存在、非敏感的关键词，并检查命中来源和相关性。

## 4. Automatic memory flush

compaction 前的 memory flush 默认开启。读取 `agents.defaults.compaction.memoryFlush`：

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

不要为了“显式化默认值”写冗余配置。

## 5. Dreaming

Dreaming 属于 `memory-core`，默认关闭。它自管一个去重后的 full-sweep cron；不要再创建第二个外部 Dreaming cron。

启用前确认：

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

基础配置路径：

```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 lint
openclaw wiki search "已导入内容中的关键词"
```

只有用户提供并确认内容路径后才执行 `openclaw wiki ingest <path>` 和 `openclaw wiki compile`。

## 8. 最终验证与报告

执行：

```bash
openclaw config validate --json
openclaw plugins doctor
openclaw gateway status --json --require-rpc
```

按启用模块追加：

- Memory Search：provider/模型/索引身份、深度状态、真实关键词搜索。
- Dreaming：`/dreaming status`、managed sweep 是否存在、下次运行时间。
- Commitments：配置、heartbeat 投递条件、pending/all 列表；外发测试仅在用户同意后进行。
- Wiki：status、doctor、lint 和真实内容搜索。

报告必须列出：变更前后、备份位置、实际写入路径、是否重启、索引是否重建、后台模型成本、外发条件、跳过项和未解决告警。