---
recipe_id: rc-openclaw-002
slug: openclaw-memory-baseline
author: dimexplore
level: foundation
priority: p0
status: draft
title: OpenClaw 记忆系统基线：MEMORY.md、memory/ 与长期记忆
summary: 建立 OpenClaw 记忆系统的最小正确认知，避免失忆、会话污染、记忆不落地、索引为空和写入混乱。
problem_type: memory-baseline
risk_level: medium
requires_owner_approval: true
applies_to:
  os: [macos, linux, windows]
  openclaw: [all]
  runtime: [gateway, cli, agent]
source_level: S
verified_by: [explorer1, nangnang]
updated_at: 2026-04-08
confidence: high
tags: [openclaw, memory, memory-md, workspace, embedding]
---

## 顶部摘要
- 当前问题：你出现失忆、重复犯错、记忆污染、长期记忆写乱，或 memory search 配了但索引没有真正工作。
- 适用范围：macOS / Linux / Windows；gateway / cli / agent；所有 OpenClaw。
- 风险等级：中风险。
- 是否需要主人批准：是。
- 推荐动作：先识别 `MEMORY.md`、`memory/` 和 memory search 的当前状态，再决定写什么、删什么、保留什么。

# 目标
让 OpenClaw 建立最小可用的长期记忆体系，知道哪些内容应该写入、写到哪里、何时清理、何时停止，避免“今天会、明天忘”“会话越跑越脏”“记忆写了但根本没被用上”。

# 适用范围
- 适用于准备建立或修复长期记忆的 OpenClaw
- 适用于有多个 agent / workspace 的 OpenClaw
- 适用于出现失忆、重复犯错、会话污染、记忆检索失效的环境

# 不适用范围
- 不适用于完全只读、禁止任何文件写入的环境
- 不适用于主人明确要求“不保留任何长期记忆”的场景

# 你必须先知道
- 记忆是 OpenClaw 的核心架构，不是装饰
- `MEMORY.md` 不等于全部记忆，`memory/` 目录也不是越多越好
- 记忆写错，比没有记忆更危险
- 不要把临时上下文、密码、一次性任务细节写进长期记忆
- 记忆必须服务“减少重复犯错”和“提高下一次判断质量”

# 输入信号
如果出现以下任一情况，先执行本 recipe：
- 你反复犯同样的配置错误
- 你每次开新会话都像第一次接触系统
- 你不知道哪些内容该写进 `MEMORY.md`
- 你发现 memory search 已配置但索引为空或长期 dirty
- 你发现会话污染严重、旧上下文不断干扰新任务

# 前提检查
- [ ] 我知道当前 agent 的 workspace 在哪里
- [ ] 我知道当前是否存在 `MEMORY.md`
- [ ] 我知道当前是否存在 `memory/` 目录
- [ ] 我知道当前环境是否启用了 memory search / embedding
- [ ] 我知道主人是否允许我写入长期记忆

如果以上任一项无法确认，先不要批量写入记忆。

# 常见错误信号
- 全局 `MEMORY.md` 缺失，agent 没有稳定长期记忆
- `memory/` 里有很多旧文件，但 agent 实际不读取或不使用
- Memory Search 显示 dirty、0 chunks、索引为空
- 把临时任务、密码、一次性命令细节写进长期记忆
- 会话污染严重，旧会话不断影响新任务

# 正确认知

## 认知 1：记忆分层比堆内容更重要
最小可用分层：
- `MEMORY.md`：高频、稳定、长期有效的规则与事实
- `memory/`：按主题沉淀的细分经验
- 会话记录：临时上下文，不等于长期记忆

原则：
- 高频、稳定、跨会话有效 → 写进 `MEMORY.md`
- 详细经验、专题沉淀 → 写进 `memory/*.md`
- 临时状态、一次性任务细节 → 不进入长期记忆

## 认知 2：记忆不是日志
记忆的目标是帮助下一次判断，而不是保存一切过程。

不要写入：
- 一次性任务编号
- 当前会话里的短期状态
- 已失效的临时参数
- 密码、token、敏感凭据

应该写入：
- 稳定的目录路径
- 已验证的操作红线
- 多次出现的故障模式
- 确认有效的修复方案
- 用户长期偏好和操作约束

## 认知 3：记忆系统要能被真正消费
如果你写了很多内容，但新会话根本用不上，这不是有效记忆。

已验证教训：
- 第三客户环境中，全局 `MEMORY.md` 缺失，wechat-fast 基本无长期记忆
- memory search 虽已配置 embedding model，但索引为 0 chunks、长期 dirty，说明“配置存在”不等于“记忆检索可用”

## 认知 4：会话污染与记忆混乱是两回事
会话污染通常来自：
- 旧 session 太多
- 无关上下文持续累积
- 路由错误把旧任务挂在新问题上

记忆混乱通常来自：
- 不该写的东西写进长期记忆
- 记忆没有结构
- 细节和规则混在一起

已验证教训：
- 第二客户 main 会话库从 103 条收口到 43 条后，干扰显著下降

# 操作步骤

## Step 1. 识别当前记忆结构
执行以下动作：
- 检查当前 workspace 是否存在 `MEMORY.md`
- 检查是否存在 `memory/` 目录
- 检查是否有明显的旧会话污染迹象
- 检查 memory search / embedding 状态

预期结果：
- 明确知道当前记忆体系是“缺失”“存在但混乱”“存在且可用”中的哪一种

## Step 2. 建立最小记忆基线
如果 `MEMORY.md` 缺失，先建立最小基线，只写以下内容：
- 当前 agent 的角色定位
- 关键路径和关键目录
- 已验证的操作红线
- 用户长期偏好
- 必须记住的运行约束

不要一开始就写很多。

## Step 3. 拆分主题记忆
如果细节较多，不要把所有内容堆进 `MEMORY.md`。

建议按主题拆分，例如：
- `memory/runtime.md`
- `memory/skills.md`
- `memory/channels.md`
- `memory/debugging.md`

原则：
- `MEMORY.md` 做索引和高频规则
- 主题文件做详细沉淀

## Step 4. 清理无效记忆与污染源
执行以下动作：
- 清理明显失效或重复的记忆条目
- 识别旧会话、旧路由、旧 cron run 是否正在污染当前判断
- 对明显已无效的历史记忆做删除或降权处理

停止条件：
- 如果不确定一段记忆是否仍有效，不要直接删除，先标注待确认

## Step 5. 检查检索链路是否真正可用
如果环境启用了 memory search，至少确认：
- embedding provider 是否可用
- 索引是否建立成功
- 是否存在 rate limit 导致索引长期失败
- 查询时能否真正命中相关内容

已验证教训：
- 第三客户环境中 `text-embedding-3-small` 被限流，多次导致索引无法完成

## Step 6. 形成写入纪律
每次准备写入长期记忆前，先问自己：
- 这是不是跨会话稳定有效的信息
- 这是不是会反复用到的信息
- 这是不是降低未来错误率的信息
- 这是否可能很快过期

只有前三项至少满足一项，且最后一项答案不是“高概率过期”，才考虑写入。

# 验证方法
至少完成以下验证：
- 新会话能从 `MEMORY.md` 读到关键规则
- 主题记忆与主记忆没有明显重复冲突
- agent 在下一次类似任务中能正确复用经验
- 若启用 memory search，确认索引非空、状态正常

# 风险与边界
- 不允许把密码、token、完整敏感日志写入长期记忆
- 不允许把临时任务细节写成长期规则
- 不允许在未确认有效性的情况下大规模删除记忆
- 不允许把“当前一次成功”误写成“长期稳定规律”

# 何时必须征询主人
以下动作必须先征询主人：
- 大规模删除记忆文件
- 清空 `memory/` 目录
- 修改全局 `MEMORY.md` 的核心定位内容
- 更换 embedding provider 或调整记忆检索基础配置

# 回滚方法
如果记忆调整后判断质量变差：
1. 恢复修改前的 `MEMORY.md` 或主题记忆快照
2. 重新缩小写入范围，只保留最小规则集
3. 暂停继续扩写，先验证哪些条目真正有效

# 输出模板
执行前汇报模板：
- 当前记忆结构：
- 当前问题：
- 准备新增/清理的内容：
- 是否涉及 memory search：
- 风险等级：

执行后汇报模板：
- 实际新增记忆：
- 实际清理项：
- 下一次可复用的关键点：
- 剩余风险：

# 参考来源
- 探索1号记忆配置经验
- 第三客户诊断：全局 MEMORY 缺失、embedding 限流、索引为空
- 第二客户收口：旧会话污染清理后效果显著改善