在 AI Agent 时代，记忆（Memory） 已成为决定智能体能力上限的关键要素。一个没有记忆的 AI 就像患有顺行性遗忘症的人——每次对话都是从零开始，无法积累经验、无法学习偏好、无法完成需要长期上下文的复杂任务。

本课程将以 OpenClaw（原名 Clawdbot，后更名为 Moltbot，现定名为 OpenClaw）为核心案例，深入剖析 AI Agent 记忆系统的架构设计、实现原理、以及我们在实际项目中遇到的工程挑战与解决方案。

💡 为什么选择 OpenClaw？

OpenClaw 被称为 "Claude with hands"——它不仅能思考，还拥有持久记忆，并能通过 iMessage、WhatsApp、Telegram、Slack、Discord 等多种平台进行实时对话。它在 GitHub 上获得了超过 100,000 颗星，是开源历史上增长最快的项目之一（72 小时内获得 60,000+ 星），由著名开发者 Peter Steinberger（@steipete）创建。Steinberger 是 PSPDFKit 的创始人，该公司已被 Insight Partners 收购。

一、AI Agent 记忆系统的理论基础

1.1 为什么传统分类法已不够用？

根据 2025 年 12 月发表的权威综述论文 "Memory in the Age of AI Agents"（登顶 Huggingface Daily Paper #1）指出：传统的"长期记忆/短期记忆"二分法已不足以描述当代 Agent 记忆系统的多样性。该论文提出了更细粒度的分类法，区分了事实记忆（Factual Memory）、经验记忆（Experiential Memory）和工作记忆（Working Memory）。

现代 AI Agent 记忆系统需要考虑以下维度：

1.2 三种核心记忆类型

根据 Machine Learning Mastery 的研究，构建能够从经验中学习、积累知识并执行复杂任务的 Agent，需要实现三种截然不同的长期记忆：

🎬 情景记忆（Episodic Memory）

• 定义：记录特定事件和经历的时序记忆
• 应用场景：个人 AI 助手的用户个性化
• 存储内容：用户偏好、过去的交互、决策结果
• 在 OpenClaw 中的体现：memory/YYYY-MM-DD.md 日志文件

📖 语义记忆（Semantic Memory）

• 定义：存储事实性知识和概念理解
• 应用场景：法律、医疗、金融等领域专家 Agent
• 存储内容：领域知识、定义、规则
• 在 OpenClaw 中的体现：MEMORY.md 中的结构化知识条目

⚙️ 程序记忆（Procedural Memory）

• 定义：存储"如何做"的操作性知识
• 应用场景：工作流自动化 Agent
• 存储内容：操作步骤、最佳实践、工作流程
• 在 OpenClaw 中的体现：通过 AGENTS.md 规则文件实现

二、OpenClaw 记忆架构深度解析

2.1 名称变更历史

OpenClaw 经历了多次更名：

创始人 Steinberger 表示："Clawd 诞生于 2025 年 11 月，是'Claude'加上爪子的有趣双关。直到 Anthropic 的法务团队礼貌地请我们重新考虑，这个名字感觉非常完美。"

2.2 文件系统即记忆

OpenClaw 采用了一种独特且"可黑客"的记忆架构：记忆就是工作空间中的 Markdown 文件。这与企业级工具使用的不透明嵌入数据库形成鲜明对比。

根据 OpenClaw 官方文档和深度技术分析，其记忆系统由以下子系统组成：

~/.openclaw/workspace/
├── MEMORY.md              # 🧠 长期记忆（策展的核心知识）
├── memory/
│   ├── 2026-01-25.md      # 📅 日志记忆（原始对话日志）
│   ├── 2026-01-26.md
│   └── 2026-01-27.md
├── AGENTS.md              # 📋 程序记忆（行为规则）
└── ~/.openclaw/memory/
    └── <agentId>.sqlite   # 🔍 向量搜索索引（SQLite）

2.3 双层记忆架构

核心区别在于：

日志笔记是原始日志；MEMORY.md 是 Agent 对你世界的策展理解。

• 日志记忆 捕获所有发生的事情——对话片段、临时决定、尝试过的方案
• 长期记忆 保存真正重要的内容——你的偏好、重要决策、反复出现的上下文、经验教训

2.4 语义搜索与向量索引

OpenClaw 可以在 MEMORY.md 和 memory/*.md（以及任何你选择加入的额外目录或文件）上构建小型向量索引，以便语义查询可以找到相关笔记。

memory_search 工具特性：

• 对 Markdown 块进行语义搜索（目标约 400 token，80 token 重叠）
• 搜索范围：MEMORY.md + memory/**/*.md
• 返回内容：片段文本（上限约 700 字符）、文件路径、行范围、分数、提供商/模型
• 支持本地 → 远程嵌入的回退机制
• 索引存储位置：~/.openclaw/memory/<agentId>.sqlite（可配置，支持 {agentId} 令牌）

2.5 透明性与用户控制

OpenClaw 记忆系统的一个革命性设计是其透明性。根据深度报道：

与企业工具使用的不透明嵌入数据库不同，OpenClaw 默认采用透明、"可黑客"的记忆系统——通常被描述为 MEMORY.md。这种基于文件的记忆系统允许用户充当自己 Agent 大脑的编辑者。如果机器人误解了某个偏好，用户可以直接在电脑上打开 Markdown 文件并删除那一行。

这种设计带来的优势：

• ✅ 完全透明：用户可以随时查看 Agent "记住"了什么
• ✅ 可编辑：直接修改文件即可纠正错误记忆
• ✅ 可备份：标准文件，可使用任何工具进行版本控制
• ✅ 隐私安全：所有记忆、文件和日志都存储在本地

2.6 记忆生命周期

OpenClaw 的记忆管理遵循以下生命周期：

┌─────────────────────────────────────────────────────────────────┐
│                        会话开始 (Bootstrap)                      │
├─────────────────────────────────────────────────────────────────┤
│  1. 读取 MEMORY.md（长期记忆）                                    │
│  2. 读取今日日志 memory/2026-01-27.md                            │
│  3. 读取昨日日志 memory/2026-01-26.md（最近上下文）               │
│  4. 注入 AGENTS.md 规则                                          │
│  5. 加载向量索引用于语义搜索                                       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        对话进行中                                │
├─────────────────────────────────────────────────────────────────┤
│  • 实时写入当日日志                                               │
│  • 按需进行语义+关键词混合搜索                                     │
│  • 用户可显式要求记住某些信息                                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     上下文压缩前 (Pre-Compaction)                 │
├─────────────────────────────────────────────────────────────────┤
│  ⚠️ 关键机制：当对话历史即将被压缩丢弃时                           │
│  Agent 自动执行"静默记忆刷新"：                                   │
│  • 将重要信息持久化到 MEMORY.md                                   │
│  • 确保关键上下文不会因压缩而丢失                                  │
│  • 默认提示显式声明模型可以回复，但通常 NO_REPLY 是正确响应        │
└─────────────────────────────────────────────────────────────────┘

这个"压缩前刷新"（Pre-Compaction Flush）机制是 OpenClaw 的核心创新之一——它确保即使在长对话中，关键信息也不会因为上下文窗口限制而丢失。

三、隐私与安全设计

3.1 群聊场景的隐私保护

OpenClaw 在群聊（Discord 服务器、Telegram 群组）中有特殊的隐私保护机制：

在群聊中，MEMORY.md 永远不会被注入。这可以防止你的个人上下文泄露给其他参与者。日志笔记遵循类似的模式：它们在会话开始时被读取以保持连续性，但不会广播到共享上下文中。

这种设计体现了"默认安全"的原则：

3.2 本地优先架构

根据 DigitalOcean 的介绍：

OpenClaw 采用"本地优先"（Local First）的设计理念，运行在 Windows、Mac、Linux 或 VPS 上。所有记忆、文件和日志都存储在本地。这使其超级安全，非常适合敏感任务。它通过尽可能在本地处理提示和文件交互，最大限度地减少数据泄露。

3.3 安全注意事项

根据 Astrix Security 的分析，OpenClaw 的设计也引起了网络安全研究人员的关注，潜在漏洞包括：

• 提示注入攻击
• 暴露的管理界面
• 本地配置文件中存储的凭据

用户在部署时需要注意适当的安全配置。

四、与其他 AI Agent 记忆系统的比较

4.1 Claude Code 的 CLAUDE.md 系统

根据 Claude Code 官方文档和上下文工程最佳实践：

Claude Code 在 2025 年发布了 176 次更新，从 beta 版迭代到 v2.0。关键里程碑包括 CLAUDE.md 记忆文件、Plan 模式、Subagents、/context 命令、Skills 和 Opus 4.5。

Claude Code 采用了类似但更结构化的记忆系统：

项目根目录/
├── CLAUDE.md              # 项目级记忆/规则
├── CLAUDE.local.md        # 本地个人配置（不入版本控制）
└── .claude/
    └── rules/             # 模块化规则目录
        ├── coding-style.md
        ├── git-workflow.md
        └── testing.md

Claude Code 的特色功能：

• 递归读取：从当前目录向上递归读取所有 CLAUDE.md 文件（直到但不包括根目录）
• 文件导入：支持 @path/to/import 语法引用其他文件
• 模块化规则：.claude/rules/ 目录支持将规则拆分为多个文件

2025-2026 年更新亮点：

• 修复了使用 @include 指令时意外将二进制文件（图片、PDF 等）包含在记忆中的问题
• 改进了外部 CLAUDE.md 导入审批对话框
• 内存使用优化 3 倍（针对大型对话）
• 移除了 # 快捷方式用于快速记忆输入（现在告诉用户让 Claude 编辑 CLAUDE.md）

社区解决方案： 由于 Claude Code 本身没有自动记忆系统，社区开发了多种扩展：

• episodic-memory：自动将所有对话存档到 ~/.config/superpowers/conversations-archive，并提供带向量搜索的 SQLite 数据库
• Claude Code Memory Bank：Cline Memory Bank 方法论的实验性改编，专门针对 Claude Code 优化

4.2 OpenCode 的 AGENTS.md 系统

根据 OpenCode 官方文档和 AGENTS.md 技术解析：

OpenCode 使用 AGENTS.md 作为其规则注入机制：

• 自由格式：AGENTS.md 是自由格式的 Markdown，直接注入到 Agent 的系统上下文
• 一次性加载：AGENTS.md 上下文在会话启动时加载一次，并在整个会话生命周期中保持不变
• 自动生成：运行 /init 命令可以扫描项目并自动生成 AGENTS.md 文件

记忆插件生态：

opencode-agent-memory 插件被描述为"AGENTS.md with a harness"：

它类似于 AGENTS.md 的精神，但增加了结构（带元数据和大小限制的作用域块）、专用的记忆操作工具，以及鼓励 Agent 主动维护自身记忆的提示。核心理念——给予 Agent 持久的、可自编辑的记忆块——改编自 Letta。

其他记忆插件：

• opencode-mem：使用本地向量数据库的持久记忆系统，支持双记忆作用域、Web 界面、自动捕获系统
• opencode-supermemory：使用 Supermemory 的持久记忆，跨会话、跨项目记忆

4.3 综合对比

五、Token 消耗优化：对话模式 vs 直接写入模式

5.1 问题背景

这是我们在实际项目中遇到的一个关键工程问题：如何在不消耗 AI Token 的情况下管理 Agent 记忆？

在我们的 WordPress 插件（TriliumAI Agent）中，原始的记忆写入实现采用了"对话模式"：

// ❌ 原始实现：对话模式（消耗 Token）
async writeToOpenClawMemory(notes, memoryMode) {
    // 构造自然语言指令
    const instruction = `请将以下内容追加到 ${targetFile} 文件末尾：

    ${memoryContent}

    请使用 write 工具完成写入，并确认写入成功。`;

    // 通过 WebSocket 发送给 AI 处理
    return this.client.sendMessage(instruction);  // 消耗 Token！
}

这种方法的问题：

5.2 研究发现

根据 FlowHunt 的上下文工程研究和 DEV Community 的 Token 优化指南，以下策略可以显著减少 Token 消耗：

• 直接文件操作：绕过 AI 对话，直接通过 API 操作文件
• 上下文压缩：使用摘要技术压缩历史记录
• 按需检索：不加载全部记忆，而是按需搜索
• 工具外部化：通过 MCP 等协议将工具调用外部化

根据 arXiv 2601.11653 论文的实验数据：

在 100 轮对话测试中，这些技术将总 Token 消耗减少了 84%，同时仍然允许对话连贯地继续。换句话说，Agent 不需要在每一步都将整个历史塞进提示词——它可以丢弃或压缩正确的部分，并在需要时召回它们。

根据 Anthropic 的评估：

结合记忆工具和上下文编辑，在复杂多步骤基准测试中任务成功率提高了 39%。即使单独使用上下文编辑也能带来约 29% 的提升。

5.3 我们的解决方案：REST API 直接写入

我们将记忆操作从"对话模式"改造为"直接写入模式"：

// ✅ 优化后：直接写入模式（零 Token 消耗）
async writeToOpenClawMemory(notes, memoryMode) {
    // 格式化记忆内容（纯前端操作）
    const memoryContent = this.formatMemoryContent(notes);

    // 确定目标文件
    const target = memoryMode === 'long_term'
        ? 'MEMORY.md'
        : `memory/${dateStr}.md`;

    // 通过 REST API 直接写入文件系统
    return this.callMemoryRestApi('write', {
        target: target,
        content: memoryContent,
        mode: 'append'
    });  // 零 Token 消耗！
}

技术架构变化：

┌──────────────────────────────────────────────────────────────┐
│                     原始架构（对话模式）                        │
├──────────────────────────────────────────────────────────────┤
│  前端 → WebSocket → OpenClaw AI → 工具调用 → 文件系统          │
│                        ↑                                      │
│                   消耗 Token                                   │
└──────────────────────────────────────────────────────────────┘

                          ↓ 优化

┌──────────────────────────────────────────────────────────────┐
│                     优化架构（直接写入）                        │
├──────────────────────────────────────────────────────────────┤
│  前端 → REST API → FileBrowser API → 文件系统                  │
│                                                               │
│              完全绕过 AI，零 Token 消耗                         │
└──────────────────────────────────────────────────────────────┘

5.4 实现要点

我们的解决方案涉及以下组件的改造：

关键代码变更（REST API 调用）：

callMemoryRestApi: function(endpoint, data, method) {
    method = method || 'POST';

    // 使用 REST nonce（wp_rest）而不是 AJAX nonce
    var url = this.config.restUrl + '/openclaw/memory/' + endpoint;

    return fetch(url, {
        method: method,
        credentials: 'same-origin',  // 确保发送 cookie
        headers: {
            'Content-Type': 'application/json',
            'X-WP-Nonce': this.config.restNonce  // WordPress REST API 认证
        },
        body: method !== 'GET' ? JSON.stringify(data) : undefined
    }).then(response => response.json());
}

通过 Docker 共享卷实现文件访问：

# docker-compose.yml
services:
  openclaw:
    volumes:
      - ./data:/app/workspace    # OpenClaw 工作空间

  filebrowser:
    volumes:
      - ./data:/srv              # FileBrowser 服务目录

这样，WordPress 可以通过 FileBrowser API 直接操作 OpenClaw 的记忆文件，无需经过 AI。

六、前沿研究与未来趋势

6.1 2026 年最新动态

根据 Agent Memory Paper List 追踪的最新论文：

6.2 MemoryOS：记忆操作系统

根据 arXiv 2506.06326，研究人员提出了 MemoryOS 来实现 AI Agent 的全面高效记忆管理。受操作系统内存管理原则的启发，MemoryOS 设计了包含四个关键模块的分层存储架构：

• Memory Storage（记忆存储）
• Memory Updating（记忆更新）
• Memory Retrieval（记忆检索）
• Memory Generation（记忆生成）

该架构包含三级存储单元：

• 短期记忆（Short-term Memory）
• 中期记忆（Mid-term Memory）
• 长期个人记忆（Long-term Personal Memory）

6.3 ReasoningBank：推理策略记忆库

Google Cloud AI Research 开发的 ReasoningBank 框架使 LLM Agent 能够将经验组织成记忆库。它从 Agent 解决问题的成功和失败尝试中提炼出"可泛化的推理策略"，然后在推理时使用这些记忆来避免重复过去的错误。

6.4 claude-cognitive 工作记忆系统

根据 GitHub 项目，claude-cognitive 实现了基于注意力的分层记忆机制：

注意力衰减机制：每个回合，注意力分数衰减 15%；提及某个主题会将相关文件跳回 1.0。

系统支持多实例协调（Instance A、B 和 default），并追踪上下文大小（平均约 18,420 字符）。采用 30 天保留策略，将注意力历史存储在 ~/.claude/attention_history.jsonl 的仅追加 JSONL 文件中。

6.5 未来方向

根据 2026 年 AI 研究展望：

"2026 年可能会被记住为 AI 研究从'我们能做多大'转向'我们如何高效地变聪明'的一年。智能，事实证明，与参数数量关系不大，而与架构、记忆以及知道何时深度思考、何时快速思考更为相关。"

核心论点已经明确：记忆不是外围功能，而是未来智能体设计的基础原语。没有健壮的记忆系统，AI Agent 无法维持行为一致性、从经验中学习或适应不断变化的环境。

根据 Claude Code Meetup Tokyo 的信息，开发者 Boris Cherny 表示对两个方向感兴趣：

• 长时间运行任务（Long Running Tasks）：支持跨越数小时甚至数天的任务
• 群体智能（Swarm）：多 Agent 协作和记忆共享

七、实践建议

7.1 选择合适的记忆架构

7.2 Token 优化最佳实践

1. 区分读写路径：读取需要 AI 理解，写入可以绕过 AI
2. 利用共享存储：通过 Docker 卷或共享文件系统实现直接访问
3. 实现 REST API 层：为前端提供直接文件操作的能力
4. 使用正确的认证：WordPress REST API 需要 wp_rest nonce

📚 参考资料与延伸阅读

官方文档

• OpenClaw 官网
• OpenClaw Memory 文档
• Claude Code Memory 文档
• OpenCode Agents 文档

深度分析

• Deep Dive: How OpenClaw's Memory System Works
• ClawBot's Architecture Explained: How a Lobster Conquered 100K GitHub Stars
• OpenClaw: How a Weekend Project Became an Open-Source AI Sensation
• From Clawdbot to Moltbot to OpenClaw (CNBC)
• What is OpenClaw? (DigitalOcean)

学术论文

• Memory in the Age of AI Agents (arXiv:2512.13564)
• AI Agents Need Memory Control Over More Context (arXiv:2601.11653)
• Memory OS of AI Agent (arXiv:2506.06326)
• From Storage to Experience: A Survey on the Evolution of LLM Agent Memory Mechanisms

社区资源

• Agent Memory Paper List (GitHub)
• OpenClaw GitHub
• opencode-agent-memory Plugin
• claude-cognitive Project

📝 小结

本文深入探讨了 AI Agent 记忆系统的理论基础与工程实践：

1. 理论层面：理解了情景记忆、语义记忆、程序记忆三种核心记忆类型及其应用场景
2. 架构层面：详细分析了 OpenClaw 的 MEMORY.md + 日志记忆双层架构，以及与 Claude Code、OpenCode 的对比
3. 工程层面：解决了实际项目中的 Token 消耗问题，将"对话模式"改造为"直接写入模式"
4. 前沿层面：了解了 2026 年最新的记忆系统研究动态和未来发展方向，包括 MemoryOS、ReasoningBank 等创新框架

核心洞见：

在 AI Agent 时代，记忆不再是可选项，而是核心竞争力。选择透明、可控、高效的记忆架构，将直接决定你的 Agent 能走多远