记忆系统

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

四层记忆架构

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

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

设计意图

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

Daily Logs（每日日志）

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

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 会触发自动的记忆保存与上下文压缩流程，避免关键信息丢失。

触发流程

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。

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

适用场景

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

memory_get — 精确读取

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

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

记忆系统最佳实践

给 Agent 配置者的建议

1. SOUL.md 写好就不要改 — 它定义了 Agent 的核心身份，频繁修改会导致人格不一致
2. 善用 MEMORY.md — 重要的用户偏好和决策应该被记录，而不是依赖 Session 上下文
3. Daily Log 自动管理 — 无需手动维护，Agent 会自行追加
4. 信任 Pre-Compaction — 长对话中不必担心信息丢失，自动压缩会保留关键内容