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

IT
1

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

本文转发自知乎

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 采用了经典的双层记忆模型，模拟人类记忆的 工作记忆 和 长期记忆 ：

┌─────────────────────────────────────────────────────────────┐
│                    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 在本地构建了一个 混合索引层 ：

~/.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 不会简单地截断或丢弃，而是执行一个 静默的记忆刷新 ：

// 伪代码：预压缩刷新逻辑
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 区分 会话历史 和 提炼记忆 ：

~/.openclaw/
├── workspace/
│   ├── MEMORY.md              # 长期记忆（提炼后）
│   └── memory/
│       └── 2026-02-06.md      # 每日日志（原始）
└── sessions/
    └── {sessionId}.jsonl      # 完整会话历史（原始记录）
  • JSONL 会话文件 ：每一次对话的完整记录，用于审计和回溯
  • Markdown 记忆文件 ：AI 提炼后的有用信息，用于指导未来行为

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

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

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

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 采用了 混合策略 ：

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

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

向量搜索的细节 ：

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

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

3.2 记忆工具：Agent 主动检索

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

3.2.1 memory_search —— 语义搜索

// 工具定义（简化）
{
  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 —— 精确读取

{
  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 沙盒运行不受信任的会话：

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

4.1.3 内存的"遗忘"机制

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

// 伪代码：遗忘特定记忆
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 默认对未知发送者拒绝消息，需要显式配对批准：

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 ：


## 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 更容易被解析：


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

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

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

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

5.2.2 使用标签增强检索

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

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

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

5.3 多设备同步

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

5.3.1 Git 同步

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 插件可以被替换或增强：

// 自定义记忆插件示例
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 集成，实现 时序感知的记忆 ：

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

Graphiti 的优势：

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

6.2.2 VecLite 轻量级向量库

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

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

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

6.3 记忆的导入导出

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

// 从旧会话导入记忆
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 格式支持图像、音频的引用：

![用户家的猫](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・广东