OpenClaw 记忆系统架构详解
Yuhang2026年2月17日
OpenClaw架构AI
概述
OpenClaw 采用双层记忆架构管理 AI 助手的状态与上下文：
- 短期记忆：当前会话的上下文（有长度限制，重启后清空）
- 长期记忆：固化在文件系统中的持久信息
本文档详细说明该架构的设计原理、文件层级及最佳实践。
一、架构设计
1.1 核心原则：Text > Brain
OpenClaw 的设计哲学强调文件持久化优于内存存储：
- 不依赖模型的"隐性记忆"
- 重要信息必须落盘保存
- 文件格式通用，便于审计与迁移
1.2 四层存储模型
| 层级 | 位置 | 存储内容 | 生命周期 |
|---|---|---|---|
| L1 灵魂档案 | clawd/*.md | 人格、规则、用户档案 | 永久 |
| L2 每日日志 | clawd/memory/*.md | 每日活动详细记录 | 永久 |
| L3 专题笔记 | clawd/notes/*.md | 用户创建的专题内容 | 永久 |
| L4 外部知识库 | Obsidian | 系统化长期知识 | 永久 |
二、L1：灵魂档案详解
位于工作目录根目录，每次会话启动时自动加载。
2.1 文件清单
| 文件名 | 功能说明 | 更新频率 |
|---|---|---|
SOUL.md | AI 性格、说话风格、行为准则 | 低 |
IDENTITY.md | 身份标识（名称、emoji、头像路径） | 极低 |
USER.md | 用户档案（偏好、健康、日程） | 按需 |
AGENTS.md | 操作规则、安全边界、经验教训 | 中 |
MEMORY.md | 项目状态、技术决策、核心知识 | 高 |
HEARTBEAT.md | 定时任务清单、检查项 | 低 |
TOOLS.md | 工具配置 | 按需 |
2.2 关键文件示例
USER.md 结构：
- Timezone: Asia/Shanghai
- Health: 颈椎曲度变直、腰间盘膨出
- Schedule: 健身周一三五 20:30
- Preferences: 文字详细、语音极简
HEARTBEAT.md 结构：
- 每周一、三、五 19:30 检查健身提醒
- 免打扰时段: 23:30 - 08:00
三、L2：每日日志
按日期命名的 Markdown 文件，记录当日所有活动。
3.1 命名规范
YYYY-MM-DD.md— 单日记录YYYY-MM-DD-HHMM.md— 同日多记录
3.2 与 MEMORY.md 的关系
Daily Notes 作为原始日志，定期提炼至 MEMORY.md。
四、L3 & L4：扩展存储
4.1 专题笔记（notes/）
用户创建的独立文档，与系统运行无关。
4.2 Obsidian 知识库
独立管理的知识库，包含系统化的长期知识。
五、记忆流转机制
用户输入 → 短期记忆 → Daily Notes → MEMORY.md
Context Flush 协议：
| 上下文使用率 | 动作 |
|---|---|
| < 50% | 正常运行 |
| 50-70% | 提高警觉 |
| 70-85% | 主动保存 |
| > 85% | 紧急保存 |
六、技术实现
6.1 文件访问限制
- 工作目录限定：
~/clawd/ - Obsidian 读取可能受 iCloud 同步影响
6.2 API 调用
记忆系统通过标准文件 IO 操作。
七、最佳实践
- 重要信息明确指示"记录下来"
- 定期回顾 MEMORY.md 清理过时信息
- 启动时按序加载：SOUL → USER → MEMORY → HEARTBEAT
- 定期提炼知识至 MEMORY.md
八、参考
- OpenClaw 文档：https://docs.openclaw.ai
- 项目仓库：https://github.com/openclaw/openclaw
0
Likes
