OpenClaw 记忆系统设计详解
一、初始架构：本地优先的双层存储
核心设计哲学：「Markdown 即真相」
OpenClaw 最初采用的记忆架构以 "Markdown 即真相" 为核心理念：
记忆文件以纯 Markdown 格式 存储在本地磁盘，是人类可读、git 可追踪的原始真相；SQLite 向量索引是从 Markdown 派生出来的加速层，始终可重建。
整体分为短期缓存 与长期持久化两层：
记忆系统
├── 短期记忆（Short-term Cache）
│ └── 内存缓存，72小时内对话上下文
└── 长期记忆（Long-term Storage）
├── SQLite 数据库（结构化索引）
└── Markdown 文件（原始真相）1. 短期记忆 ------ 内存缓存
- 存储位置：运行时内存（In-Memory）
- 存储内容：当前对话窗口的原始上下文
- 生命周期：72小时，会话结束后失效
- 容量限制：受限于模型 Max Tokens
- 作用：保证多轮对话的连贯性
2. 长期记忆 ------ Markdown 文件持久化
~/.openclaw/workspace/
├── MEMORY.md # 长期决策、用户偏好、关键事实
└── memory/ # 每日日志目录
├── 2026-01-30.md # 按日期分片的每日笔记
├── 2026-01-31.md
└── ...| 文件 | 存储内容 | 加载时机 |
|---|---|---|
MEMORY.md |
持久性事实、用户偏好、关键决策 | 仅在主私有会话加载 |
memory/YYYY-MM-DD.md |
每日会话摘要、日常笔记 | 按日期按需读取 |
extraPaths |
外部文档索引（用户自定义路径） | 按需检索 |
3. SQLite ------ 派生索引层
~/.openclaw/memory/
└── <agentId>.sqlite # 每个 Agent 独立的向量索引库
├── FTS5 # 全文搜索索引
├── vec0 # 向量相似度搜索
└── 结构化元数据 # 文件路径、时间戳等- 性质 ：从 Markdown 派生，不是原始真相
- 作用：加速检索，支持语义搜索与关键词混合搜索
- 可重建：Markdown 存在时，SQLite 索引随时可重新生成
4. 整体数据流向
用户对话
↓
内存上下文（短期缓存）
↓ 触发写入规则
Markdown 文件落盘（真相层）
↓ 索引管道
SQLite（FTS5 + vec0）加速层
↑ 工具调用检索
Agent 对话上下文注入5. 本地优先原则
所有存储方式均遵循 Local-First（本地优先） 原则：
- ✅ 所有记忆数据存储在用户本地设备，不上传云端
- ✅ 纯 Markdown 格式，人类可读、可直接编辑
- ✅ 支持 git 追踪，记忆变更历史可回溯
- ✅ 仅调用 LLM API 时联网，支持切换本地模型零联网运行
二、社区演化：分层记忆架构
随着社区实践深入，原生架构暴露出核心痛点------整份 MEMORY.md 每轮全量塞进 system_prompt，不做检索，随使用无限增长，导致 Token 消耗爆炸。社区在此基础上演化出更完善的分层架构。
分层设计总览
将不同类型的信息存储在不同层级，平衡连续性与 Token 消耗：
| 层级 | 存储内容 | 加载策略 | Token 成本 |
|---|---|---|---|
| 身份层 | 核心自我、用户偏好 | 始终加载 | ~200 tokens |
| 活动上下文 | 当前任务、近期决策 | 始终加载 | ~500 tokens |
| 档案层 | 完整历史、项目细节 | 按需语义检索 | 节省 96% |
核心记忆文件结构
~/openclaw-workspace/
├── SOUL.md # AI 的人格和核心行为准则
├── USER.md # 用户信息（名字、偏好、职业等）
├── IDENTITY.md # AI 的自我认知（名字、性格、定位）
├── MEMORY.md # 长期记忆（重要事件、项目进度、关键决策）
├── HEARTBEAT.md # 周期性任务清单（主动服务配置）
└── memory/ # 每日记忆文件夹
├── 2026-03-04.md
├── 2026-03-05.md
└── ...RAG 记忆工作流程
每次对话，系统自动完成以下流程：
用户输入
↓
预处理（清洗、脱敏）
↓
检索 Retrieve ------ 在向量库中搜索 Top-K 相关历史记忆
↓
增强 Augment ------ 检索到的记忆 + 当前对话 + System Prompt 组装完整 Prompt
↓
生成 Generate ------ LLM 基于完整 Prompt 输出回复
↓
存储 Store ------ 将当前对话追加到短期上下文记忆生命周期
① 首次启动：基础记忆加载
OpenClaw 自动读取核心配置文件，构建初始记忆基础：
SOUL.md--- 明确 AI 的行为准则和沟通风格USER.md--- 存储用户核心信息，让 AI 快速了解服务对象IDENTITY.md--- 确立 AI 的自我定位，保证交互一致性
② 日常使用：动态记忆交互
- 读取当天的
memory/YYYY-MM-DD.md，加载最新会话上下文 - 检索最近 1~2 天的每日记忆文件，确保短期对话连贯性
- 对话结束后自动写入新的记忆内容
③ 记忆写入规范
markdown
## 记忆管理规范
- 日志写入 memory/YYYY-MM-DD.md，记录结论而非过程
- 项目变更时同步更新 memory/projects.md
- 遇到问题时记录到 memory/lessons.md向量数据库后端支持
yaml
memory:
enabled: true
# 支持: chroma（默认轻量）| milvus | qdrant | faiss
backend: chroma| 后端 | 特点 |
|---|---|
| Chroma | 默认，轻量级，适合本地使用 |
| Milvus | 适合大规模生产环境 |
| Qdrant | 高性能向量搜索 |
| FAISS | Facebook 开源，适合离线场景 |
三、社区主流优化插件
① MemOS（推荐 ⭐⭐⭐⭐⭐）
- 底层用 Neo4j 图数据库记录实体关系
- 用 Qdrant 向量搜索记语义相似内容
- 实测 Token 消耗下降 72%，支持多 Agent 共享记忆池
② PowerMem 插件
- 会话前按需检索相关记忆注入上下文
- 会话后智能抽取关键事实落库
- 实测同等任务 Token 消耗降至默认方案的 18%
③ 知识图谱上下文引擎
https://so.html5.qq.com/page/real/search_news?docid=70000021_58069bafede28652
- 从对话中提取结构化三元组（实体-关系-实体）构建知识图谱
- 上下文压缩率高达 75%（174条消息从 9.5 万 token 压缩至 2.4 万）
- 支持跨会话记忆重用
四、自定义记忆逻辑（高级）
OpenClaw 允许开发者通过 Python 脚本完全接管记忆的写入、读取和遗忘逻辑：
python
# skills/custom/custom_memory.py
class CustomMemoryHandler:
def write(self, content):
# 自定义写入逻辑
pass
def read(self, query):
# 自定义检索逻辑
pass
def forget(self, criteria):
# 自定义遗忘逻辑
pass总结
OpenClaw 记忆系统
├── 文件层（Markdown）------ 持久化、可读、透明
├── 向量层（Chroma/Qdrant 等）------ 语义检索、按需加载
├── 图谱层（Neo4j，可选）------ 关系推理、跨会话关联
└── 插件层（MemOS/PowerMem）------ Token 优化、智能管理OpenClaw 记忆系统的核心设计哲学是：记忆以落盘 Markdown 的形式存在，而非黑盒式的隐式记忆，实现了从 "prompt" 到 "workspace" 的范式转变。初始架构奠定了本地化、透明可编辑的基础，社区演化则在此之上持续突破 Token 瓶颈，走向更智能的分层检索体系。