龙虾文档

主题

今天更新

记忆系统 ​

OpenClaw 的记忆系统赋予 Agent 跨会话的持久记忆能力，使其能够记住用户偏好、历史决策和对话上下文，提供真正个性化的交互体验。

四层记忆架构 ​

OpenClaw 采用 SOUL → TOOLS → USER → Session 的四层分层架构，每一层拥有不同的生命周期和加载策略。

层级存储位置生命周期说明
SOULSOUL.md永久不可变Agent 的人格、价值观、核心身份定义
TOOLSSkills + Extensions按需加载当前可用工具和技能列表
USERMEMORY.md + 向量数据库持久化用户偏好、决策、历史事实
Session内存 + sessions.json会话级当前对话实时上下文

设计意图

分层架构确保了不可变身份（SOUL）与动态知识（USER / Session）的清晰分离。SOUL 层定义 Agent「是谁」，创建后不应被修改；而 USER 和 Session 层则随着交互持续演进。

Daily Logs（每日日志） ​

每天的交互记录以 append-only 方式写入 memory/YYYY-MM-DD.md 文件。

text
workspace/
└── memory/
    ├── 2026-03-08.md
    ├── 2026-03-09.md
    └── 2026-03-10.md   ← 今天的日志

加载策略：Session 启动时，Agent 自动读取今天和昨天的日志，以获取近期上下文。更早的日志不会主动加载，但可通过向量记忆搜索检索。

日志格式

Daily Log 是纯 Markdown 文件，Agent 在交互过程中以追加方式写入关键事件、决策和用户请求摘要。文件只增不删，保证完整的审计轨迹。

Long-term Memory（长期记忆） ​

MEMORY.md 是持久化的长期记忆文件，用于存储跨会话需要保留的重要信息：

  • 决策记录 — 用户做出的重要选择和偏好设定
  • 用户偏好 — 沟通风格、技术栈、常用工具等
  • 历史事实 — 需要长期记住的关键信息

加载限制

MEMORY.md 仅在 main / private session 中加载。群组会话（group session）不会加载长期记忆，以保护用户隐私。详见会话管理。

Agent 可以在对话过程中主动写入 MEMORY.md，但更常见的触发时机是 Pre-Compaction（自动压缩）流程。

Pre-Compaction（自动记忆保存） ​

当 Session 接近 token 上限时，OpenClaw 会触发自动的记忆保存与上下文压缩流程，避免关键信息丢失。

触发流程 ​

text
Session token 接近阈值（约 4000 tokens 剩余）
        │
        ▼
  ┌─────────────────────────┐
  │  1. 检测阈值             │
  │     监控当前 token 用量   │
  └────────┬────────────────┘
           │
           ▼
  ┌─────────────────────────┐
  │  2. 静默保存             │
  │     写入 MEMORY.md       │
  │     写入 Daily Log       │
  └────────┬────────────────┘
           │
           ▼
  ┌─────────────────────────┐
  │  3. 压缩上下文           │
  │     旧消息被压缩摘要     │
  │     返回 NO_REPLY        │
  └─────────────────────────┘

对用户透明

Pre-Compaction 是一次 silent agentic turn（静默代理回合），用户不会看到任何提示。Agent 在后台自动完成保存和压缩，然后继续正常对话。返回的 NO_REPLY 标记表示这次回合不需要向用户发送消息。

压缩策略 ​

  • 较旧的消息被压缩为摘要，保留关键信息
  • 最近的消息保持原样，确保对话连贯性
  • 重要的决策和偏好被写入 MEMORY.md，不会因压缩而丢失

向量记忆搜索 ​

OpenClaw 结合两种检索策略实现高质量的记忆搜索：

策略方式适用场景
Embedding 向量搜索语义相似度匹配模糊回忆、概念关联查询
BM25 关键词搜索精确关键词匹配精确名称、特定术语检索

底层存储使用 SQLite-vec，兼顾轻量部署和向量检索性能。

搜索工具 ​

Agent 可使用两个内置工具访问记忆：

memory_search — 语义搜索 ​

基于语义相似度检索相关记忆片段，返回约 400 token 的 chunks。

text
memory_search("用户上次提到的部署方案")
→ 返回语义最相关的记忆片段

适用场景

当你不确定具体细节但记得大致内容时，使用 memory_search 进行模糊检索。它会综合 Embedding 和 BM25 两种策略返回最相关的结果。

memory_get — 精确读取 ​

读取特定记忆文件的全部内容，适用于已知文件路径的场景。

text
memory_get("memory/2026-03-09.md")
→ 返回该文件完整内容

三层记忆模型 ​

OpenClaw 的记忆管理借鉴人类认知分层思路，将信息按提炼程度分为三层：

层级类比Agent 对应存储位置
Tier 1 信息层你看过的所有书学习笔记、原始资料、完整对话memory/learning/
Tier 2 知识层你的读书笔记每日工作日志、提炼后的知识点memory/YYYY-MM-DD.md
Tier 3 智慧层你的世界观跨领域洞察、底层规律、核心方法论MEMORY.md

不分层的后果：所有信息堆在一起，MEMORY.md 膨胀到 500+ 行，找不到历史信息，token 消耗越来越大，记忆混乱没有结构。分层后 MEMORY.md 精简到 <100 行，查找成功率从 ~60% 提升到 ~95%，token 消耗降低 30-40%。

七个核心文件 ​

OpenClaw 工作区中有 7 个核心文件，各司其职。核心原则：一个信息只存一个地方，不在多个文件中重复。

文件职责内容更新频率
AGENTS.md怎么工作工作流程、操作规范、任务管理规则流程变更时
SOUL.md我是谁人格特质、核心原则、价值观很少变
USER.md我服务谁用户的偏好、习惯、决策模式发现新偏好时
TOOLS.md怎么操作工具使用手册、命令格式、配置说明配置变更时
MEMORY.md我记得什么长期记忆、方法论、核心认知提炼智慧时（需用户同意）
ERRORS.md我在哪里失败过错误记录、教训、避坑指南犯错时
SHARED.md团队共识多 Agent 共享的信息团队决策时

文件大小参考 ​

文件典型大小判断标准
MEMORY.md<100 行只保留跨领域洞察和核心原则
AGENTS.md300-800 行只保留核心工作规则和决策流程
ERRORS.md<200 行保留最近 6 个月 + 经常重复的错误
SHARED.md200-500 行团队共识，所有 Agent 都需要的信息
USER.md<100 行用户偏好和习惯
TOOLS.md视工具数量工具使用说明
SOUL.md<50 行人格特质，很少变化

记忆写入的 7 种分类 ​

不同类型的信息应写入不同文件。核心原则：不等 Heartbeat，用户做出决策时立即写入。

信息类型写到哪里触发条件举例
用户的决策/指令MEMORY.md + Daily Log用户确认或下达指令时立即写入"TOOLS.md 不用启动加载"
用户的偏好/习惯USER.md发现新偏好时立即写入"别让我来回折腾"
我犯的错ERRORS.md + Daily Log犯错被纠正时立即写入"write 覆盖了文件"
工作流程变更AGENTS.md + 检查 SOUL.md/MEMORY.md 同步流程确认时立即写入"MEMORY.md 每次都读"
工具/配置变更TOOLS.md配置变更确认后写入"飞书新增了一个权限"
业务认知MEMORY.md + Daily Log需求讨论产出结论时写入"profile 改版核心是数据中心"
闲聊/临时讨论不记—"你在吗"

Heartbeat 记忆整理 ​

Heartbeat 每 30 分钟触发一次，但记忆整理每 6 小时一次（太频繁浪费 token，太久容易遗漏，6 小时一天 4 次刚好覆盖工作时段）。

整理流程：

  1. 检查 memory/heartbeat-state.json 中的 lastMemoryReview 时间戳
  2. 如果距离上次整理 < 6 小时 → 跳过整理，发送"一切正常"
  3. 如果需要整理 → 读取最近的 memory/YYYY-MM-DD.md（自上次整理后的新内容）
  4. 提炼到对应文件：经验教训/业务认知 → MEMORY.md，用户偏好/习惯 → USER.md，犯的错误 → ERRORS.md
  5. 清理过时信息：已完成的待办事项、被新决策覆盖的旧决策
  6. 同步更新相关文件（如有流程变化）
  7. 更新 heartbeat-state.json 时间戳
  8. 生成记忆整理报告

Dreaming 记忆机制（2026.4.5+） ​

Dreaming（做梦） 是 2026.4.5 引入的实验性长期记忆机制，它让 OpenClaw 像人类一样通过后台"睡眠"把零散的 Daily Log 片段提炼为可持久召回的知识。

三个协作阶段 ​

Dreaming 不再是单一循环，而是三个独立调度、独立恢复的协作阶段：

阶段类比主要工作
Light（浅睡）小憩短期记忆快速整理、热点内容加权
Deep（深睡）深度睡眠把 Daily Log 分块后送入持久化候选，重复运行是 replay-safe 的，不会在 MEMORY.md 里产生重复条目
REM（快速眼动）做梦扫描阶段性真相、生成概念标签，多语言可用；输出写入顶层 dreams.md

每个阶段都可以单独开停或按自己的节拍运行；doctor / status 提供恢复支持。

/dreaming 命令与 Dreams UI ​

  • /dreaming 命令 —— 聊天中查看/触发 dreaming 状态
  • Dreams 面板 —— Control UI 里直接查看被提炼的"梦境"
  • Dream Diary —— 列出按日期聚合的 dreaming 产物，龙虾 Logo 动画一直浮在内容之上

配置与调试 ​

用户层面的配置保持极简：

json
{
  "memory": {
    "dreaming": {
      "enabled": true,
      "frequency": "normal",
      "recencyHalfLifeDays": 7,
      "maxAgeDays": 90
    }
  }
}
  • recencyHalfLifeDays / maxAgeDays 控制召回衰减曲线
  • 开启 verbose 日志可审阅每一次晋升决策
  • 新增调试工具：
    • openclaw memory rem-harness —— 试跑 REM 阶段
    • openclaw memory promote-explain —— 解释某条记忆为什么被晋升

dreams.md 与日常记忆的关系

Dreaming 的 trail 内容写入顶层 dreams.md，不会被拉入默认召回，但可以显式读取。这是为了把 dreaming 的"推测性产物"与 Daily Log / MEMORY.md 的"确认事实"清楚分开。

Bedrock Embeddings 向量后端（2026.4.5+） ​

除了默认的 SQLite-vec，2026.4.5 起你可以把向量记忆挂到 Amazon Bedrock 上，使用 Titan、Cohere、Nova、TwelveLabs 等 Embedding 模型：

json
{
  "memory": {
    "embeddings": {
      "provider": "auto",
      "bedrock": { "model": "amazon.titan-embed-text-v2" }
    }
  }
}

provider: "auto" 会自动走 AWS 凭证链（环境变量 / IAM 角色 / SSO），向量维度按具体模型自动设定。

记忆系统最佳实践 ​

给 Agent 配置者的建议

  1. SOUL.md 写好就不要改 — 它定义了 Agent 的核心身份，频繁修改会导致人格不一致
  2. 善用 MEMORY.md — 重要的用户偏好和决策应该被记录，而不是依赖 Session 上下文
  3. Daily Log 自动管理 — 无需手动维护，Agent 会自行追加
  4. 信任 Pre-Compaction — 长对话中不必担心信息丢失，自动压缩会保留关键内容
  5. 文件写入铁律 — 写入已有文件永远用 edit 追加，绝不用 write 覆盖。write 会覆盖整个文件，导致已有内容全部丢失。只有创建全新文件时才用 write。
觉得有帮助？