# OpenClaw 对话和记忆优化初步方案

> 研究日期：2026-02-17  
> 研究者：Ami + 阿米狗  
> 状态：已实施并上线

---

## 背景与目标

OpenClaw 默认配置下存在两个核心痛点：
1. **对话 context 超限**会直接中断会话，体验割裂
2. **记忆搜索被禁用**（需要 OpenAI/Gemini/Voyage API key，成本高）

本方案目标：在不依赖任何外部 API key 的前提下，实现：
- 对话 context 的主动管理（不被动等爆）
- 本地向量语义搜索（完全离线）
- 跨会话记忆自动恢复

---

## 核心约束

> 我们假设暂时解决不了对话 context 上限这一概念和顶层限制（200k token 硬上限由模型决定，无法改变）。
> 因此，所有优化都是在这个硬上限内做最大化利用。

---

## 三步方案

### Step 1 — Token 优化 + 自动压缩

**问题**：context 默认无上限地增长，直到 API 报错才触发压缩，体验差。

**解决**：

| 配置项 | 值 | 作用 |
|--------|-----|------|
| `contextTokens` | `120000` | 软上限，到达后触发剪枝（低于模型 200k 硬上限，留出安全边际） |
| `contextPruning.mode` | `cache-ttl` | 在 Anthropic 缓存 TTL 到期前删除老 tool output，减少 cacheWrite 费用 |
| `contextPruning.keepLastAssistants` | `3` | 保留最近 3 条 assistant 消息，删除更早的 |
| `compaction.mode` | `safeguard` | 确保 Pi runtime 的 compaction 有足够预留空间 |
| `compaction.reserveTokensFloor` | `20000` | compaction 预留底线 20k token（防止压缩时空间不足） |

**原理**：把原来的"被动爆仓"改成"主动管理"，在 context 超限前就开始清理。

---

### Step 2 — 新会话自动恢复历史（QMD 本地向量搜索）

**问题**：`memory_search` 工具默认需要 OpenAI/Gemini/Voyage embedding API，没有 key 则完全禁用。

**解决**：安装并启用 **QMD**（Quick Markdown / 本地向量搜索引擎）

#### QMD 是什么

- GitHub: [tobi/qmd](https://github.com/tobi/qmd)
- OpenClaw 官方支持的实验性本地搜索后端
- 技术栈：BM25 + 向量（node-llama-cpp）+ reranking
- **完全本地运行**，GGUF 模型首次自动下载，无 API key 需求

#### 安装步骤

```bash
# 1. 安装 Bun（QMD 运行时）
curl -fsSL https://bun.sh/install | bash

# 2. 安装 QMD
bun install -g https://github.com/tobi/qmd

# 3. 解锁 postinstall（bun 默认阻止）
cd ~/.bun/install/global && bun pm trust --all

# 4. 补充缺失的 @types/node 并 build
cd ~/.bun/install/global/node_modules/@tobilu/qmd
bun add -d @types/node && bun run build

# 5. 验证
qmd --version  # → qmd 1.0.6
```

**注意**：`bun install -g` 安装的 qmd 包没有预编译 dist，需要手动 build TypeScript 源码。这是一个安装坑，已记录。

#### OpenClaw 配置

```json
{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "command": "/Users/mini/.bun/bin/qmd",
      "includeDefaultMemory": true,
      "sessions": {
        "enabled": true,
        "retentionDays": 30
      },
      "update": {
        "interval": "5m",
        "debounceMs": 15000
      },
      "limits": {
        "maxResults": 6,
        "timeoutMs": 4000
      },
      "scope": {
        "default": "deny",
        "rules": [{ "action": "allow", "match": { "chatType": "direct" } }]
      }
    }
  }
}
```

**关键配置说明**：
- `backend: "qmd"` — 切换为本地引擎（替代内置 SQLite 索引）
- `sessions.enabled: true` — 自动导出 session 对话记录到 QMD 索引（实现跨会话搜索）
- `retentionDays: 30` — 保留 30 天历史
- `scope.rules` — 仅限直接私聊可搜索（不在群组里暴露私人记忆）
- `citations: "auto"` — 搜索结果自动附带来源文件路径

**效果**：新会话开始时，`memory_search` 可以检索过去 30 天的对话历史摘要和记忆文件，自动恢复上下文。

---

### Step 3 — Context 快满时自动提醒

**问题**：用户不知道 context 什么时候快满，只能被动等待中断。

**解决**：在压缩前的"软阈值"触发主动通知

#### 工作流程

```
context 使用量
    ↓
[120k 软上限] → contextPruning 开始清理老消息
    ↓
[还剩 ~5k token] → memoryFlush 触发（比 compaction 更早）
    ↓
    ├── 1. 把重要上下文写入 memory/YYYY-MM-DD.md
    └── 2. 发 Telegram 通知：⚠️ 对话快满了，建议发 /new
    ↓
[用户发 /new 开启新会话]
    ↓
[新会话] → memory_search 自动检索历史 → 无缝续接
```

#### 配置

```json
{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 5000,
          "prompt": "Context is nearing the compaction limit. Do TWO things:\n1. Write important context/decisions from this conversation to memory/YYYY-MM-DD.md (today's date).\n2. Use the message tool to send a Telegram notification to the user (target: 5588544200, channel: telegram) saying: '⚠️ 对话快满了，建议发 /new 开启新会话，我会自动从历史记忆中恢复上下文。'\nReply with NO_REPLY after completing both steps.",
          "systemPrompt": "Pre-compaction housekeeping: persist memories and notify user. Silent turn."
        }
      }
    }
  }
}
```

**原理**：
- `softThresholdTokens: 5000` — 在 Pi runtime 触发 compaction **之前** 5000 token 就介入
- `prompt` 中的双任务：写记忆 + 发通知
- `NO_REPLY` — 对话中不显示任何内容（静默操作），但 tools 仍然执行（Telegram 消息照常发）

---

## 整体架构图

```
用户对话
  │
  ▼
[OpenClaw Gateway]
  │
  ├── contextTokens: 120k → 软上限保护
  ├── contextPruning: cache-ttl → 清理老 tool output
  │
  ├── [context 剩 5k] → memoryFlush 触发
  │     ├── 写 memory/YYYY-MM-DD.md
  │     └── 发 Telegram 通知 → 用户
  │
  ├── compaction: safeguard → 自动压缩摘要（最后防线）
  │
  └── [用户 /new 开新会话]
        │
        ▼
  [新会话启动 — AGENTS.md 规则]
        ├── 自动读取 MEMORY.md（系统注入）
        ├── 自动读取 memory/今日+昨日.md（系统注入）
        └── 自动调用 memory_search("最近对话 上下文")
              │
              ▼
        QMD 本地向量索引（上限 5k tokens）
          ├── MEMORY.md（长期记忆）
          ├── memory/*.md（日志）
          └── sessions/*.jsonl（30天对话历史）
              │
              ▼
        自动恢复上下文，无缝续接
```

---

## Step 4 — 新会话自动触发历史检索（AGENTS.md 规则）

**问题**：QMD 搜索是"按需"的，新会话开始时需要主动触发，否则历史上下文不会自动加载。

**解决**：在 `AGENTS.md` 的"每次会话"规则中加入自动搜索指令。

#### 触发机制说明

| 层级 | 内容 | 加载方式 |
|------|------|----------|
| `MEMORY.md` | 长期记忆（核心事实、偏好） | 系统自动注入 context |
| `memory/YYYY-MM-DD.md` | 今日 + 昨日日志 | 系统自动注入 context |
| QMD session 历史 | 近 30 天对话记录 | **需调用 `memory_search` 触发** |

#### AGENTS.md 新增规则

```markdown
## Every Session

Before doing anything else:
1. Read SOUL.md — this is who you are
2. Read USER.md — this is who you're helping
3. Read memory/YYYY-MM-DD.md (today + yesterday) for recent context
4. **If in MAIN SESSION**: Also read MEMORY.md
5. **If in MAIN SESSION**: Run memory_search("最近对话 上下文") to retrieve
   relevant history from QMD — restore any ongoing topics or tasks automatically
```

**Token 消耗评估**：

| 场景 | 消耗 |
|------|------|
| QMD 本地搜索计算 | 0（纯本地） |
| 搜索结果注入 context | 1k–5k tokens |
| 上限（`maxInjectedChars: 20000`） | ~5000 tokens 硬上限 |

**`maxInjectedChars` 的作用**：无论搜到多少内容，最终注入 context 的字符数不超过 20000（约 5000 tokens），防止历史检索本身消耗过多 context 空间。

#### QMD limits 完整配置

```json
{
  "memory": {
    "qmd": {
      "limits": {
        "maxResults": 6,
        "maxSnippetChars": 700,
        "maxInjectedChars": 20000,
        "timeoutMs": 4000
      }
    }
  }
}
```

**效果**：开新会话后无需任何提示，我会自动检索近期历史并将相关上下文带入当前会话，实现无缝续接。

---

## 当前局限性

1. **QMD 首次搜索较慢**：需要自动下载 GGUF 模型（reranker + query expansion），约几百 MB
2. **session 索引延迟**：对话结束后才导出，不是实时的
3. **根本上限无法突破**：200k token 硬上限由 Anthropic 决定，所有优化只是更好地利用这 200k
4. **QMD build 依赖**：安装时需要手动 build TypeScript（bun 全局安装的包缺少 dist 目录，已知坑）

---

## 文件位置

| 文件 | 说明 |
|------|------|
| `~/.openclaw/openclaw.json` | 所有配置的实际存储位置 |
| `/Users/mini/clawd/MEMORY.md` | 长期记忆（每次主会话加载） |
| `/Users/mini/clawd/memory/YYYY-MM-DD.md` | 每日日志 |
| `~/.openclaw/agents/main/qmd/` | QMD 索引数据库 + 缓存 |
| `~/.openclaw/agents/main/sessions/*.jsonl` | 对话历史（被 QMD 索引）|

---

## 后续可探索方向

- **3层记忆架构**（@Ktaohzk 方案）：Fact/Belief 分层 + 衰减评分，进一步减少 token 占用
- **session memory search 实验性功能**：`memorySearch.experimental.sessionMemory: true`（内置 SQLite 版的 session 索引，与 QMD sessions 二选一）
- **混合搜索调优**：调整 `vectorWeight` / `textWeight` 比例优化检索精度
- **embedding 缓存**：`memorySearch.cache.enabled: true` 避免重复 embedding

---

*本文档由 Ami + 阿米狗共同研究整理，2026-02-17，v1.1 更新于同日*