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. 记忆文件类型与关系

1.5. 文件处理逻辑关系

1.5.1. 核心处理流程

1.5.2. 详细处理逻辑

1. 会话文件 → 每日记忆文件

   • 触发：会话结束或达到压缩阈值
   • 处理：compactEmbeddedPiSessionDirect 函数生成会话摘要，保存到 memory/YYYY-MM-DD.md
   • 代码：src/agents/compaction.ts

2. 每日记忆文件 → 梦境阶段报告

   • 触发：定时执行或手动触发梦境系统
   • 处理：
     • Light阶段：整理排序短期记忆 → runLightDreaming
     • REM阶段：反思发现主题模式 → runRemDreaming
     • Deep阶段：提升持久记忆 → runDeepDreaming
   • 代码：extensions/memory-core/src/dreaming/

3. 梦境阶段报告 → 持久记忆文件

   • 触发：Deep阶段执行完成
   • 处理：将重要信息从每日记忆提升到 MEMORY.md
   • 代码：extensions/memory-core/src/dreaming/deep.ts

4. 所有记忆文件 → SQLite数据库

   • 触发：记忆同步（会话开始、搜索时、定时）
   • 处理：updateIndex 函数将文件分块、生成向量嵌入、更新数据库
   • 代码：src/memory-host-sdk/engine-storage.ts

5. SQLite数据库 → 大模型提示词

   • 触发：用户查询或会话开始
   • 处理：searchMemory 函数检索相关记忆，生成提示词
   • 代码：src/memory-host-sdk/host/internal.ts

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

1.7. 业务触发流程

1.7.1. 会话文件生成与更新

触发条件：

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

流程：

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

1.7.2. 每日记忆文件生成

触发条件：

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

流程：

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

1.7.3. 梦境系统执行

触发条件：

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

流程：

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

1.7.4. 记忆同步

触发条件：

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

流程：

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

1.7.5. 记忆检索

触发条件：

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

流程：

1. 分析查询或上下文需求
2. 执行混合搜索（向量+文本）
3. 过滤和排序结果
4. 格式化结果为提示词
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. 数据库结构

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. 详细映射

1. 文件到 files 表：

   • 每个记忆文件对应 files 表中的一条记录
   • 存储文件路径、来源、哈希、修改时间、大小
   • 用于变更检测和文件管理

2. 文件到 chunks 表：

   • 每个文件被分成多个记忆块，每个块对应 chunks 表中的一条记录
   • 存储块ID、文件路径、来源、行范围、哈希、模型、文本内容、向量嵌入
   • 是记忆检索的核心数据

3. chunks 表到 fts_chunks 表：

   • fts_chunks 是 FTS5 虚拟表，自动同步 chunks 表的文本内容
   • 用于全文搜索功能

4. chunks 表到 embedding_cache 表：

   • 当生成向量嵌入时，会检查 embedding_cache 表是否存在缓存
   • 缓存命中则直接使用，否则生成新嵌入并缓存

4. 记忆存储操作

4.1. 读取操作

4.2. 更新操作

4.3. 删除操作

5. 触发操作的业务流程

5.1. 记忆同步流程

触发条件：

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

流程：

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

5.2. 记忆搜索流程

触发条件：

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

流程：

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

5.3. 记忆压缩流程

触发条件：

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

流程：

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

5.4. 梦境系统流程

触发条件：

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

流程：

1. Light 阶段：整理短期记忆
2. REM 阶段：发现主题模式
3. Deep 阶段：提升持久记忆到 MEMORY.md
4. 触发记忆同步，更新数据库
5. 生成 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. 相关代码与函数

6.1.4. 核心算法

嵌入缓存算法：

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

缓存清理算法：

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

6.2. 业务流程中的使用

6.2.1. 记忆同步流程

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

6.2.2. 记忆检索流程

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

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的记忆系统通过精心设计的目录结构和处理逻辑，实现了高效的记忆管理：

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

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

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

1. 文件存储：

   • 每日记忆、持久记忆、梦境报告等文件，提供直观的记忆组织
   • 会话文件存储完整对话历史，支持会话管理

2. 数据库表：

   • files 表：跟踪文件信息，用于变更检测
   • chunks 表：存储分块的记忆内容和向量嵌入，是核心数据
   • fts_chunks 表：提供全文搜索能力
   • meta 表：存储数据库元数据
   • embedding_cache 表：缓存向量嵌入，提升性能

3. 缓存机制：

   • embedding_cache 表缓存向量嵌入，避免重复计算
   • 基于哈希值和时间戳的缓存管理
   • 定期清理过期缓存，控制存储使用

这种设计既保证了记忆的持久化存储，又通过数据库索引和缓存机制提升了检索性能，为大模型提供了丰富的上下文信息。