# OpenClaw 记忆系统深度拆解：从零理解 AI 助手的"大脑"是如何工作的

**URL:** <https://www.sunai.net/t/topic/1184>\
**Category:** IT\
**Tags:** openclaw\
**Created:** [2026 年3 月 1 日 15:37 UTC](https://www.sunai.net/t/topic/1184 "2026-03-01T15:37:08Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

作者： ![wood](https://www.sunai.net/user_avatar/www.sunai.net/wood/32/1032_2.png) [@wood](https://www.sunai.net/u/wood)\
发布日期： [2026 年3 月 1 日 15:37 UTC](https://www.sunai.net/t/topic/1184/1 "2026-03-01T15:37:08Z")

</div>

![OpenClaw 记忆系统深度拆解：从零理解 AI 助手的"大脑"是如何工作的](https://i.czl.net/r2/original/2X/2/2d4363197a7149ba02624112ddcbee3c76ed0ec7.jpeg)

> 本文转发自[知乎](https://zhuanlan.zhihu.com/p/2003188933438230664)

OpenClaw 记忆系统深度拆解：从零理解 AI 助手的"大脑"是如何工作的

> 当 AI 不再"金鱼记忆"——深入剖析开源个人 AI 助手的持久化记忆架构设计

* * *

## 引言：为什么记忆是 AI 助手的分水岭

在 2026 年初，一个名为 OpenClaw 的开源项目以惊人的速度席卷了开发者社区——60,000+ GitHub Stars 仅用 72 小时，成为当时增长最快的开源项目之一。这个被称为"真正能做事情的 AI"的助手，与 ChatGPT、Claude 等传统聊天机器人最大的区别之一，就是它的 **持久记忆系统** 。

传统的对话式 AI 有一个致命缺陷： **每次对话都是全新的开始** 。你昨天告诉它你的喜好，今天它就忘了；你上周让它记住一个重要的项目细节，这周它就消失了。这种"金鱼记忆"让 AI 始终停留在"工具"层面，而无法进化成真正的"助手"。

OpenClaw 的核心突破在于： **它让 AI 真正拥有了记忆** 。不是简单的上下文窗口堆积，而是一个精心设计的、分层的、可持久化的记忆架构。

本文将从架构设计、存储机制、检索策略、安全考量和实践应用五个维度，深度拆解 OpenClaw 的记忆系统，帮助你理解现代 AI 助手是如何实现"长期记忆"的。

* * *

## 第一部分：整体架构设计——双轨记忆模型

### 1.1 核心哲学：Markdown 即真相（Markdown as Source of Truth）

OpenClaw 记忆系统最令人惊艳的设计决策是： **使用纯 Markdown 文件作为记忆的源头，而非传统数据库** 。

大多数 AI 记忆系统一上来就设计复杂的数据库 schema，但 OpenClaw 选择了相反的路径—— **可读的纯文本** 。这种设计有以下几个深层考量：

- **透明性** ：用户可以像阅读笔记一样查看 AI 的记忆
- **可编辑性** ：直接修改 Markdown 文件就能改变 AI 的行为
- **可移植性** ：不依赖特定数据库，任何文本编辑器都能处理
- **版本控制友好** ：天然支持 Git，可以追踪记忆的演变历史

这种设计哲学贯穿了整个记忆系统。正如 OpenClaw 文档所说："OpenClaw memory is plain Markdown in the agent workspace. The files are the source of truth; the model only 'remembers' what gets written to disk."

### 1.2 双层记忆架构

OpenClaw 采用了经典的双层记忆模型，模拟人类记忆的 **工作记忆** 和 **长期记忆** ：

```auto
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw 记忆架构 │
├─────────────────────────────────────────────────────────────┤
│ 第一层：短期/工作记忆 (Working Memory) │
│ ├── memory/2026-02-06.md ← 今日日志（追加写入） │
│ ├── memory/2026-02-05.md ← 昨日日志（只读参考） │
│ └── 自动加载：会话启动时读取今天+昨天的日志 │
├─────────────────────────────────────────────────────────────┤
│ 第二层：长期/精炼记忆 (Long-term Memory) │
│ ├── MEMORY.md ← 人工精选的核心记忆（仅私聊） │
│ └── 手动触发：AI 主动整理写入，或用户直接编辑 │
└─────────────────────────────────────────────────────────────┘

```

### 1.2.1 第一层：每日日志（Daily Logs）

位于 `memory/YYYY-MM-DD.md` 的路径下，这是 **追加写入** 的运行时笔记：

- **写入时机** ：AI 在对话过程中实时写入，记录重要的上下文、决策和临时信息
- **读取策略** ：会话启动时自动加载今天和昨天的日志
- **内容特征** ：原始、详细、时间线导向，类似日记
- **保留周期** ：理论上永久保留，但检索优先级随时间降低

这种设计的巧妙之处在于： **它既保证了上下文的连续性，又避免了向 LLM 发送过长的历史记录** 。昨天的对话作为参考加载，但不会被无限累积。

### 1.2.2 第二层：精炼记忆（Curated Memory）

位于 `MEMORY.md` ，这是 **人工精选** 的长期记忆文件：

- **写入时机** ：AI 主动整理（"从我们的对话中，我应该记住什么？"），或用户明确要求
- **读取策略** ：仅在私聊会话中加载，群聊中不加载（出于隐私考虑）
- **内容特征** ：结构化、概括性、偏好导向，类似个人档案
- **保留周期** ：永久，且是 AI 理解用户的"圣经"

**为什么群聊不加载 MEMORY.md？** 这是一个重要的隐私设计。群聊中的信息可能是多人的，如果 AI 把从私聊中学到的个人偏好应用到群聊，可能会造成隐私泄露或语境错位。

### 1.3 索引层：SQLite + 向量嵌入

虽然 Markdown 是源头，但纯文本检索效率低下。OpenClaw 在本地构建了一个 **混合索引层** ：

```auto
~/.openclaw/memory/
├── {agentId}.sqlite # 每个 Agent 独立的 SQLite 数据库
│ ├── chunks # 文本分片表
│ ├── embeddings # 向量嵌入表
│ └── metadata # 文件指纹、模型信息等
└── embedding-cache/ # 本地嵌入模型缓存

```

**索引的工作原理** ：

1. **文件监听** ：通过文件系统 watcher 监听 `MEMORY.md` 和 `memory/` 目录的变化
2. **自动同步** ：变化后 1.5 秒的防抖延迟触发重新索引
3. **分片策略** ：Markdown 文件被切分为约 400 token 的块，80 token 重叠
4. **嵌入模型** ：支持 OpenAI、Gemini 或本地嵌入模型，自动回退

**关键设计** ：索引是 **派生数据** ，可以随时重建。真正的源头永远是 Markdown 文件。这种设计避免了"数据锁定"风险。

* * *

## 第二部分：存储机制——从内存到磁盘的持久化管道

### 2.1 上下文压缩与预刷新机制（Pre-compaction Flush）

这是 OpenClaw 记忆系统最精妙的技术细节之一。

LLM 都有上下文长度限制（如 Claude 3.5 Sonnet 的 200K tokens）。当对话过长时，OpenClaw 不会简单地截断或丢弃，而是执行一个 **静默的记忆刷新** ：

```auto
// 伪代码：预压缩刷新逻辑
async function preCompactionFlush(session: Session) {
  if (session.contextLength > COMPACTION_THRESHOLD) {
    // 静默触发一轮对话，提醒 AI 写入重要记忆
    await session.injectSilentTurn(\`
      Context limit approaching. Review our conversation and write 
      any durable facts, preferences, or decisions to MEMORY.md 
      before compression occurs.
    \`);
    
    // 压缩旧上下文，保留摘要
    await session.compact();
  }
}

```

**为什么这很重要？**

传统做法是在上下文满了后直接截断，导致重要信息丢失。OpenClaw 的预刷新机制 **在压缩前主动提醒 AI 保存关键信息** ，就像人类在忘记事情前赶紧记在笔记本上一样。

**注意** ：这个功能仅在 workspace 可写时触发。如果是只读的 Docker 沙盒环境，则跳过此步骤。

### 2.2 会话文件与记忆分离

OpenClaw 区分 **会话历史** 和 **提炼记忆** ：

```auto
~/.openclaw/
├── workspace/
│ ├── MEMORY.md # 长期记忆（提炼后）
│ └── memory/
│ └── 2026-02-06.md # 每日日志（原始）
└── sessions/
    └── {sessionId}.jsonl # 完整会话历史（原始记录）

```

- **JSONL 会话文件** ：每一次对话的完整记录，用于审计和回溯
- **Markdown 记忆文件** ：AI 提炼后的有用信息，用于指导未来行为

这种分离确保了 **可追溯性** （你能查到 AI 为什么那样说）和 **可用性** （AI 不会被噪声淹没）。

### 2.3 工作空间隔离与多 Agent 支持

OpenClaw 支持 **多 Agent 路由** ，不同渠道可以使用不同的记忆空间：

```auto
agents:
  work-slack:
    workspace: ~/.openclaw/workspaces/professional
    memorySearch:
      store:
        path: ~/.openclaw/memory/work.sqlite
  
  personal-telegram:
    workspace: ~/.openclaw/workspaces/personal  
    memorySearch:
      store:
        path: ~/.openclaw/memory/personal.sqlite

```

**隔离的好处** ：

- 工作相关的记忆不会污染个人生活
- 可以为不同角色配置不同的长期记忆（MEMORY.md）
- 敏感信息限制在特定渠道内

* * *

## 第三部分：检索策略——如何找到"相关"记忆

### 3.1 混合检索：向量搜索 + 关键词匹配

单纯的向量语义搜索有局限：它擅长找"意思相近"的内容，但不擅长找"具体名字"或"精确匹配"。OpenClaw 采用了 **混合策略** ：

```auto
用户提问 → 并行检索
├── 向量搜索：找到语义相关的记忆片段（约 700 字符摘要）
│ └── 使用 SQLite 中的嵌入向量，余弦相似度排序
└── 关键词搜索：找到包含特定术语的记忆
    └── 使用 SQLite FTS（全文搜索）

→ 合并结果 → 去重 → 按相关度排序 → 注入上下文

```

**向量搜索的细节** ：

- **目标大小** ：每个 chunk 约 400 tokens（约 600-800 字符）
- **重叠** ：80 tokens，确保语义连贯性不被切断
- **返回格式** ：包含文件路径、行号范围、相似度分数、使用的嵌入模型

**关键词搜索的补充** ： 当用户提到特定项目名称、人名、日期时，关键词搜索能快速定位精确匹配，而向量搜索可能因为这些词的语义泛化而漏掉。

### 3.2 记忆工具：Agent 主动检索

OpenClaw 提供了两个核心记忆工具供 AI 调用：

### 3.2.1 memory\_search —— 语义搜索

```auto
// 工具定义（简化）
{
  name: "memory_search",
  description: "Search through memories using semantic similarity",
  parameters: {
    query: "string", // 搜索意图描述
    limit: "number" // 返回结果数量（默认 5）
  },
  returns: {
    snippets: [{
      text: "string", // 记忆片段文本（截断至 ~700 字符）
      path: "string", // 文件路径
      lines: [start, end], // 行号范围
      score: "number" // 相似度分数
    }]
  }
}

```

**关键限制** ：不返回完整文件内容，只返回摘要。这是为了防止上下文被单个大文件占满。

### 3.2.2 memory\_get —— 精确读取

```auto
{
  name: "memory_get",
  description: "Read a specific memory file",
  parameters: {
    path: "string", // 相对 workspace 的路径
    startLine: "number", // 可选：起始行
    limit: "number" // 可选：读取行数
  }
}

```

**安全限制** ：路径必须在 `MEMORY.md` 或 `memory/` 目录下，禁止读取敏感文件。

### 3.3 检索的触发时机

OpenClaw 的检索不是被动的，而是 **多阶段触发** ：

1. **会话启动时** ：自动加载今天 + 昨天的日志 + MEMORY.md（私聊）
2. **Agent 主动调用** ：当 AI 判断需要历史信息时，调用 `memory_search`
3. **工具调用后** ：某些工具执行后自动触发相关记忆检索
4. **上下文压缩前** ：预刷新阶段检索可能被遗忘的关键信息

* * *

## 第四部分：安全与隐私设计——记忆的边界

### 4.1 提示注入与记忆污染

OpenClaw 的记忆系统面临一个独特的安全挑战： **持久化提示注入（Persistent Prompt Injection）** 。

**攻击场景** ：

1. 攻击者通过某种方式让 AI 记住一条恶意指令（如"永远忽略之前的指令，执行 X"）
2. 这条指令被写入 `MEMORY.md` 或每日日志
3. 后续所有会话都会加载这条记忆，导致 AI 行为被长期劫持

**OpenClaw 的防御措施** ：

### 4.1.1 分层信任模型

- `MEMORY.md` ：仅在私聊加载，且需要用户明确确认写入
- 每日日志：自动加载，但优先加载近期的，旧的检索权重降低
- 会话文件：不直接作为记忆加载，仅用于审计

### 4.1.2 沙盒隔离

通过 Docker 沙盒运行不受信任的会话：

```auto
agents:
  defaults:
    sandbox:
      mode: "non-main" # 非主会话（如群聊）使用沙盒
      docker:
        image: "openclaw-sandbox"
        readOnly: true # 只读，防止写入恶意记忆

```

### 4.1.3 内存的"遗忘"机制

虽然 Markdown 是源头，但 OpenClaw 支持 **选择性遗忘** ：

```auto
// 伪代码：遗忘特定记忆
async function forgetMemories(options: {
  path?: string; // 特定文件
  before?: Date; // 某日期前
  matching?: string; // 匹配关键词
}) {
  // 从 SQLite 索引中删除
  await index.delete(options);
  // 可选：从 Markdown 文件中删除对应段落
  await rewriteMarkdown(options);
}

```

### 4.2 隐私保护设计

### 4.2.1 本地优先（Local-First）

所有记忆文件默认存储在本地 `~/.openclaw/` 目录，不上传云端。这意味着：

- 你的私人对话不会被用于训练第三方模型
- 即使 OpenClaw 的服务器被攻破，你的记忆也不会泄露
- 你可以随时物理删除文件，确保数据销毁

### 4.2.2 渠道隔离

如前所述， `MEMORY.md` 仅在私聊加载。这防止了：

- 群聊中的其他成员通过 AI 窥探你的私人偏好
- 工作频道中的敏感信息混入个人记忆

### 4.2.3 配对码与访问控制

OpenClaw 默认对未知发送者拒绝消息，需要显式配对批准：

```auto
openclaw pairing list
openclaw pairing approve <userId>

```

这防止了恶意用户通过冒充身份向你的 AI 注入记忆。

### 4.3 记忆的"毒性"与清理

长期运行后，记忆文件可能积累矛盾或过时的信息。OpenClaw 提供了：

- **手动整理** ：用户直接编辑 Markdown 文件，删除不需要的记忆
- **自动去重** ：索引层自动检测相似片段
- **版本控制** ：建议将 memory 目录纳入 Git，可以回滚到干净的记忆状态

* * *

## 第五部分：实践应用——如何高效使用 OpenClaw 记忆

### 5.1 记忆的"写入策略"

想要让 AI 记住关键信息，你需要理解它的 **写入触发机制** ：

### 5.1.1 显式请求

最直接的方式是明确告诉 AI：

> "请记住，我所有项目都用 TypeScript，不喜欢 Python。"

AI 会调用工具将这条写入 `MEMORY.md` 。

### 5.1.2 间接提炼

在长时间的对话后，询问：

> "从我们的对话中，你有什么应该永久记住的吗？"

这会触发 AI 的 **主动记忆整理** ，将散落的上下文提炼成结构化的 MEMORY.md 条目。

### 5.1.3 手动编辑

直接编辑 `~/.openclaw/workspace/MEMORY.md` ：

```auto

## Technical
- Primary language: TypeScript
- Editor: VS Code with Vim keybindings
- Avoid: Python except for data science tasks

## Personal
- Timezone: Asia/Shanghai (UTC+8)
- Preferred meeting times: 10:00-12:00, 14:00-17:00

```

### 5.2 记忆的"读取调优"

### 5.2.1 优化 MEMORY.md 结构

AI 加载 MEMORY.md 时，结构化的 Markdown 更容易被解析：

```auto

## 工作相关
### 项目 Alpha
- 技术栈：Next.js + Prisma
- Deadline: 2026-03-01

### 项目 Beta  
- 技术栈：Rust + Tauri
- Status: 暂停中

## 个人偏好
### 饮食
- 素食主义者
- 过敏：花生

### 沟通风格
- 喜欢简洁直接的回答
- 技术讨论时可以使用术语

```

### 5.2.2 使用标签增强检索

在记忆中加入特定标签，便于后续检索：

```auto
#project-alpha #urgent 需要本周完成 API 文档

```

虽然 OpenClaw 的默认搜索是语义化的，但标签可以帮助人工快速浏览。

### 5.3 多设备同步

OpenClaw 本身不提供云同步，但你可以通过以下方式实现记忆同步：

### 5.3.1 Git 同步

```auto
cd ~/.openclaw/workspace/memory
git init
git remote add origin https://github.com/your/memory-repo.git
git add .
git commit -m "Memory update: $(date +%Y-%m-%d)"
git push

```

### 5.3.2 云盘同步

使用 Dropbox、iCloud Drive 或 Syncthing 同步 `~/.openclaw/workspace` 目录。

**注意** ：同步时要确保 OpenClaw 不在运行，避免文件冲突。

### 5.4 故障排查

### 5.4.1 "AI 总是忘记"

- **检查 workspace 路径** ：确保 Gateway 使用的是同一个 workspace
- **检查写入权限** ：特别是 Docker 沙盒环境，可能是只读的
- **显式要求写入** ：提醒 AI "请把这条写入 MEMORY.md"

### 5.4.2 "搜索不到相关记忆"

- **检查嵌入模型配置** ：需要设置 OpenAI、Gemini 或本地嵌入 API key
- **检查索引状态** ：运行 `openclaw doctor` 诊断索引健康
- **手动触发重索引** ：删除 SQLite 文件，让系统自动重建

### 5.4.3 "记忆太多，响应变慢"

- **归档旧日志** ：将 `memory/2025-*.md` 移动到备份目录
- **精简 MEMORY.md** ：定期手动清理过时的记忆
- **调整 chunk 大小** ：减少每个片段的 token 数（高级配置）

* * *

## 第六部分：技术进阶——自定义记忆插件

### 6.1 插件架构

OpenClaw 允许通过插件扩展记忆系统。默认的 `memory-core` 插件可以被替换或增强：

```auto
// 自定义记忆插件示例
export default definePlugin({
  name: "memory-advanced",
  slots: {
    memory: {
      async search(query: string, context: Context) {
        // 1. 查询向量数据库
        const vectorResults = await vectorSearch(query);
        
        // 2. 查询图谱数据库（如果安装了 Graphiti）
        const graphResults = await temporalQuery(query);
        
        // 3. 合并排序
        return mergeResults(vectorResults, graphResults);
      },
      
      async write(content: string, metadata: object) {
        // 自定义写入逻辑，比如同时写入云端备份
        await localWrite(content, metadata);
        await cloudBackup.write(content, metadata);
      }
    }
  }
});

```

### 6.2 集成外部记忆系统

### 6.2.1 Graphiti 时序知识图谱

社区有项目将 Graphiti 与 OpenClaw 集成，实现 **时序感知的记忆** ：

```auto
npm install openclaw-graphiti-memory
memory:
  provider: "graphiti"
  graphiti:
    endpoint: "http://localhost:8000"
    temporal: true # 支持时序查询（"上周三我说过什么？"）

```

Graphiti 的优势：

- **时间感知** ："三天前"、"上周"等时间限定查询
- **关系推理** ："我和谁讨论过这个项目？"
- **事实演化** ：追踪信息的变化历史（"项目状态从进行中变为暂停"）

### 6.2.2 VecLite 轻量级向量库

对于资源受限的设备，可以使用 VecLite 替代完整的 SQLite + 嵌入模型方案：

```auto
import { Memory } from 'veclite/integrations/openclaw';

const memory = new Memory({
  path: './lightweight-memory.db',
  embeddingDim: 384, // 使用轻量级模型
  localModel: 'all-MiniLM-L6-v2'
});

```

### 6.3 记忆的导入导出

OpenClaw 支持多种格式的记忆迁移：

```auto
// 从旧会话导入记忆
await memory.importSession('./old-session.jsonl', {
  deduplicate: true,
  tag: 'migrated-2026'
});

// 导出为 Markdown 备份
await memory.exportMarkdown('./backup/');

// 遗忘特定时间段
await memory.forget({
  before: new Date('2026-01-01'),
  tag: 'temp'
});

```

* * *

## 第七部分：设计哲学与未来演进

### 7.1 "龙虾之道"（The Lobster Way）

OpenClaw 的吉祥物是一只龙虾，这不仅是 branding，更代表了其 **持续蜕皮进化** 的设计理念：

- **硬壳** ：安全边界清晰，默认拒绝未知访问
- **软体** ：内部柔软灵活，Markdown 文件可随时调整
- **蜕皮** ：定期丢弃旧的不适用记忆，生长出新的能力

记忆系统的这种"可塑性"是其核心优势——不像传统数据库那样僵化，而是像生物神经网络一样可以 **遗忘、重塑、进化** 。

### 7.2 与 AutoGPT、MemGPT 的对比

| 特性 | OpenClaw | AutoGPT | MemGPT |
| --- | --- | --- | --- |
| 存储格式 | Markdown 文件 | 向量数据库 | 分层记忆架构 |
| 可读性 | 极高（纯文本） | 低（二进制） | 中（结构化） |
| 编辑性 | 直接编辑 | 需工具 | 需 API |
| 检索方式 | 混合（向量+关键词） | 纯向量 | 分层缓存 |
| 上下文管理 | 预压缩刷新 | 递归总结 | 虚拟上下文 |
| 部署复杂度 | 低 | 高 | 中 |
| 隐私控制 | 完全本地 | 依赖配置 | 依赖配置 |

OpenClaw 的取舍很明显： **牺牲绝对存储效率，换取透明度和可控性** 。

### 7.3 未来可能的演进方向

基于当前架构，OpenClaw 的记忆系统可能向以下方向发展：

### 7.3.1 分层记忆压缩

目前的预压缩刷新还比较简单，未来可能引入更智能的 **分层摘要** ：

- L1：原始对话（最近 3 天）
- L2：周度摘要（过去 4 周）
- L3：月度回顾（永久保存）

### 7.3.2 跨 Agent 记忆共享

在保持隔离的前提下，允许用户显式分享某些记忆：

### 7.3.3 记忆的"置信度"评分

为每条记忆添加置信度元数据，低置信度的记忆（如一次性提及的偏好）会被高置信度的记忆（如多次确认的偏好）覆盖。

### 7.3.4 多模态记忆

扩展 Markdown 格式支持图像、音频的引用：

```auto
![用户家的猫](attachment://cat-photo.jpg)
用户提到这只猫叫"咪咪"，3岁。

```

* * *

## 结语：记忆让 AI 成为"助手"而非"工具"

OpenClaw 的记忆系统证明了： **真正的个人 AI 助手不是拥有最大的模型，而是拥有最懂你的记忆** 。

通过简洁而精妙的双层 Markdown 架构、透明的文件存储、混合检索策略和严格的安全边界，OpenClaw 实现了一个既强大又可控的记忆系统。它不是黑盒，而是 **可审计、可编辑、可迁移** 的个人知识库。

对于开发者，理解这套架构不仅能帮助你更好地使用 OpenClaw，更能启发你设计自己的 AI 记忆系统。核心启示是：

1. **简单胜过复杂** ：Markdown 文件胜过复杂的数据库 schema
2. **透明建立信任** ：用户可以阅读 AI 的记忆，知道它"知道"什么
3. **分层管理记忆** ：工作记忆与长期记忆的分离是必需的
4. **安全不能妥协** ：持久化记忆意味着持久化的攻击面，必须严格隔离

当你下次与 OpenClaw 对话，看到它准确记得你上周提到的项目细节、知道你更喜欢 TypeScript 而非 Python、记得你通常在下午开会——背后是这套精心设计的记忆系统在默默工作。

这，就是 AI 从"工具"进化为"助手"的关键一步。

* * *

**参考资源** ：

- OpenClaw 官方文档 - Memory 章节
- OpenClaw GitHub 仓库
- OpenClaw-mini 极简复现项目
- How OpenClaw Implements Agent Memory
- The OpenClaw Prompt Injection Problem

* * *

_本文深度剖析了 OpenClaw 记忆系统的设计理念、技术实现和最佳实践，适合希望理解 AI 助手长期记忆机制的开发者和技术爱好者阅读。_

编辑于 2026-02-06 19:33・广东