OpenClaw 记忆系统 — 设置、优化与故障排除

核心原理

OpenClaw 记忆是存储在磁盘上的纯 Markdown 文件。这些文件是唯一的事实来源。 模型只"记住"写入磁盘的内容——在不同会话之间，没有任何内容会保留在 RAM 中。 记忆搜索工具由激活的记忆插件提供（默认插件：memory-core）。

1. 记忆架构（两层）

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

• 仅追加式会话笔记、运行上下文、当日事件。
• OpenClaw 在会话开始时读取今天 + 昨天的日志。
• 如果有人要求"记住这个" → 请立即写在这里。
• 这些日志会随时间累积；旧的日志可通过memory_search进行搜索。

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

• 精选持久性事实：决策、偏好、铁律规则、项目上下文。
• 仅在会话开始时加载于私有/主会话中（绝不在群组上下文中）。
• 如果同时存在MEMORY.md和memory.md，则仅加载MEMORY.md。
• 保持简短——任何非每次会话都需要的内容都应归入每日日志。
• 超过约20,000字符的文件会被截断（bootstrapMaxChars）。
• 所有工作空间文件的组合引导上限：约150,000字符。

工作空间布局

~/.openclaw/workspace/
├── MEMORY.md              # Long-term curated memory (main session only)
├── memory/
│   ├── 2026-03-17.md      # Today's daily log
│   ├── 2026-03-16.md      # Yesterday's log (also auto-loaded)
│   └── ...                # Older logs (searchable, not auto-loaded)
├── AGENTS.md              # Operating manual, boot sequence
├── SOUL.md                # Persona, tone, values
├── USER.md                # Human profile
└── TOOLS.md               # Environment-specific config

内容存放位置

2. 记忆工具

OpenClaw 向代理暴露两个工具：

memory_search——语义回忆

• 在所有已索引的记忆文件（MEMORY.md + 每日日志）中搜索。
• 返回片段文本（最多约700字符）、文件路径、行号范围、匹配度分数。
• 使用混合搜索：向量相似度 + BM25 关键词匹配。
• 向量搜索能发现语义转述（例如"部署过程"匹配"我们如何发布代码"）。
• BM25 能发现精确词元（ID、环境变量、错误字符串、代码符号）。
• 结果通过加权融合进行排序：最终分数 = 向量权重 × 向量得分 + 文本权重 × 文本得分。

memory_get— 定向文件读取

• 通过路径和可选的行范围读取特定的记忆文件。
• 如果文件不存在，会优雅降级处理（返回空文本，不报错）。
• 在确切知道哪个文件包含所需信息时使用。

最佳实践：强制要求检索

将此规则添加到AGENTS.md：

## Memory Protocol
- ALWAYS run memory_search before acting on tasks that reference past context.
- Do NOT guess from conversation history alone — check your notes.

没有此规则，代理会猜测而不是检查其记忆文件。

3. 压缩与记忆刷新

问题

长对话会填满上下文窗口。当达到阈值时，OpenClaw会压缩（总结/截断）较早的消息。任何仅存在于对话中的内容——包括在聊天中输入的操作指令——都可能消失。

安全网：自动内存刷新

在触发压缩之前，OpenClaw会启动一个静默的代理回合，提醒模型将持久性笔记写入磁盘。

默认配置：

{
  "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."
        }
      }
    }
  }
}

关键要点

• 软阈值：刷新触发于上下文窗口 - 保留令牌下限 - 软阈值令牌。
• 每个压缩周期仅刷新一次（记录于sessions.json）。
• 静默：代理以NO_REPLY回应，因此用户不会看到它。
• 需要可写的工作空间: 如果workspaceAccess: "ro"或"none"则跳过
• 。验证其是否正常工作：检查配置并确保memoryFlush.enabled = true

且有足够的缓冲区。

1. 生存规则将持久性规则放在文件中，而非聊天记录中。
2. MEMORY.md 和 AGENTS.md 在压缩后仍会保留。验证内存刷新已启用
3. 并且有足够的缓冲区来触发。通过 AGENTS.md 规则

使检索成为强制要求。

4. 向量记忆搜索配置

1. 嵌入提供者（自动选择顺序）本地— 如果memorySearch.local.modelPath
2. 已配置 + 文件存在— 如果 OpenAI API 密钥可用
3. gemini— 如果 Gemini API 密钥可用
4. voyage— 如果 Voyage API 密钥可用
5. mistral— 如果 Mistral API 密钥可用
6. 如果未配置任何密钥，则禁用

同样支持：ollama（本地/自托管，非自动选择）。

重要提示：Codex OAuth 仅覆盖聊天/补全功能 — 它不适用于嵌入。您需要为您的嵌入提供商准备一个单独的 API 密钥。

混合搜索配置

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

索引详情

• 分块：目标约 400 个词元，重叠 80 个词元。
• 存储：每个代理的 SQLite 数据库位于~/.openclaw/memory/<agentId>.sqlite。
• 文件监视器：防抖 1.5 秒，变更时重新索引。
• 当提供商/模型/分块参数变化时自动重新索引。

5. 高级：后处理流程

Vector + Keyword → Weighted Merge → Temporal Decay → Sort → MMR → Top-K Results

时间衰减（近期性提升）

仅凭原始相似度，旧笔记可能会排在近期笔记前面。启用衰减功能可以解决此问题：

• 根据笔记存在时间应用指数型乘数因子。
• 今天的笔记（得分 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文件。
• 符号链接会被忽略。
• 使用 Gemini Embedding 2 可实现多模态索引（图像/音频）。

8. 故障排除

诊断：始终从此处开始

在您的 OpenClaw 会话中运行/context list命令进行检查：

• 是否MEMORY.md正在加载？如果显示“缺失” → 不在上下文中 → 零效果。
• 是否有任何被截断文件超过20000字符会被截断。
• 注入字符是否与原始字符匹配？若不匹配 → 内容正在被修剪。

常见问题

健康检查清单

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存储记忆

• 在上下文窗口之外 → 在压缩后依然保留。自动捕获：自动从对话中提取事实。自动召回：在每次回应前注入相关记忆。
• 区分长期（用户范围）和短期（会话范围）记忆。
• 支持云端或自托管（Ollama + Qdrant + 任何LLM）。
• Cognee（知识图谱）
• 为记忆添加

关系推理

• 功能（例如，"Alice管理认证团队" → 图谱遍历）。启动时扫描记忆文件，每次会话后同步。适用于：跨项目上下文、"我应该找谁咨询X问题？"等查询。
• 需要Docker来运行Cognee服务器。
• Supermemory (
• openclaw-supermemory

)基于云的持久化记忆，带有用户档案。自定义容器路由（工作与个人）。

• Cloud-based persistent memory with user profiles.
• Custom container routing (work vs personal).
• 无需本地基础设施。

10. 记忆维护流程

每周

• 审查MEMORY.md 文件——移除过时的事实，提升重要的每日日志条目。
• 检查每日日志是否增长得过于庞大。

每月（记忆提炼）

• 扫描memory/*.md 文件以发现重复模式和来之不易的规则。
• 将成熟的规则提升至MEMORY.md 文件或相应的技能 SKILL.md 文件。
• 如有需要，归档旧的每日日志（超过30天）。

备份

cd ~/.openclaw/workspace
git init  # if not already
git add memory/ MEMORY.md
git commit -m "Memory backup $(date +%Y-%m-%d)"

排除： ~/.openclaw/credentials/ 目录和openclaw.json 文件（包含机密信息）。

快速参考：文件优先级