Memory 记忆系统

Memory 是什么

OpenClaw 的记忆系统通过普通 Markdown 文件实现持久化。Agent 只记得被保存到磁盘的内容，不存在隐藏状态。它让 Agent 从「每次重启都失忆」变成「越用越懂你」。

记忆分层

OpenClaw 的记忆有两层结构：

第一层：MEMORY.md（精选长期记忆）

~/.openclaw/workspace/MEMORY.md

• 职责：持久的、精选的事实、偏好、决策和简短摘要
• 加载方式：主会话启动时自动注入到模型上下文
• 规则：不是原始对话记录、不是每日日志、不是详尽归档

第二层：memory/YYYY-MM-DD.md（每日详细记录）

~/.openclaw/workspace/memory/
├── 2026-07-24.md
├── 2026-07-25.md
└── 2026-07-26.md

• 职责：运行上下文、观察记录、会话摘要
• 加载方式：今天 + 昨天的日志自动加载；更早的日志通过 memory_search 按需检索
• 规则：详细记录写这里，精华提炼到 MEMORY.md

graph TD
    A[会话开始] --> B[自动注入 MEMORY.md]
    A --> C[自动注入 today + yesterday 日志]
    A --> D[Agent 可调用 memory_search]
    D --> E[语义搜索历史日志]
    D --> F[关键词搜索历史日志]
    B & C & E & F --> G[组装完整上下文]

memory_search 召回机制

当有 Embedding Provider 配置时，memory_search 使用混合搜索：

模式	说明
向量相似度	语义匹配，即使措辞和原文不同也能找到
关键词匹配	精确匹配 ID、代码符号等具体词条

# Agent 内部的调用逻辑
# 1. 用户提问
# 2. Agent 调用 memory_search(query="PostgreSQL 数据库配置")
# 3. 返回语义相似的记忆条目
# 4. Agent 参考记忆回答问题

Embedding 配置

OpenClaw 默认使用 OpenAI Embeddings。可切换为 Gemini、Voyage、Mistral、Ollama 本地模型、LM Studio 等。

记忆写什么、不写什么

✅ 应该写入 MEMORY.md 的内容

# 用户信息
- 姓名：张三，后端工程师
- 偏好语言：Go > TypeScript > Python
- 时区：Asia/Shanghai，工作日 9:00-18:00

# 环境信息
- 生产 k3s 集群：192.168.1.10-12
- 数据库：PostgreSQL 16，端口 5432
- 部署方式：k3s + Helm

# 关键决策
- 2026-07-15：API 网关从 Kong 迁移到 Envoy
- 2026-06-01：日志方案用 Grafana Loki，放弃 ELK

❌ 不应该写入的内容

• 📛 API 密钥、密码、Token —— 放环境变量或 ~/.openclaw/.env
• 📛 完整对话记录 —— 放 session transcript
• 📛 一次性临时信息 —— 会话结束后就作废
• 📛 过于细节的操作步骤 —— 应该放 Skills

Session Transcript（会话历史）

会话转录（Session Transcript）是 memory/ 之外的第三个信息层：

层级	存储位置	用途
上下文	会话内存	当前对话的「思维」，最即时
记忆文件	MEMORY.md + memory/	持久化的知识，跨会话复用
会话转录	~/.openclaw/agents/*/agent/*.sqlite	完整交互历史，可搜索回顾

自动 Memory Flush

OpenClaw 在 compaction（对话压缩）前会自动执行一次 Memory Flush：用一次静默的模型调用提醒 Agent 把对话中的关键信息写入 memory 文件。

// 关闭自动 flush（不推荐）
{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: { enabled: false },
      },
    },
  },
}

// 用本地模型执行 flush，省钱
{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: { model: "ollama/qwen3:8b" },
      },
    },
  },
}

实战：设计一个高效的 MEMORY.md 模板

# 持久化记忆

## 用户身份
- 姓名/称呼：
- 角色/职业：
- 技术栈偏好：

## 重要偏好
- 代码风格：
- 工具偏好：
- 沟通方式：

## 项目/环境
- 项目名：简要说明
- 关键路径/配置：
- 运维要点：

## 知识索引（指向 memory/ 中的详细记录）
- 主题 1 → 参见 memory/2026-07-xx.md
- 主题 2 → 参见 memory/2026-07-xx.md

## 当前进行中
- [ ] 任务 1
- [ ] 任务 2

经验：避免记忆膨胀

维护策略

1. 按时间归档：每日记录放 memory/YYYY-MM-DD.md，不要让 MEMORY.md 变成流水账
2. 定期提炼：每周从 memory/ 中提取精华，合并到 MEMORY.md
3. 删旧去重：新信息出现后，检查旧记录是否有冲突，及时更新或删除
4. 关注预算：MEMORY.md 超过 bootstrap 文件预算（默认 20000 字符）会被截断

判断标准

如果在 MEMORY.md 中找不到某条信息，Agent 仍可通过 memory_search 从历史日志中检索到——所以不必把一切都塞进 MEMORY.md。它应该是索引 + 精华，而非全量备份。

记忆膨胀信号

• MEMORY.md 超过 300 行 → 该整理了
• 同一条信息出现了 3 次不同版本 → 该合并了
• 3 个月前的临时任务还在列表中 → 该清理了
• Agent 的回复中引用了过期信息 → 该更新了

Memory 后端

OpenClaw 支持多种 memory 后端：

后端	特点
Builtin（默认）	SQLite 存储，关键词+向量混合搜索，零依赖
QMD	本地优先，支持重排序和查询扩展
Honcho	AI 原生，跨会话用户建模，多 Agent 感知
LanceDB	本地向量数据库，支持 Ollama embedding

Dreaming（梦境系统）

Dreaming 是可选的后台记忆整合功能，自动将短期记忆提炼为长期记忆：

• 启用方式：默认关闭，需手动开启
• 自动调度：启用后 memory-core 自动管理一个定时任务执行完整 dreaming 扫描
• 阈值控制：候选记忆必须通过评分、召回频率、查询多样性三道门槛才能提升
• 可审查：阶段摘要和日记条目写入 DREAMS.md 供人类审查

# 基于历史日志文件回填（grounded backfill）
openclaw memory rem-backfill --path ./memory --stage-short-term

Grounded backfill 读取历史 memory/YYYY-MM-DD.md 笔记，将结构化审查结果写入 DREAMS.md，但不会直接写入 MEMORY.md——所有修改仍通过 dreaming 的深度提升阶段完成。

知识 Wiki 层（可选）

如果你希望记忆系统更像维护型知识库而非原始笔记，可以启用 memory-wiki 插件：

• 将持久化知识编译为结构化 wiki 仓库
• 支持结构化声明与证据、矛盾检测、新鲜度追踪
• 生成仪表盘和编译摘要
• 提供专用工具：wiki_status、wiki_search、wiki_get、wiki_apply、wiki_lint

memory-wiki 不替代活跃 memory 插件；memory 插件仍负责召回、提升和 dreaming。

Action-Sensitive 记忆

部分记忆不仅记录事实，还影响 Agent 未来的行为决策。对于这类记忆，应明确标注触发条件和边界：

API 迁移正在另一个 session 中进行设计。未来对话不应从本线程编辑 API 实现；
此处发现仅作为设计输入，等待迁移方案落地后再执行。

记录时应包含：

• 什么行为会改变 → 什么条件适用 → 何时过期 → 不可做什么 → 信息来源和权限

下一步

掌握了记忆系统后，继续学习 节点管理 →

加载练习题中...

---

🎯 本章要点

• 记忆存储为普通 Markdown 文件，Agent 只记得被保存到磁盘的内容
• MEMORY.md 放持久事实和关键决策，日常细节写 memory/YYYY-MM-DD.md