Memory Architecture

OpenClaw 记忆系统架构

基于文件化记忆 + 可扩展检索的混合架构，与 Claude Code 有本质区别。OpenClaw 采用了更像传统 RAG 的检索增强方案。

Architecture

核心设计理念

OpenClaw 的记忆系统与 Claude Code 最根本的区别：不是「把所有文件拼接到上下文」，而是「按需检索相关记忆」。

L1
📋
文件化记忆 (File-Based)记忆存在 .openclaw/memory/ 目录中

        所有记忆都是 Markdown 文件。Claude Code 的 auto-memory 是一个索引文件指向多个主题，但 OpenClaw 则是更纯粹的「文件 + 检索」模式。
      

        memory/
        *.md
        YAML 元数据
      
L2
🔍
混合检索 (Hybrid Search)BM25 关键词 + 向量语义双通道

        不是整文件拼接，而是检索最相关的记忆片段。BM25 处理精确关键词匹配，向量处理语义相似性，两者分数加权合并。
      

        BM25
        Embedding
        Reranker
      
L3
📈
时间衰减 (Time Decay)指数衰减模型，越老越容易被遗忘

        每条记忆都有时间戳和访问次数权重。长时间未被访问的记忆分数自动衰减，类似于人类记忆的艾宾浩斯遗忘曲线。
      

        指数衰减
        访问权重
        新鲜度
      
L4
⚙️
工作区配置 (Workspace Config)SOUL.md / AGENTS.md / POLICY.md

        除记忆外，OpenClaw 还有一套独立的配置文件体系：定义 Agent 角色、行为策略、用户信息。这与 Claude Code 的 CLAUDE.md 定位类似但更细分。
      

        SOUL.md
        AGENTS.md
        POLICY.md
      

File Structure

文件目录结构

OpenClaw 的记忆和工作区配置完全基于文件系统。以下是典型的项目结构：

📁 OpenClaw 项目文件结构

▶ 项目根目录

├── .openclaw/ # OpenClaw 专属配置目录

▶ .openclaw/memory/

├── memory.md # 中央记忆文件（所有记忆的容器）

├── user.md # 用户偏好记忆

├── project.md # 项目上下文记忆

├── session/ # 本次会话记忆

│ └── *.md # 会话级记忆片段

└── .index/ # 检索索引（BM25 + 向量）

├── bm25.json # BM25 倒排索引

└── vectors/ # 向量嵌入存储

▶ .openclaw/workspace/

├── SOUL.md # Agent 灵魂定义（角色、性格、语气）

├── AGENTS.md # Agent 行为规范

├── USER.md # 用户信息

├── POLICY.md # 安全和操作策略

└── PROJECT.md # 项目配置

▶ 全局配置 (~/.openclaw/)

├── SOUL.md # 全局 Agent 灵魂

├── memory/ # 全局记忆

└── config.toml # 全局配置

Retrieval

混合检索流程

当用户发起请求时，OpenClaw 会经历以下检索流程，找到最相关的记忆片段：

1
查询解析 Query Understanding将用户的自然语言查询转换为检索向量和关键词集合。同时提取实体、时间、意图等元信息。
2
BM25 关键词检索在 .openclaw/memory/ 目录中对所有 Markdown 文件进行倒排索引匹配。找出包含精确关键词的记忆片段。
3
向量语义检索将查询向量与存储的 embedding 进行余弦相似度计算。找出语义上最相关但可能不包含精确关键词的记忆。
4
分数加权融合将 BM25 分数和向量相似度分数按权重合并。权重可配置，通常语义权重略高。融合后得到最终排序列表。
5
时间衰减加权每条记忆有指数衰减的权重。decay_rate 通常设为 0.95^t（t = 天数）。同时考虑访问频率boost。
6
Rerank 精排用交叉编码器对 Top-K 候选记忆重新评分，确保真正相关的内容排在最前面。输出最相关的 N 条记忆片段。
7
注入上下文将检索到的记忆片段插入到 prompt 的专用区域。记忆是「片段级」注入，而非整文件注入。

Comparison

OpenClaw vs Claude Code

两者记忆系统的核心差异：

维度

OpenClaw

Claude Code

架构模式

RAG 检索增强

文件拼接注入

加载方式

按需检索片段

启动时全量加载

上下文影响

记忆数量不影响

积累会占满上下文

检索机制

BM25 + 向量 + Rerank

无检索，直接读取

遗忘机制

指数时间衰减

需手动清理

配置分离

SOUL/AGENTS/POLICY 分离

统一 CLAUDE.md

记忆持久化

文件 + 独立索引

纯文件

规模化场景

大规模知识库友好

中小型项目更优

配置复杂度

较高（多文件体系）

较低（集中管理）

Content Examples

记忆文件内容示例

OpenClaw 的记忆文件都包含 YAML front-matter 元数据，这是检索的基础：

📄 memory/user.md

---
type: user_preference
created: 2025-11-15
updated: 2026-05-07
tags: [偏好, 编码风格, 工具]
access_count: 24
---

# 用户偏好

## 编码风格
- 喜欢使用 TypeScript
- 代码格式偏好 Prettier
- 注释风格：重要决策必须写注释

## 技术栈
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 测试：Jest

## 沟通偏好
- 喜欢先看架构图再动手
- 讨厌长篇大论的解释
- 期望代码提交附带变更说明

📄 memory/project.md

---
type: project_context
created: 2025-10-20
updated: 2026-05-06
tags: [项目, 架构, 待办]
access_count: 31
---

# 项目上下文

## 项目概述
电商后端 API 服务，采用微服务架构。

## 当前阶段
正在进行 支付模块重构，目标：
- 解耦支付网关
- 添加支付幂等性
- 完善退款流程

## 技术债务
- [ ] 旧订单服务无事务日志
- [ ] 缓存策略不一致
- [ ] 部分 API 缺少鉴权

## 最近决策
- 2026-05-06: 决定使用 Temporal 做工作流编排
- 2026-04-28: 放弃 Kafka，改用 Redis Streams

💡 核心区别总结

Claude Code = 把所有记忆文件拼接到上下文（像发一叠纸质材料）
OpenClaw = 把记忆存到可检索知识库，按需查询（像用搜索引擎找资料）

OpenClaw 的方案更接近 RAG（检索增强生成），适合记忆量大或知识库丰富的场景。Claude Code 的方案更简单直接，适合中小型项目。

4
层记忆体系
Session → Project → User → Global
2+1
检索通道
BM25 + 向量 + Rerank
e^(-λt)
指数时间衰减
记忆自动老化

OpenClaw Memory System · 2026