OpenClaw 记忆系统 -- 持久化

本文依据 OpenClaw 的 v2026.4.22 版本，重点分析了 OpenClaw 的记忆系统的文件存储结构和数据库存储结构，以及文件和数据库的存储关系。并简单的介绍这些存储的数据是如何在业务之间流转的。

shendong70

422人浏览 · 2026-04-27 17:24:39

shendong70 · 2026-04-27 17:24:39 发布

1. 文件存储

1.1. 文件结构

├── memory/                    # 记忆主目录
│   ├── YYYY-MM-DD.md          # 每日记忆文件
│   ├── dreaming/              # 梦境系统输出
│   │   ├── light/             # Light阶段报告
│   │   │   └── YYYY-MM-DD.md  # 每日Light阶段报告
│   │   ├── rem/               # REM阶段报告
│   │   │   └── YYYY-MM-DD.md  # 每日REM阶段报告
│   │   └── deep/              # Deep阶段报告
│   │       └── YYYY-MM-DD.md  # 每日Deep阶段报告
├── sessions/                  # 会话目录
│   └── session-*.jsonl        # 会话文件（JSONL格式）
├── MEMORY.md                  # 持久记忆文件
└── DREAMS.md                  # 梦境系统报告

1.2. 主要存储文件

每日记忆文件：memory/YYYY-MM-DD.md - 存储每日的短期记忆
持久记忆文件：MEMORY.md - 存储通过梦境系统提升的持久记忆
梦境报告文件：DREAMS.md - 存储梦境系统的执行结果和反思
梦境阶段报告：memory/dreaming/<phase>/YYYY-MM-DD.md - 存储各阶段的详细报告

1.3. 存储内容与示例

1.3.1. 每日记忆文件 (`memory/YYYY-MM-DD.md`)

存储内容：当日会话的摘要和重要信息
内容示例：

# 2026-04-27

## 会议记录
- 项目进度讨论：完成了80%
- 下一步计划：下周发布beta版本

## 重要任务
- 完成API文档
- 测试新功能

## 学习笔记
- 学习了TypeScript泛型高级用法
- 了解了向量数据库原理

1.3.2. 会话文件 (`sessions/session-*.jsonl`)

存储内容：完整对话历史，包括用户消息、助手回复、工具调用
内容示例：

{"role":"user","content":"What's the capital of France?","timestamp":"2026-04-27T10:00:00Z","id":"msg-1"}
{"role":"assistant","content":"The capital of France is Paris.","timestamp":"2026-04-27T10:00:05Z","id":"msg-2"}
{"role":"toolcall","toolName":"memory_search","params":{"query":"Paris landmarks"},"timestamp":"2026-04-27T10:00:10Z","id":"msg-3"}
{"role":"toolResult","toolName":"memory_search","result":{"items":[{"corpus":"memory","path":"memory/2026-04-20.md","score":0.85,"snippet":"Eiffel Tower is a famous landmark in Paris."}]},"timestamp":"2026-04-27T10:00:15Z","id":"msg-4"}
{"role":"assistant","content":"Paris is known for landmarks like the Eiffel Tower, Louvre Museum, and Notre-Dame Cathedral.","timestamp":"2026-04-27T10:00:20Z","id":"msg-5"}

1.3.3. 持久记忆文件 (`MEMORY.md`)

存储内容：长期保存的重要事实、偏好、关系等
内容示例：

# 持久记忆

## 个人信息
- 姓名：张三
- 职业：软件工程师
- 兴趣：编程、阅读、旅行

## 重要关系
- 家人：父母、妻子、儿子
- 朋友：李四、王五

## 知识偏好
- 喜欢TypeScript胜过JavaScript
- 偏好使用VS Code
- 关注前端和AI技术

1.3.4. 梦境系统报告 (`DREAMS.md`)

存储内容：梦境系统的执行结果和反思
内容示例：

# 梦境报告

## 2026-04-27

### Light阶段
- 整理了最近7天的记忆
- 识别了3个主要主题：工作、学习、家庭

### REM阶段
- 发现了工作与学习的关联：项目需要新技能
- 识别了家庭时间不足的问题

### Deep阶段
- 提升了3条持久记忆：
  1. 项目进度80%，下周发布beta
  2. 新技能学习计划：TypeScript泛型
  3. 家庭时间安排：每天1小时

## 2026-04-26
...

1.4. 记忆文件类型与关系

记忆文件类型	路径模式	作用	与其他文件的关系
每日记忆	`memory/YYYY-MM-DD.md`	存储短期记忆	由会话摘要生成，被梦境系统处理
持久记忆	`MEMORY.md`	存储长期记忆	由梦境系统的Deep阶段从每日记忆提升
梦境报告	`DREAMS.md`	存储梦境系统结果	由梦境系统的各阶段生成
梦境阶段报告	`memory/dreaming/<phase>/YYYY-MM-DD.md`	存储各阶段详细报告	由梦境系统各阶段生成
会话文件	`sessions/session-*.jsonl`	存储完整对话历史	包含用户消息、助手回复、工具调用

1.5. 文件处理逻辑关系

1.5.1. 核心处理流程

1.5.2. 详细处理逻辑

会话文件 → 每日记忆文件
- 触发：会话结束或达到压缩阈值
- 处理：compactEmbeddedPiSessionDirect 函数生成会话摘要，保存到 memory/YYYY-MM-DD.md
- 代码：src/agents/compaction.ts
每日记忆文件 → 梦境阶段报告
- 触发：定时执行或手动触发梦境系统
- 处理：
  - Light阶段：整理排序短期记忆 → runLightDreaming
  - REM阶段：反思发现主题模式 → runRemDreaming
  - Deep阶段：提升持久记忆 → runDeepDreaming
- 代码：extensions/memory-core/src/dreaming/
梦境阶段报告 → 持久记忆文件
- 触发：Deep阶段执行完成
- 处理：将重要信息从每日记忆提升到 MEMORY.md
- 代码：extensions/memory-core/src/dreaming/deep.ts
所有记忆文件 → SQLite数据库
- 触发：记忆同步（会话开始、搜索时、定时）
- 处理：updateIndex 函数将文件分块、生成向量嵌入、更新数据库
- 代码：src/memory-host-sdk/engine-storage.ts
SQLite数据库 → 大模型提示词
- 触发：用户查询或会话开始
- 处理：searchMemory 函数检索相关记忆，生成提示词
- 代码：src/memory-host-sdk/host/internal.ts

1.6. 涉及的主要代码和函数

函数名	文件路径	作用
`buildSessionStartupContextPrelude`	`src/auto-reply/reply/startup-context.ts`	构建会话启动上下文，加载最近记忆
`compactEmbeddedPiSessionDirect`	`src/agents/compaction.ts`	压缩会话，生成每日记忆摘要
`runMemorySyncWithReadonlyRecovery`	`src/memory-host-sdk/host/internal.ts`	执行记忆同步，更新数据库
`updateIndex`	`src/memory-host-sdk/engine-storage.ts`	更新记忆索引，处理文件变更
`searchMemory`	`src/memory-host-sdk/host/internal.ts`	检索相关记忆，用于生成提示词
`runLightDreaming`	`extensions/memory-core/src/dreaming/light.ts`	执行梦境系统Light阶段
`runRemDreaming`	`extensions/memory-core/src/dreaming/rem.ts`	执行梦境系统REM阶段
`runDeepDreaming`	`extensions/memory-core/src/dreaming/deep.ts`	执行梦境系统Deep阶段
`promoteToLongTerm`	`extensions/memory-core/src/dreaming/deep.ts`	将记忆提升到持久记忆

1.7. 业务触发流程

1.7.1. 会话文件生成与更新

触发条件：

新会话创建
用户发送消息
助手回复
工具调用执行

流程：

用户输入消息 → 追加到会话文件
助手生成回复 → 追加到会话文件
工具调用执行 → 追加工具调用和结果到会话文件
会话结束 → 触发压缩，生成每日记忆

1.7.2. 每日记忆文件生成

触发条件：

会话结束
会话达到压缩阈值（compaction.reserveTokens）
手动触发压缩

流程：

检查会话大小是否达到阈值
执行会话压缩，生成摘要
将摘要写入 memory/YYYY-MM-DD.md
触发记忆同步，更新数据库

1.7.3. 梦境系统执行

触发条件：

定时执行（dreaming.frequency cron表达式）
手动触发（/dreaming 命令）
系统启动时

流程：

Light阶段：整理排序短期记忆
REM阶段：反思发现主题模式
Deep阶段：提升持久记忆到 MEMORY.md
生成 DREAMS.md 报告
触发记忆同步，更新数据库

1.7.4. 记忆同步

触发条件：

会话开始（sync.onSessionStart: true）
首次搜索（sync.onSearch: true）
定时同步（sync.intervalMinutes）
文件变更（sync.watch: true）

流程：

扫描 memory 和 sessions 目录
检测文件变更（新增、修改、删除）
对变更文件执行分块、嵌入生成
更新 files 和 chunks 表
FTS5 自动更新 fts_chunks 表

1.7.5. 记忆检索

触发条件：

用户执行记忆搜索命令
系统生成提示词时需要上下文
会话开始时加载启动上下文

流程：

分析查询或上下文需求
执行混合搜索（向量+文本）
过滤和排序结果
格式化结果为提示词
提供给大模型

1.8. 约束条件

1.8.1. 文件大小限制

单个文件：
- 启动上下文：maxFileBytes 默认16384字节，最大64KB
- 记忆搜索：multimodal.maxFileBytes 限制多媒体文件大小
总字符数：
- 启动上下文：maxTotalChars 默认2800，最大50000

1.8.2. 存储限制

会话文件：
- session.maintenance.maxEntries：sessions.json 最大条目数500
- session.maintenance.rotateBytes：sessions.json 超过10MB时旋转
记忆文件：
- 每天最多5个文件（1个主要文件 + 4个slugged文件）
- 梦境阶段报告按日期存储，定期清理

1.8.3. 性能约束

嵌入缓存：
- 缓存嵌入向量，避免重复计算
- 定期清理过期缓存
搜索优化：
- 限制返回结果数量（maxResults 默认6）
- 应用分数阈值（minScore 默认0.35）
- 可选的MMR重排序提升多样性

1.8.4. 安全约束

文件读取：
- 使用 openBoundaryFile 确保文件路径在工作区内
- 限制文件读取大小，防止过大文件导致性能问题
数据处理：
- 压缩时移除工具结果的详细信息
- 启动上下文标记为"不受信任"，防止执行其中的指令

2. SQLite数据库存储

2.1. 存储路径

SQLite数据库：默认路径为 ~/.openclaw/memory/{agentId}.sqlite
- 向量存储：存储记忆块的向量嵌入
- 文本索引：存储记忆块的文本内容
- 元数据：存储记忆块的路径、时间戳等信息

2.2. 数据库结构

表名	作用	关键字段
`meta`	存储数据库元数据	`key` (主键), `value`
`files`	存储已索引的文件信息	`path` (主键), `source`, `hash`, `mtime`, `size`
`chunks`	存储记忆块信息（核心表）	`id` (主键), `path`, `source`, `start_line`, `end_line`, `hash`, `model`, `text`, `embedding`, `updated_at`
`fts_chunks`	全文搜索索引（FTS5虚拟表）	`text`, `id`, `path`, `source`, `model`, `start_line`, `end_line`
`embedding_cache`	缓存嵌入向量（可选）	`provider`, `model`, `provider_key`, `hash` (联合主键), `embedding`, `dims`, `updated_at`

OpenClaw的SQLite数据库包含以下表：

2.2.1. `meta` 表

CREATE TABLE meta (
  key TEXT PRIMARY KEY,
  value TEXT NOT NULL
);

用途：存储数据库元数据，确保版本兼容性和系统状态
内容：键值对形式的系统信息

使用场景：

数据库初始化：存储数据库版本号
系统启动：检查数据库版本，确保兼容性
架构变更：跟踪数据库架构版本，支持迁移
系统状态：存储系统级别的配置和状态信息

与其他表的关系：

独立表，不直接关联其他表
为整个数据库提供元数据支持

2.2.2. `files` 表

CREATE TABLE files (
  path TEXT PRIMARY KEY,
  source TEXT NOT NULL DEFAULT 'memory',
  hash TEXT NOT NULL,
  mtime INTEGER NOT NULL,
  size INTEGER NOT NULL
);

用途：存储已索引的文件信息
内容：
- path：文件路径（主键）
- source：来源类型（默认为’memory’）
- hash：文件内容哈希值
- mtime：文件修改时间
- size：文件大小

2.2.3. `chunks` 表

CREATE TABLE chunks (
  id TEXT PRIMARY KEY,
  path TEXT NOT NULL,
  source TEXT NOT NULL DEFAULT 'memory',
  start_line INTEGER NOT NULL,
  end_line INTEGER NOT NULL,
  hash TEXT NOT NULL,
  model TEXT NOT NULL,
  text TEXT NOT NULL,
  embedding TEXT NOT NULL,
  updated_at INTEGER NOT NULL
);

用途：存储记忆块信息（核心表）
内容：
- id：记忆块唯一标识
- path：所属文件路径
- source：来源类型
- start_line：在原始文件中的起始行号
- end_line：在原始文件中的结束行号
- hash：记忆块内容哈希值
- model：使用的嵌入模型
- text：记忆块的文本内容
- embedding：向量嵌入（序列化为文本）
- updated_at：更新时间

2.2.4. FTS5虚拟表

CREATE VIRTUAL TABLE fts_chunks USING fts5(
  text,
  id UNINDEXED,
  path UNINDEXED,
  source UNINDEXED,
  model UNINDEXED,
  start_line UNINDEXED,
  end_line UNINDEXED
);

用途：全文搜索索引
分词器：支持 unicode61（默认）和 trigram（用于CJK文本）
内容：与chunks表关联的全文搜索索引

2.2.5. 嵌入缓存表（可选）

CREATE TABLE embedding_cache (
  provider TEXT NOT NULL,
  model TEXT NOT NULL,
  provider_key TEXT NOT NULL,
  hash TEXT NOT NULL,
  embedding TEXT NOT NULL,
  dims INTEGER,
  updated_at INTEGER NOT NULL,
  PRIMARY KEY (provider, model, provider_key, hash)
);

用途：缓存嵌入向量，避免重复计算
启用条件：配置 cache.enabled: true

2.2.6. 表关系图

3. 记忆文件与数据库表的关系

3.1. 文件与数据库表的映射关系

3.2. 详细映射

文件到 files 表：
- 每个记忆文件对应 files 表中的一条记录
- 存储文件路径、来源、哈希、修改时间、大小
- 用于变更检测和文件管理
文件到 chunks 表：
- 每个文件被分成多个记忆块，每个块对应 chunks 表中的一条记录
- 存储块ID、文件路径、来源、行范围、哈希、模型、文本内容、向量嵌入
- 是记忆检索的核心数据
chunks 表到 fts_chunks 表：
- fts_chunks 是 FTS5 虚拟表，自动同步 chunks 表的文本内容
- 用于全文搜索功能
chunks 表到 embedding_cache 表：
- 当生成向量嵌入时，会检查 embedding_cache 表是否存在缓存
- 缓存命中则直接使用，否则生成新嵌入并缓存

4. 记忆存储操作

4.1. 读取操作

操作	函数名	文件路径	作用
搜索记忆	`searchMemory`	`src/memory-host-sdk/host/internal.ts`	执行混合搜索（向量+BM25）
读取文件信息	`getFiles`	`src/memory-host-sdk/engine-storage.ts`	获取文件列表
读取记忆块	`getChunks`	`src/memory-host-sdk/engine-storage.ts`	获取记忆块列表
读取元数据	`getMeta`	`src/memory-host-sdk/engine-storage.ts`	获取元数据

4.2. 更新操作

操作	函数名	文件路径	作用
更新索引	`updateIndex`	`src/memory-host-sdk/engine-storage.ts`	更新记忆索引
插入文件	`insertFile`	`src/memory-host-sdk/engine-storage.ts`	插入文件记录
插入记忆块	`insertChunk`	`src/memory-host-sdk/engine-storage.ts`	插入记忆块记录
更新元数据	`setMeta`	`src/memory-host-sdk/engine-storage.ts`	更新元数据
缓存嵌入向量	`cacheEmbedding`	`src/memory-host-sdk/engine-storage.ts`	缓存嵌入向量

4.3. 删除操作

操作	函数名	文件路径	作用
删除文件	`deleteFile`	`src/memory-host-sdk/engine-storage.ts`	删除文件记录
删除记忆块	`deleteChunksByPath`	`src/memory-host-sdk/engine-storage.ts`	按路径删除记忆块
清理过期缓存	`cleanupEmbeddingCache`	`src/memory-host-sdk/engine-storage.ts`	清理过期的嵌入缓存

5. 触发操作的业务流程

5.1. 记忆同步流程

触发条件：

会话开始时（sync.onSessionStart: true）
首次搜索时（sync.onSearch: true）
定时同步（sync.intervalMinutes）

流程：

扫描 memory 和 sessions 目录
对比文件哈希，检测变更
对新增或修改的文件：
- 调用 insertFile 更新 files 表
- 分块处理文件内容
- 为每个块生成向量嵌入
- 调用 insertChunk 插入 chunks 表
- FTS5 自动更新 fts_chunks 索引
对删除的文件：
- 调用 deleteFile 从 files 表删除
- 调用 deleteChunksByPath 从 chunks 表删除
- FTS5 自动更新索引

5.2. 记忆搜索流程

触发条件：

用户执行记忆搜索命令
系统需要相关记忆生成提示词

流程：

分析用户查询
生成查询向量嵌入
执行向量搜索：查询 chunks 表的 embedding 字段
执行文本搜索：查询 fts_chunks 表
合并结果，应用权重和过滤
返回搜索结果

5.3. 记忆压缩流程

触发条件：

会话接近上下文窗口限制
手动触发压缩

流程：

分析会话内容
生成会话摘要
保存摘要到 memory/YYYY-MM-DD.md
触发记忆同步，更新数据库
可选：清理过期会话数据

5.4. 梦境系统流程

触发条件：

定时触发（dreaming.frequency）
手动触发（/dreaming 命令）

流程：

Light 阶段：整理短期记忆
REM 阶段：发现主题模式
Deep 阶段：提升持久记忆到 MEMORY.md
触发记忆同步，更新数据库
生成 DREAMS.md 报告

6. 记忆的缓存（embedding_cache 表）

作用：缓存向量嵌入，避免重复计算，提升性能

使用场景：

记忆同步：生成记忆块的向量嵌入时
记忆检索：生成查询的向量嵌入时
任何需要向量嵌入的操作：如混合搜索、相似度计算

与其他表的关系：

与 chunks 表关联：为 chunks 表中的文本提供缓存的向量嵌入
独立于其他表：可以单独清理和管理

6.1. embedding_cache 缓存机制

6.1.1. 缓存内容

具体内容：

provider：嵌入提供商（如OpenAI）
model：嵌入模型（如text-embedding-3-small）
provider_key：提供商特定的键（如API密钥标识符）
hash：文本内容的哈希值
embedding：向量嵌入的序列化表示（通常为JSON字符串）
dims：嵌入维度
updated_at：更新时间戳

信息来源：

文本内容来自记忆文件的分块
向量嵌入由嵌入模型生成（如OpenAI的嵌入API）

6.1.2. 总量控制与刷新机制

总量控制：

缓存大小限制：通过配置控制（默认无硬性限制，依赖系统资源）
清理策略：定期清理过期缓存
内存使用：缓存存储在SQLite数据库中，不占用系统内存

刷新机制：

时间衰减：基于 updated_at 字段，清理长时间未使用的缓存
手动清理：提供清理命令
自动清理：系统启动或记忆同步时检查并清理过期缓存

6.1.3. 相关代码与函数

函数名	文件路径	作用
`cacheEmbedding`	`src/memory-host-sdk/engine-storage.ts`	缓存嵌入向量
`getCachedEmbedding`	`src/memory-host-sdk/engine-storage.ts`	获取缓存的嵌入向量
`cleanupEmbeddingCache`	`src/memory-host-sdk/engine-storage.ts`	清理过期的嵌入缓存
`generateEmbedding`	`src/memory-host-sdk/host/embeddings.ts`	生成嵌入向量
`buildHybridQuery`	`src/memory-host-sdk/host/internal.ts`	构建混合搜索查询

6.1.4. 核心算法

嵌入缓存算法：

计算文本哈希：使用SHA-256等哈希算法计算文本内容的哈希值
检查缓存：查询 embedding_cache 表，使用 provider、model、provider_key 和 hash 作为键
缓存命中：如果找到缓存，直接返回嵌入向量
缓存未命中：调用嵌入模型生成新的嵌入向量，然后存储到 embedding_cache 表
缓存清理：定期检查 updated_at 字段，清理过期的缓存条目

缓存清理算法：

确定过期时间：根据配置的缓存过期时间（默认可能为7-30天）
查询过期缓存：查找 updated_at 早于过期时间的记录
删除过期缓存：删除符合条件的缓存记录
优化数据库：执行VACUUM操作，回收空间

6.2. 业务流程中的使用

6.2.1. 记忆同步流程

扫描文件：扫描 memory 和 sessions 目录
文件处理：
- 对每个文件，计算哈希值
- 检查 files 表，确定是否需要更新
分块处理：
- 将文件分成适当大小的块
- 对每个块，计算哈希值
- 检查 chunks 表，确定是否需要更新
嵌入生成：
- 对需要更新的块，检查 embedding_cache 表
- 缓存命中则使用缓存的嵌入
- 缓存未命中则生成新嵌入并缓存
数据库更新：
- 更新 files 表和 chunks 表
- FTS5 自动更新 fts_chunks 表

6.2.2. 记忆检索流程

查询处理：分析用户查询
嵌入生成：
- 检查 embedding_cache 表，查找查询的嵌入
- 缓存未命中则生成新嵌入并缓存
混合搜索：
- 向量搜索：使用查询嵌入与 chunks 表中的嵌入计算相似度
- 文本搜索：使用 fts_chunks 表执行全文搜索
- 合并结果，应用权重和过滤
结果返回：返回搜索结果

7. 记忆持久化核心实现代码

数据库操作主要由 engine-storage.ts 中的函数处理，确保了数据的一致性和可靠性。触发这些操作的业务流程则根据用户交互和系统配置自动执行，形成了完整的记忆管理生命周期。

7.1. 索引更新（记忆同步）

// src/memory-host-sdk/engine-storage.ts
async function updateIndex(params: {
  files: Array<{ path: string; source: string; hash: string; mtime: number; size: number }>;
  chunks: Array<{
    id: string;
    path: string;
    source: string;
    startLine: number;
    endLine: number;
    hash: string;
    model: string;
    text: string;
    embedding: string;
  }>;
  deletedPaths: string[];
}) {
  // 开始事务
  // 处理删除的文件
  // 处理新增/修改的文件
  // 处理新增/修改的记忆块
  // 提交事务
}

7.2. 混合搜索

// src/memory-host-sdk/host/internal.ts
async function searchMemory(params: {
  query: string;
  maxResults?: number;
  minScore?: number;
  agentSessionKey?: string;
}) {
  // 生成查询向量
  // 执行向量搜索
  // 执行文本搜索
  // 合并结果
  // 排序和过滤
  // 返回结果
}

7.3. 嵌入向量缓存

// src/memory-host-sdk/engine-storage.ts
async function cacheEmbedding(params: {
  provider: string;
  model: string;
  providerKey: string;
  hash: string;
  embedding: string;
  dims?: number;
}) {
  // 检查缓存是否存在
  // 不存在则插入
  // 返回缓存结果
}

8. 总结

OpenClaw的记忆系统通过精心设计的目录结构和处理逻辑，实现了高效的记忆管理：

分层存储：从会话文件到每日记忆，再到持久记忆，形成完整的记忆层次
自动处理：通过会话压缩、梦境系统等机制，自动整理和优化记忆
高效检索：结合SQLite数据库和向量搜索，实现快速准确的记忆检索
约束控制：通过文件大小、字符数等限制，确保系统性能和安全性

这种设计既保证了记忆的有效存储和管理，又为大模型提供了丰富的上下文信息，提升了对话的连贯性和准确性。

OpenClaw的记忆系统通过文件存储和SQLite数据库的结合，实现了高效的记忆管理：

文件存储：
- 每日记忆、持久记忆、梦境报告等文件，提供直观的记忆组织
- 会话文件存储完整对话历史，支持会话管理
数据库表：
- files 表：跟踪文件信息，用于变更检测
- chunks 表：存储分块的记忆内容和向量嵌入，是核心数据
- fts_chunks 表：提供全文搜索能力
- meta 表：存储数据库元数据
- embedding_cache 表：缓存向量嵌入，提升性能
缓存机制：
- embedding_cache 表缓存向量嵌入，避免重复计算
- 基于哈希值和时间戳的缓存管理
- 定期清理过期缓存，控制存储使用