OpenClaw Memory — 配置、优化与故障排查

核心原理

OpenClaw 的记忆机制本质上是磁盘上的纯 Markdown 文件。这些文件即为唯一可信数据源（Single Source of Truth）。 模型仅“记住”被写入磁盘的内容——会话之间无任何内容保留在内存（RAM）中。 记忆搜索功能由当前启用的记忆插件提供（默认为 memory-core）。

1. 记忆架构（双层结构）

第 1 层：每日日志 — memory/YYYY-MM-DD.md

• 仅追加（Append-only）的会话笔记、运行上下文及当日事件记录。
• OpenClaw 在会话启动时自动读取今日 + 昨日的日志文件。
• 若有人提出“请记住这个”，应立即写入该文件。
• 日志随时间持续累积；旧日志可通过 memory_search 进行全文检索。

第 2 层：长期记忆 — MEMORY.md

• 人工维护的持久化事实：关键决策、用户偏好、铁律规则、项目背景等。
• 仅在私有/主会话（private/main sessions）启动时加载（群组上下文中永不加载）。
• 若同时存在 MEMORY.md 和 memory.md，仅加载 MEMORY.md。
• 务必保持简洁——非每会话必需的内容均应放入每日日志。
• 单文件超过约 20,000 字符将被截断（受 bootstrapMaxChars 限制）。
• 所有工作区文件合计引导容量上限约为 150,000 字符。

工作区目录结构

~/.openclaw/workspace/
├── MEMORY.md              # 长期人工维护的记忆（仅主会话加载）
├── memory/
│   ├── 2026-03-17.md      # 今日日志
│   ├── 2026-03-16.md      # 昨日日志（同样自动加载）
│   └── ...                # 更早的日志（可检索，但不自动加载）
├── AGENTS.md              # 运行手册、启动流程
├── SOUL.md                # 角色设定、语气风格、价值观
├── USER.md                # 用户档案
└── TOOLS.md               # 环境特定配置

内容归类指南

2. 记忆工具

OpenClaw 向 Agent 暴露两类面向用户的工具：

memory_search — 语义召回

• 在所有已索引的记忆文件（MEMORY.md + 所有每日日志）中执行搜索。
• 返回结果片段（最大约 700 字符）、文件路径、行号范围及匹配得分。
• 采用混合搜索策略：向量相似度 + BM25 关键词匹配。
• 向量搜索可识别同义改写（例如：“部署流程”可匹配“我们如何发布代码”）。
• BM25 可精准匹配具体标记（ID、环境变量、错误字符串、代码符号等）。
• 结果按加权融合排序：finalScore = vectorWeight × vectorScore + textWeight × textScore。

memory_get — 定向文件读取

• 根据指定路径（及可选行号范围）读取特定记忆文件。
• 若文件不存在，则优雅降级（返回空文本，不报错）。
• 适用于你已明确知道所需信息所在文件的场景。

最佳实践：强制执行记忆检索

请将以下规则加入 AGENTS.md：

## 记忆协议
- 执行涉及历史上下文的任务前，必须先运行 memory_search。
- 切勿仅凭对话历史猜测——务必查阅你的笔记。

若未设置此规则，Agent 将倾向于猜测而非主动检查记忆文件。

3. 压缩（Compaction）与记忆刷新（Memory Flush）

问题背景

长对话会迅速填满上下文窗口。当达到阈值时，OpenClaw 将执行压缩（compaction）操作（即对较早消息进行摘要或截断）。仅存在于对话中的内容——包括在聊天窗口中输入的指令——可能因此丢失。

安全网：自动记忆刷新

在触发压缩前，OpenClaw 会启动一次静默的 Agent 轮次（silent agentic turn），提醒模型将持久化笔记写入磁盘。

默认配置：

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

关键要点

• 软阈值（Soft threshold）：刷新触发于 contextWindow - reserveTokensFloor - softThresholdTokens 处。
• 每个压缩周期仅执行一次刷新（状态记录于 sessions.json）。
• 静默执行：Agent 回复 NO_REPLY，用户不可见。
• 需具备可写工作区权限：若 workspaceAccess: "ro" 或 "none"，则跳过刷新。
• 验证是否生效：检查配置中 memoryFlush.enabled = true 且缓冲余量充足。

持久化生存守则

1. 将持久化规则写入文件，而非聊天窗口。 MEMORY.md 和 AGENTS.md 可在压缩中幸存。
2. 确认 memory flush 已启用，且缓冲设置足够触发。
3. 通过 AGENTS.md 规则强制执行记忆检索。

4. 向量记忆搜索配置

嵌入（Embedding）服务提供商（自动选择顺序）

1. local — 若已配置 memorySearch.local.modelPath 且对应文件存在
2. openai — 若 OpenAI API 密钥可用
3. gemini — 若 Gemini API 密钥可用
4. voyage — 若 Voyage API 密钥可用
5. mistral — 若 Mistral API 密钥可用
6. 若以上均未配置，则禁用嵌入功能

另支持：ollama（本地/自托管，但不参与自动选择）。

重要提示：Codex OAuth 仅覆盖聊天/补全（chat/completions）能力，不适用于嵌入（embeddings）。你需要为嵌入服务提供商单独配置 API 密钥。

混合搜索配置

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small",
        "query": {
          "hybrid": true
        }
      }
    }
  }
}

索引细节

• 分块策略：目标约 400 Token，重叠 80 Token。
• 存储方式：按 Agent 分离的 SQLite 数据库，路径为 ~/.openclaw/memory/.sqlite。
• 文件监听：防抖 1.5 秒，文件变更时自动重建索引。
• 当嵌入服务提供商、模型或分块参数变更时，自动触发重索引。

5. 高级功能：后处理流水线（Post-Processing Pipeline）

向量 + 关键词 → 加权合并 → 时间衰减 → 排序 → MMR 重排 → Top-K 结果

时间衰减（Recency Boost）

仅靠原始相似度，旧笔记可能排名高于新笔记。启用时间衰减可解决此问题：

• 依据文档年龄应用指数级衰减系数。
• 今日笔记（得分 0.82 × 1.00 = 0.82）将远超 148 天前的笔记（得分 0.91 × 0.03 = 0.03）。
• 建议启用场景：积累了数月每日日志，且陈旧信息常因高相似度压倒当前上下文。

MMR 重排序（多样性保障）

高度相似的每日日志可能挤占多样化结果。MMR 用于消除冗余：

• 对与已选结果过于相似的新结果施加惩罚。
• 建议启用场景： memory_search 返回大量重复或近似重复的片段。

6. QMD 后端（实验性）

面向追求更高搜索质量的高级用户：

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "includeDefaultMemory": true,
      "update": { "interval": "5m", "debounceMs": 15000 },
      "limits": { "maxResults": 6, "timeoutMs": 4000 },
      "paths": [
        { "name": "docs", "path": "~/notes", "pattern": "**/*.md" }
      ]
    }
  }
}

• QMD 通过 Bun + node-llama-cpp 在本地融合 BM25、向量与重排序能力。
• 需单独安装：bun install -g https://github.com/tobi/qmd。
• 若 QMD 故障或缺失，则自动回退至内置 SQLite。
• 首次搜索可能较慢（首次运行将下载 GGUF 模型）。
• 支持会话级索引：memory.qmd.sessions.enabled = true。

7. 额外记忆路径

索引默认工作区以外的文件：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "extraPaths": ["../team-docs", "/srv/shared-notes/overview.md"]
      }
    }
  }
}

• 目录将递归扫描所有 .md 文件。
• 忽略符号链接（symlinks）。
• 借助 Gemini Embedding 2，可支持多模态索引（图像/音频）。

8. 故障排查

诊断起点：始终从此处开始

在 OpenClaw 会话中运行 /context list 检查以下事项：

• MEMORY.md 是否成功加载？若显示 “missing” → 未进入上下文 → 完全无效。
• 是否存在TRUNCATED（被截断）？超过 20,000 字符的文件会被裁剪。
• 注入字符数是否等于原始字符数？若不一致 → 内容已被修剪。

常见问题

健康检查清单

1. MEMORY.md 存在，且大小 < 10,000 字符（理想）或 < 20,000 字符（上限）
2. memory/ 目录存在，且包含近期的每日日志
3. 压缩配置中 memoryFlush.enabled = true
4. 已配置嵌入服务提供商，且 API 密钥有效
5. AGENTS.md 包含“执行前先搜索记忆”规则
6. 运行 wc -c ~/.openclaw/workspace/*.md 审计各文件大小

9. 记忆插件（外部）

适用于需要超越内置系统能力的用户：

Mem0 (@mem0/openclaw-mem0)

• 将记忆存储于上下文窗口之外 → 可抵御压缩影响。
• 自动捕获（Auto-Capture）：从对话中自动提取事实。
• 自动召回（Auto-Recall）：每次响应前自动注入相关记忆。
• 区分长期记忆（用户级）与短期记忆（会话级）。
• 支持云端或自托管（Ollama + Qdrant + 任意 LLM）。

Cognee（知识图谱）

• 为记忆引入关系推理能力（例如：“Alice 管理鉴权团队” → 支持图遍历查询）。
• 启动时扫描全部记忆文件，每次会话结束后同步更新。
• 适用场景：跨项目上下文、“关于 X 我该联系谁？” 类查询。
• 需 Docker 运行 Cognee 服务端。

Supermemory (openclaw-supermemory)

• 基于云的持久化记忆服务，支持用户档案管理。
• 支持自定义容器路由（工作 vs 个人）。
• 无需本地基础设施。

10. 记忆维护例行任务

每周

• 审阅 MEMORY.md — 删除过时事实，将重要日志条目提升至此。
• 检查每日日志是否异常膨胀。

每月（记忆蒸馏 / Memory Distillation）

• 扫描 memory/*.md，识别反复出现的模式与经实践验证的关键规则。
• 将成熟规则提升至 MEMORY.md 或技能文件 SKILL.md。
• 如需，可归档 30 天以上的旧日志。

备份

cd ~/.openclaw/workspace
git init  # 若尚未初始化
git add memory/ MEMORY.md
git commit -m "Memory backup $(date +%Y-%m-%d)"

排除项：~/.openclaw/credentials/ 和 openclaw.json（含敏感凭据）。

速查表：文件加载优先级