一、记忆系统架构

OpenClaw 采用双层记忆设计，模拟人类的短期记忆和长期记忆：

┌─────────────────────────────────────────┐
│         AI Agent 工作记忆               │
│      (LLM Context Window)               │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │  当前对话上下文                    │  │
│  │  + 最近 1-2 天的日志               │  │
│  │  + MEMORY.md 中的长期记忆          │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
              ↓ 接近上下文限制时
┌─────────────────────────────────────────┐
│      预压缩记忆刷新机制                  │
│   (Pre-compaction Memory Flush)         │
│                                         │
│  AI 自主决定保存什么到磁盘               │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│         持久化存储 (磁盘)                │
│                                         │
│  ├─ memory/2026-02-10.md (短期记忆)    │
│  ├─ memory/2026-02-09.md               │
│  └─ MEMORY.md (长期记忆)                │
└─────────────────────────────────────────┘

二、两层记忆详解

2.1 第一层：短期记忆（Daily Logs）

文件位置：~/.openclaw/workspace/memory/YYYY-MM-DD.md

特点：

自动创建：每天自动创建新文件
追加模式：只追加，不修改历史内容
自动加载：会话启动时自动加载当天和前一天的日志
临时性：提供最近的时间上下文

2.2 第二层：长期记忆（MEMORY.md）

文件位置：~/.openclaw/workspace/MEMORY.md

特点：

精选内容：只保存重要、稳定的信息
手动或自动更新：可以手动编辑，也可以由 AI 自动写入
持久性：跨会话保持
简洁性：应保持精简，避免冗余

三、记忆是如何更新的？

3.1 自动更新机制：预压缩记忆刷新

这是 OpenClaw 最核心的记忆机制！

触发条件：当前上下文令牌数 > 软阈值（默认 4000 tokens）

工作流程：

监控上下文使用 → 持续监控令牌数 → 接近限制
触发静默代理回合（Silent Agentic Turn）：系统自动插入特殊提示，要求 AI 将重要信息写入持久化存储
AI 自主决策：没有硬性规则，AI 根据上下文自己判断什么重要
写入磁盘：AI 执行文件写入操作
压缩上下文：保存完成后，旧的对话历史被总结或丢弃，释放上下文空间

关键特点：

✅ 每个压缩周期只执行一次
✅ 完全由 AI 自主判断保存什么
✅ 使用标准工具，没有特殊的 memory_write 工具
✅ 工作空间只读时跳过

3.2 手动更新机制

用户也可以显式要求 AI 保存信息：

用户: "请记住，我们的生产环境部署时间是每周三凌晨 2 点"
AI: "好的，我会将这个重要信息保存到长期记忆中。"
    [执行 write_to_file("MEMORY.md", ...)]

四、记忆是如何使用的？

4.1 混合检索机制

OpenClaw 使用 BM25 + 向量搜索的混合方式检索记忆：

用户查询
    ↓
┌─────────────────────────────────────┐
│   混合检索（Hybrid Search）          │
│                                     │
│  ┌──────────────┐  ┌─────────────┐  │
│  │ BM25 搜索    │  │ 向量搜索     │  │
│  │ (关键词匹配) │  │ (语义理解)   │  │
│  │ 权重: 30%    │  │ 权重: 70%   │  │
│  └──────────────┘  └─────────────┘  │
│         ↓                 ↓         │
│      合并结果 + 加权评分            │
└─────────────────────────────────────┘
    ↓
返回最相关的记忆片段 → 注入到 AI 的上下文中

BM25（30% 权重）：使用 SQLite FTS5 全文搜索，擅长精确匹配关键词
向量语义搜索（70% 权重）：使用 embeddings + 余弦相似度，擅长概念匹配

4.2 记忆加载时机

会话启动时：

加载 MEMORY.md（长期记忆）
加载 memory/今天.md
加载 memory/昨天.md
加载其他配置文件（SOUL.md, AGENTS.md 等）

对话过程中：根据用户查询动态检索相关记忆，注入到当前上下文中。

五、AI 如何判断什么需要保存？

OpenClaw 没有硬性规则，完全依赖 AI 的判断力。

AI 在预压缩刷新时会考虑：

重要性评估：这是一次性信息还是需要长期记住？
信息分类：

短期信息 → memory/YYYY-MM-DD.md（今天的活动、临时决策）
长期信息 → MEMORY.md（用户偏好、项目约定、关键配置）

去重和整合：避免重复，更新已有信息

六、记忆系统的哲学

文件即真相（Files as Source of Truth）

所有记忆都是人类可读的 Markdown 文件，用户可以直接查看、编辑、删除，可以用 Git 进行版本控制，没有黑盒数据库。

上下文窗口 = 临时缓存

LLM 上下文窗口 ≈ RAM（易失性）
磁盘文件 ≈ 硬盘（持久性）

类似计算机的虚拟内存机制！

AI 自主性

信任 AI 的判断力，不设置僵硬的规则，让 AI 像人类一样决定什么值得记住。

七、USER.md vs MEMORY.md

工作空间完整文件结构

~/.openclaw/workspace/
├── SOUL.md       # AI 的个性和价值观
├── AGENTS.md     # 操作规则和安全策略
├── TOOLS.md      # 本地环境配置
├── IDENTITY.md   # AI 的角色定义
├── USER.md       # 👈 关于用户的静态信息
├── MEMORY.md     # 👈 动态的长期记忆
├── HEARTBEAT.md  # 主动监控清单
├── BOOTSTRAP.md  # 启动配置
└── memory/       # 每日日志目录

核心区别

USER.md   = "关于你的用户手册"（相对静态）
MEMORY.md = "我们一起经历的事情"（动态变化）

USER.md   = 回答 "我是谁"
MEMORY.md = 回答 "我在做什么"

维度	USER.md	MEMORY.md
性质	静态档案	动态记忆
内容	关于用户的事实	关于经历的记录
更新频率	很少（几个月一次）	频繁（几乎每天）
主语	”用户是…"	"我们做了…”
示例	”用户擅长 Python"	"上周决定用 FastAPI”

它们如何协同工作

用户提问
    ↓
1. 加载 USER.md  → 了解用户是谁、擅长什么
2. 加载 MEMORY.md → 了解最近在做什么、遇到什么问题
3. 加载 memory/今天.md → 了解今天和昨天的具体活动
4. 综合所有信息 → 提供个性化、有上下文的回答

八、总结

USER.md  = "我的简历和偏好"
MEMORY.md = "我的工作日志和经验"

使用建议：

初次设置：认真填写 USER.md
日常使用：让 AI 维护 MEMORY.md
定期维护：每周整理 MEMORY.md，每季度更新 USER.md
保持分离：不要混淆两者的内容

这种设计让 AI 既能了解你这个人（USER.md），又能记住你们一起做过的事（MEMORY.md），从而提供更加个性化和有上下文的帮助！