当前位置：首页 > 知识wiki > 正文内容

OpenClaw 记忆系统详解：长期记忆、短期记忆与记忆检索

OpenClaw 记忆系统架构

大多数AI助手的记忆要么"什么都记不住"，要么"什么都往里塞"导致上下文膨胀失控。OpenClaw 设计了一套三层递进式记忆架构，让AI Agent 在"记住什么"和"忘记什么"之间找到平衡。本文详解各层职责、读写时机、截断规则与最佳实践。

🧠 三层记忆架构总览

OpenClaw 的 Agent 通过写入纯 Markdown 文件来"记住"信息。模型只记得写入磁盘的内容——没有隐藏的运行时状态。整个记忆体系分三层：

△ OpenClaw 三层记忆架构：长期记忆→每日笔记→运行时上下文

层级	文件路径	加载时机	持久化
L1 · 长期记忆	`MEMORY.md`	每次 DM 会话启动	永久保留
L2 · 每日笔记	`memory/YYYY-MM-DD.md`	当天与昨天的笔记自动加载	持久化索引
L3 · 运行时上下文	对话历史 + Compaction	每次对话轮次	Compaction 后摘录归档

📄 第一层：MEMORY.md — 长期记忆

职责

存放持久的、经过提炼的事实性信息：用户偏好、关键决策、重要配置、长期目标。它是 Agent 的"大脑皮质"——只保留高信号、可复用的知识。

读写时机

读取：每次 Agent 主会话（DM）启动时加载到 Prompt 上下文中
写入：Agent 在对话中识别到持久化价值的信息时自动写入；用户也可直接说"记住我偏好 TypeScript"
提炼：应定期从每日笔记中将有用信息"蒸馏"到 MEMORY.md，同时移除过时的条目

截断规则

⚠️ 重要：如果 MEMORY.md 超出 Bootstrap 文件预算，OpenClaw 会截断注入模型上下文的内容（磁盘上的文件不受影响）。

此时应当：将详细信息移回 memory/*.md，仅在 MEMORY.md 保留概要，或提高 Bootstrap 限制。使用 /context list、/context detail 或 openclaw doctor 查看原始 vs 注入大小和截断状态。

行动敏感型记忆

某些记忆不仅记录事实，还影响 Agent 未来的行为。这类记忆需要标注行动边界：

审批或权限要求
临时约束（何时生效、何时过期）
交接给其他会话/线程/人
安全操作的时间窗口
来源和授权者

示例：

API 迁移正在另一个会话中设计。此线程未来轮次不应编辑 API 实现代码；仅将此处发现作为设计输入，直到迁移计划落地。

📓 第二层：memory/ 目录 — 每日笔记

文件结构

位于 Agent 工作空间下的 memory/ 目录：

~/.openclaw/workspace/
├── MEMORY.md
├── memory/
│   ├── 2026-06-28.md
│   ├── 2026-06-29.md
│   ├── 2026-06-29-review.md        # 带 slug 的变体
│   └── 2026-06-30.md
└── DREAMS.md                        # Dream 日记（可选）

职责

详细的日常观察和会话摘要
原始上下文和中间发现
尚不确定是否需要长期保留的信息
带 slug 的文件（如 2026-06-29-review.md）同样被索引

读写时机

读取：当天（Today）和昨天（Yesterday）的笔记自动注入 Prompt；更早的笔记通过 memory_search 检索
写入：Compaction 前自动触发 Memory Flush 轮次，Agent 在此时保存重要上下文
自动归档：Agent 被提示定期将内存中有价值的信息蒸馏到 MEMORY.md

Memory Flush（自动记忆保存）

在 Compaction 对对话进行摘要之前，OpenClaw 会执行一个静默轮次，提醒 Agent 将重要上下文保存到记忆文件中。此功能默认开启，无需额外配置。

配置本地模型的 Memory Flush 模型：

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

🔎 第三层：memory_search — 语义检索机制

工作原理

当 Agent 需要回忆不在 Prompt 上下文中的信息时，调用 memory_search 工具。它使用混合搜索——同时运行两条检索路径并合并结果：

Query
 ├── Embedding → Vector Search（语义相似度）
 └── Tokenize → BM25 Search（关键词精确匹配）
       ↓
   Weighted Merge → Top Results

向量搜索：找到含义相似的内容（"gateway host" 匹配 "运行 OpenClaw 的机器"）
BM25 关键词：找到精确匹配（ID、错误字符串、配置键）

支持的 Embedding Provider

Provider	配置 ID	需要 API Key
OpenAI（默认）	`openai`	是
Gemini	`gemini`	是
本地模型	`local`	否
Ollama	`ollama`	否
Voyage	`voyage`	是
Mistral	`mistral`	是
更多	DeepInfra / Bedrock / GitHub Copilot / OpenAI 兼容	视 provider 而定

检索质量调优

⏳ 时间衰减（Temporal Decay）

旧笔记的排名权重逐渐降低。默认半衰期30天：一个月前的笔记得分降至原50%。MEMORY.md 永不过期。

🎯 MMR 多样化

减少重复结果。五个笔记都提到同一个配置时，MMR 确保前几条覆盖不同主题。

同时启用时间衰减和 MMR：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "query": {
          "hybrid": {
            "mmr": { "enabled": true },
            "temporalDecay": { "enabled": true }
          }
        }
      }
    }
  }
}

CLI 命令

openclaw memory status           # 查看索引状态和 provider
openclaw memory search "query"   # 命令行搜索
openclaw memory index --force    # 重建索引

✂️ AGENTS.md 截断规则

AGENTS.md 文件中每行默认最大长度为 240 个字符。超出部分会被截断。这一规则对中文的影响尤为显著——中文字符按 UTF-8 字节计算，240 字节约等于 80 个中文字，因此长行中文内容更容易被截断。

建议：

AGENTS.md 中的中文描述尽量精简，每行控制在 80 字以内
多行信息断开写入，不要挤在一行
MEMORY.md 不适用此截断规则（但有独立的 Bootstrap 文件预算截断）

🌟 Dreaming：后台记忆巩固

Dreaming 是可选的后台记忆巩固机制，用于自动化地将短期记忆中的高价值信息晋升到长期记忆：

默认关闭，需主动启用
启用后自动管理一个 Cron 定期执行全量 Dream 扫描
晋升必须通过评分、召回频率和查询多样性门槛
阶段总结和 Diary 条目写入 DREAMS.md 供人工审核

Grounded Backfill（历史回填）：

使用 openclaw memory rem-backfill --path ./memory --stage-short-term 可以将历史笔记重新输入 Dreaming 管线，让系统评估旧笔记的持久化价值，而不直接写入 MEMORY.md。

🔄 与 MCP / Skill 联动场景

MCP 工具中的记忆使用

MCP 工具（如 wecom-msg、wecom-contact）本身不直接操作记忆文件，但 Agent 可通过以下方式实现记忆持久化：

MCP 调用 → 信息提取 → 写入 MEMORY.md：如从通讯录查询到某个联系人的信息后，Agent 可以记忆该信息供后续复用
MCP 调用 → 日志记录 → memory/*.md：MCP 工具的操作结果写入每日笔记，形成审计轨迹

Skill 中的记忆推荐

技能（Skill）在 SKILL.md 中定义时，应明确说明何时以及如何操作记忆：

SKILL.md 中的记忆声明示例：

## Memory Usage
- 查询到的用户信息应写入 MEMORY.md（偏好、联系方式）
- 每次操作日志写入当天的 memory/.md
- 不走 memory_search 检索，直接调用 memory_get 读取已验证数据

💡 最佳实践：日志 → 提炼 → 归档

推荐的记忆管理流程是一个三层漏斗：

阶段	操作	目标
1️⃣ 日志	日常对话 → memory/YYYY-MM-DD.md	保留原始上下文
2️⃣ 提炼	每日笔记 → 抽取高价值信息 → MEMORY.md	去芜存菁，保持长期记忆紧凑
3️⃣ 归档	过时条目从 MEMORY.md 移回 memory/*.md	控制 Prompt 预算，防止截断

✅ 核心原则：

相信 Agent——告诉它"记住这个"，它会自动写入对应文件
不要手动管理每条记忆——Heardbeat 流程和 Compaction 会处理日常提炼
关注截断信号——用 /context list 监控 MEMORY.md 注入大小
利用 Dreaming——启用后台巩固后，系统自动评估信息持久化价值
行动边界清晰——涉及审批、时效、交接的记忆标注"何时做什么"

🔧 记忆后端选择

OpenClaw 支持多种记忆后端引擎，可根据部署场景选择：

🗄️ Builtin（默认）

SQLite 基础，零配置开箱即用。支持关键词搜索、向量相似度和混合搜索。

⚡ QMD

本地优先，支持 Reranking、Query Expansion，可索引工作空间外目录。

🧠 Honcho

AI 原生跨会话记忆，用户建模、语义搜索、多 Agent 感知，需插件安装。

📚 Memory Wiki

编译持久记忆为可溯源的知识库，带声明结构、矛盾检测和仪表盘。

📝 总结

OpenClaw 的记忆系统设计哲学是"清晰分层、自动流转"：MEMORY.md 保存精炼的长期知识，memory/*.md 承载日常上下文，memory_search 提供跨越时间维度的召回能力。开发者的工作不是"记录所有细节"，而是建立正确的提炼节奏——利用 Compaction 前的 Memory Flush 自动保存关键内容，通过 Dreaming 后台巩固提升信息持久化效率，用 Active Memory 插件在交互式会话中预取相关记忆。

记住：最好的记忆系统不是记得最多的那个，而是知道该记住什么、该忘记什么的那个。

📖 延伸阅读

Memory 官方文档 · Memory Search · Active Memory · Dreaming

OpenClaw 知识百科 · 记忆系统详解 · 知识wiki