OpenClaw 长期记忆文件的处理机制、截断策略、压缩与自动化维护全解析
MEMORY.md 是 OpenClaw Agent 的长期记忆文件，存储持久性事实、用户偏好、重要决策和教训。每次新会话（私聊）启动时，它会被自动加载注入到模型上下文中，让 Agent "记住" 之前的一切。
| 限制项 | 默认值 | 说明 |
|---|---|---|
bootstrapMaxChars | 20,000 字符 | 单个文件注入上下文的最大字符数 |
bootstrapTotalMaxChars | 150,000 字符 | 所有工作区文件注入的总字符上限 |
约 20,000 字符 ≈ 5,000 tokens，意味着 MEMORY.md 默认最多能注入约 5000 tokens 的内容。超过的部分会被截断（而非报错）。
关键点：磁盘上的 MEMORY.md 不会被修改，只是在注入到模型上下文时，超出的部分会被静默截断。Agent 只能看到截断后的内容——后面的记忆对它来说「不存在」。
# MEMORY.md（磁盘上实际内容） 用户喜欢深色主题 ✅ Agent 能看到 偏好的编程语言：Python ✅ Agent 能看到 重要决策：部署必须确认后执行 ✅ Agent 能看到 ... 旧的项目笔记（2025年3月） ✅ Agent 能看到 已过期的偏好设置 ✅ Agent 能看到 历史教训记录 ✅ Agent 能看到 更多详细记录 ✅ Agent 能看到 --- ========== 截断线（bootstrapMaxChars = 20000）========== 以下内容被截断，Agent 看不到 ⛔ 早期调研笔记... 过时的临时决策... 2年前的项目日志...
拖动滑块增大 MEMORY.md 大小，观察截断如何发生。红色区域 = Agent 看不到的内容。
OpenClaw 用三层架构来管理记忆，每一层有不同的生命周期、加载策略和管理方式。理解这个架构是解决 MEMORY.md 膨胀问题的基础。
📍 当前对话的实时上下文（模型的工作记忆）
📍 跟进承诺（Commitments）— 短期跟进事项
📍 模型未保存到磁盘的「隐藏状态」
⚡ 生命周期：当前会话。会话结束后，如果没有保存到文件，就永久丢失。
📍 对话过长时自动触发压缩，生成摘要
📍 压缩前自动运行静默轮次，提醒 Agent 保存重要信息到文件
📍 Memory Flush 默认启用，可用本地模型（如 ollama/qwen3:8b）
⚡ 生命周期：中间缓冲层，防止压缩导致上下文丢失的「安全网」。
📄 MEMORY.md — 长期记忆，每次私聊会话启动时加载
📄 memory/YYYY-MM-DD.md — 每日笔记，自动加载今天 + 昨天
📄 DREAMS.md — 梦境摘要，供人工审阅（可选）
⚡ 生命周期：持久化存储。MEMORY.md 是核心，但也最容易膨胀。
Dreaming（梦境）是 OpenClaw 的可选后台整合流程，专门设计用来保持 MEMORY.md 的高信噪比。它从短期记忆中筛选出真正值得长期保留的内容，防止 MEMORY.md 被低价值信息填满。
候选记忆必须同时通过以下三个门槛才能被提升到 MEMORY.md：
| 门槛 | 含义 | 作用 |
|---|---|---|
| 分数门槛 (Score Threshold) | 记忆的质量评分必须达标 | 过滤低质量噪音 |
| 召回频率 (Recall Frequency) | 被重复访问的次数足够多 | 只保留真正有用的记忆 |
| 查询多样性 (Query Diversity) | 从不同角度/场景被检索过 | 避免只对单一场景有用的记忆占位 |
| 通道 | 数据来源 | 作用 |
|---|---|---|
| 实时梦境 (Live Dreaming) | memory/.dreams/ 短期梦境存储 | 常规深度阶段用它来决定哪些内容晋升 |
| 有依据回填 (Grounded Backfill) | 历史 memory/YYYY-MM-DD.md | 重播旧笔记，重新评估哪些值得持久化 |
回填 CLI：
openclaw memory rem-backfill --path ./memory --stage-short-term openclaw memory rem-backfill --rollback # 回滚（不影响常规日记）
Heartbeat 是 OpenClaw 的定期自动化机制，让 Agent 可以定期主动执行任务——无需用户手动触发。在记忆管理场景中，Heartbeat 可以：
{
"cron": {
"jobs": [
{
"name": "记忆整理心跳",
"schedule": { "kind": "every", "everyMs": 1800000 },
"payload": {
"kind": "systemEvent",
"text": "Read HEARTBEAT.md. Follow it. If nothing needs attention, reply HEARTBEAT_OK."
},
"sessionTarget": "main"
}
]
}
}
HEARTBEAT.md 中定义具体任务清单，Agent 每次心跳读取并执行。无任务时返回 HEARTBEAT_OK，不打扰用户。
cron 定时器到期，向 Agent 发送系统事件
检查任务清单，判断是否有需要处理的事项
从近期日志提炼 → 更新 MEMORY.md → 清理过时条目 → 检查文件大小
有任务则汇报执行结果，无任务则静默返回
OpenClaw 使用混合检索来从记忆文件中召回相关内容：
为什么需要混合？纯向量检索擅长「Mac主机」匹配「运行gateway的机器」，但不擅长匹配 commit hash 或配置项名。纯 BM25 精准但语义理解差。两者互补。
{
"memorySearch": {
"query": {
"hybrid": {
"enabled": true,
"vectorWeight": 0.7,
"textWeight": 0.3,
"candidateMultiplier": 4,
"mmr": { "enabled": true, "lambda": 0.7 }
}
}
}
}
MMR（Maximal Marginal Relevance）开启去重，避免返回多条高度相似的记忆。
让近期记忆权重更高，旧记忆自动淡化。但 MEMORY.md 是永久文件，不受时间衰减影响——这是它的特权。
"temporalDecay": {
"enabled": true,
"halfLifeDays": 30 // 半衰期 30 天
}
衰减公式：decayedScore = score × e^(-λ × ageInDays)，其中 λ = ln(2) / halfLifeDays
| 记忆年龄 | 得分保留比例 | 说明 |
|---|---|---|
| 当天 | 100% | 最新记忆，权重最高 |
| 7 天前 | ~84% | 上周的记忆，影响轻微 |
| 30 天前 | 50% | 恰好到半衰期 |
| 90 天前 | 12.5% | 3个月前的记忆大幅衰减 |
| 180 天前 | ~1.6% | 半年前的记忆几乎不可见 |
~/.openclaw/credentials/将详细材料移回 memory/*.md，只在 MEMORY.md 保留精炼摘要。比如「2025年Q1服务器迁移记录（3000字）」→「2025年Q1完成服务器迁移至AWS，注意：需先备份数据库」
将不同主题拆到独立文件（如 memory/projects.md、memory/deploy-rules.md），避免单文件超限。这些文件通过 memory_search 语义检索访问。
开启梦境系统，让 AI 自动评分、筛选值得保留的记忆，自动清理低价值内容。
设置周期性心跳任务，自动从日志提炼精华到 MEMORY.md、清理过时条目。
如果确实需要更多上下文，可以调大限制。但代价是占用更多对话空间。配置：agents.defaults.bootstrapMaxChars
| 命令 | 作用 | 关注点 |
|---|---|---|
/context list | 查看所有注入文件的大小和状态 | 看是否有 TRUNCATED 标记 |
/context detail | 详细查看 skills、tools、文件的 token 开销 | 找出吃 token 最多的文件 |
/status | 当前会话 token 使用情况 | 是否接近上下文上限 |
openclaw doctor | 整体健康检查 | 文件大小与注入大小对比 |
memory_search("关键词") | 测试检索效果 | 验证记忆是否被正确索引 |
TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) MEMORY.md: OK | raw 18,400 chars (~4,600 tok) | injected 18,400 chars (~4,600 tok) SOUL.md: OK | raw 1,200 chars (~300 tok) | injected 1,200 chars (~300 tok)
看到 TRUNCATED 就说明该文件超限了，需要优化。
MEMORY.md 太长 → 超出 bootstrapMaxChars → 注入时被截断 → Agent 看不到后面的内容。
解决方案：压缩内容 → 拆分主题文件 → 启用 Dreaming 自动筛选 → 配置 Heartbeat 定期维护 → 最后才考虑调大限制。
核心理念：MEMORY.md 是精炼的「知识库」，不是大杂烩的「日记本」。