AI Agent 记忆系统深度解析：以 Clawdbot/Moltbot 为例
-
AI Agent 记忆系统深度解析：以 Clawdbot/Moltbot 为例
目录- 一、AI Agent 记忆系统的理论基础
- 1.1 为什么传统分类法已不够用？
- 1.2 三种核心记忆类型
- 二、Clawdbot 记忆架构深度解析
- 2.1 文件系统即记忆
- 2.2 双层记忆架构
- 2.3 透明性与用户控制
- 2.4 记忆生命周期
- 三、隐私与安全设计
- 3.1 群聊场景的隐私保护
- 3.2 本地优先架构
- 四、与其他 AI Agent 记忆系统的比较
- 4.1 Claude Code 的 CLAUDE.md 系统
- 4.2 OpenCode 的 AGENTS.md 系统
- 4.3 综合对比
- 五、Token 消耗优化：对话模式 vs 直接写入模式
- 5.1 问题背景
- 5.2 研究发现
- 5.3 我们的解决方案：REST API 直接写入
- 5.4 实现要点
- 六、前沿研究与未来趋势
- 6.1 2026 年最新动态
- 6.2 Claude-Cognitive 工作记忆系统
- 6.3 未来方向
- 七、实践建议
- 7.1 选择合适的记忆架构
- 7.2 Token 优化最佳实践
- 📚 参考资料与延伸阅读
- 官方文档
- 深度分析
- 学术论文
- 📝 小结
在 AI Agent 时代，记忆（Memory） 已成为决定智能体能力上限的关键要素。一个没有记忆的 AI 就像患有顺行性遗忘症的人——每次对话都是从零开始，无法积累经验、无法学习偏好、无法完成需要长期上下文的复杂任务。
本课程将以 Clawdbot（现已更名为 Moltbot）为核心案例，深入剖析 AI Agent 记忆系统的架构设计、实现原理、以及我们在实际项目中遇到的工程挑战与解决方案。
💡 为什么选择 Clawdbot？
Clawdbot 被称为 "Claude with hands"——它不仅能思考，还拥有持久记忆，并能通过 iMessage 和 WhatsApp 进行实时对话。它在 GitHub 上获得了超过 60,000 颗星，是开源历史上增长最快的项目之一，由著名开发者 Peter Steinberger（@steipete）创建。一、AI Agent 记忆系统的理论基础
1.1 为什么传统分类法已不够用？
根据 2025 年 12 月发表的权威综述论文 "Memory in the Age of AI Agents"（登顶 Huggingface Daily Paper #1）指出：传统的"长期记忆/短期记忆"二分法已不足以描述当代 Agent 记忆系统的多样性。
现代 AI Agent 记忆系统需要考虑以下维度：
维度 说明 示例 持久性 记忆存活的时间范围 会话级 vs 跨会话 vs 永久 结构化程度 从非结构化文本到结构化数据库 Markdown 文件 vs 向量数据库 vs 关系数据库 访问模式 记忆的检索方式 全量注入 vs 按需检索 vs 语义搜索 更新机制 记忆的写入触发条件 显式写入 vs 隐式学习 vs 压缩刷新 作用域 记忆的可见范围 全局 vs 项目级 vs 会话级 1.2 三种核心记忆类型
根据 Machine Learning Mastery 的研究，构建能够从经验中学习、积累知识并执行复杂任务的 Agent，需要实现三种截然不同的长期记忆：
🎬 情景记忆（Episodic Memory）
- 定义：记录特定事件和经历的时序记忆
- 应用场景：个人 AI 助手的用户个性化
- 存储内容：用户偏好、过去的交互、决策结果
- 在 Clawdbot 中的体现：
memory/YYYY-MM-DD.md日志文件
📖 语义记忆（Semantic Memory）
- 定义：存储事实性知识和概念理解
- 应用场景：法律、医疗、金融等领域专家 Agent
- 存储内容：领域知识、定义、规则
- 在 Clawdbot 中的体现：
MEMORY.md中的结构化知识条目
⚙️ 程序记忆（Procedural Memory）
- 定义：存储"如何做"的操作性知识
- 应用场景：工作流自动化 Agent
- 存储内容：操作步骤、最佳实践、工作流程
- 在 Clawdbot 中的体现：通过 AGENTS.md 规则文件实现
二、Clawdbot 记忆架构深度解析
2.1 文件系统即记忆
Clawdbot 采用了一种独特且"可黑客"的记忆架构：记忆就是工作空间中的 Markdown 文件。 这与企业级工具使用的不透明嵌入数据库形成鲜明对比。
根据 Clawdbot 官方文档 和 深度技术分析，其记忆系统由以下子系统组成：
workspace/ ├── MEMORY.md # 🧠 长期记忆（策展的核心知识） ├── memory/ │ ├── 2026-01-25.md # 📅 日志记忆（原始对话日志） │ ├── 2026-01-26.md │ └── 2026-01-27.md ├── AGENTS.md # 📋 程序记忆（行为规则） └── .clawdbot/ └── embeddings.db # 🔍 向量搜索索引（SQLite）2.2 双层记忆架构
记忆层 文件 特征 注入时机 长期记忆 MEMORY.md策展的、精炼的、持久的 每次会话开始 日志记忆 memory/YYYY-MM-DD.md原始的、详细的、时序的 今日+昨日自动加载 核心区别在于：
日志笔记是原始日志；MEMORY.md 是 Agent 对你世界的策展理解。
- 日志记忆 捕获所有发生的事情——对话片段、临时决定、尝试过的方案
- 长期记忆 保存真正重要的内容——你的偏好、重要决策、反复出现的上下文、经验教训
2.3 透明性与用户控制
Clawdbot 记忆系统的一个革命性设计是其透明性。 根据 MacStories 的深度报道：
与企业工具使用的不透明嵌入数据库不同，Clawdbot 默认采用透明、"可黑客"的记忆系统——通常被描述为 MEMORY.md。这种基于文件的记忆系统允许用户充当自己 Agent 大脑的编辑者。如果机器人误解了某个偏好，用户可以直接在电脑上打开 Markdown 文件并删除那一行。
这种设计带来的优势：
- ✅ 完全透明：用户可以随时查看 Agent "记住"了什么
- ✅ 可编辑：直接修改文件即可纠正错误记忆
- ✅ 可备份：标准文件，可使用任何工具进行版本控制
- ✅ 隐私安全：所有记忆、文件和日志都存储在本地
2.4 记忆生命周期
Clawdbot 的记忆管理遵循以下生命周期：
┌─────────────────────────────────────────────────────────────────┐ │ 会话开始 (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 │ │ • 确保关键上下文不会因压缩而丢失 │ └─────────────────────────────────────────────────────────────────┘这个"压缩前刷新"（Pre-Compaction Flush）机制是 Clawdbot 的核心创新之一——它确保即使在长对话中，关键信息也不会因为上下文窗口限制而丢失。
三、隐私与安全设计
3.1 群聊场景的隐私保护
Clawdbot 在群聊（Discord 服务器、Telegram 群组）中有特殊的隐私保护机制：
在群聊中，MEMORY.md 永远不会被注入。这可以防止你的个人上下文泄露给其他参与者。日志笔记遵循类似的模式：它们在会话开始时被读取以保持连续性，但不会广播到共享上下文中。
这种设计体现了"默认安全"的原则：
场景 MEMORY.md 日志记忆 说明 私人对话 ✅ 注入 ✅ 注入 完整个人化体验 群聊 ❌ 不注入 ❌ 不注入 保护隐私 3.2 本地优先架构
根据 Clawdbot 官方介绍：
Clawdbot 运行在 Windows、Mac、Linux 或 VPS 上。所有记忆、文件和日志都存储在本地。 这使其超级安全，非常适合敏感任务。
四、与其他 AI Agent 记忆系统的比较
4.1 Claude Code 的 CLAUDE.md 系统
根据 Claude Code 官方文档 和 上下文工程最佳实践：
Claude Code 采用了类似但更结构化的记忆系统：
项目根目录/ ├── CLAUDE.md # 项目级记忆/规则 ├── CLAUDE.local.md # 本地个人配置（不入版本控制） └── .claude/ └── rules/ # 模块化规则目录 ├── coding-style.md ├── git-workflow.md └── testing.mdClaude Code 的特色功能：
- 递归读取：从当前目录向上递归读取所有 CLAUDE.md 文件
- 文件导入：支持
@path/to/import语法引用其他文件 - 模块化规则：
.claude/rules/目录支持将规则拆分为多个文件
根据 Claude Code 2025 年更新日志分析，Claude Code 在 2025 年发布了 176 次更新，"上下文工程"成为贯穿各主要功能的统一主题。
4.2 OpenCode 的 AGENTS.md 系统
根据 OpenCode 官方文档 和 AGENTS.md 技术解析：
OpenCode 使用 AGENTS.md 作为其规则注入机制：
- 自由格式：AGENTS.md 是自由格式的 Markdown，直接注入到 Agent 的系统上下文
- 一次性加载：AGENTS.md 上下文在会话启动时加载一次，并在整个会话生命周期中保持不变
- 插件扩展：通过 opencode-agent-memory 等插件可实现更强大的记忆功能
opencode-agent-memory 插件被描述为"AGENTS.md with a harness"：
它类似于 AGENTS.md 的精神，但增加了结构（带元数据和大小限制的作用域块）、专用的记忆操作工具，以及鼓励 Agent 主动维护自身记忆的提示。
4.3 综合对比
特性 Clawdbot Claude Code OpenCode 长期记忆文件 MEMORY.md CLAUDE.md AGENTS.md 日志记忆 memory/YYYY-MM-DD.md ❌ 无原生支持 ❌ 需插件 递归读取 ❌ ✅ ❌ 向量搜索 ✅ 内置 ❌ 需插件 ❌ 需插件 压缩前刷新 ✅ 自动 ❌ ❌ 群聊隐私 ✅ 自动隔离 N/A N/A 五、Token 消耗优化：对话模式 vs 直接写入模式
5.1 问题背景
这是我们在实际项目中遇到的一个关键工程问题：如何在不消耗 AI Token 的情况下管理 Agent 记忆？
在我们的 WordPress 插件（TriliumAI Agent）中，原始的记忆写入实现采用了"对话模式"：
// ❌ 原始实现：对话模式（消耗 Token） async writeToClawdbotMemory(notes, memoryMode) { // 构造自然语言指令 const instruction = `请将以下内容追加到 ${targetFile} 文件末尾： ${memoryContent} 请使用 write 工具完成写入，并确认写入成功。`; // 通过 WebSocket 发送给 AI 处理 return this.client.sendMessage(instruction); // 消耗 Token！ }这种方法的问题：
问题 影响 Token 消耗 每次记忆写入都需要 AI 理解并执行，消耗大量 Token 速率限制 受 AI API 速率限制影响 延迟 需要等待 AI 响应，延迟较高 可靠性 AI 可能误解指令或执行失败 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 writeToClawdbotMemory(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 → Clawdbot AI → 工具调用 → 文件系统 │ │ ↑ │ │ 消耗 Token │ └──────────────────────────────────────────────────────────────┘ ↓ 优化 ┌──────────────────────────────────────────────────────────────┐ │ 优化架构（直接写入） │ ├──────────────────────────────────────────────────────────────┤ │ 前端 → REST API → FileBrowser API → 文件系统 │ │ │ │ 完全绕过 AI，零 Token 消耗 │ └──────────────────────────────────────────────────────────────┘5.4 实现要点
我们的解决方案涉及以下组件的改造：
组件 文件 改造内容 PHP REST 端点 class-clawdbot-rest.php新增 /memory/write、/memory/read、/memory/clear、/memory/list端点PHP 文件客户端 class-filebrowser-client.php新增 get_file_content()、append_file()、clear_file()方法JS WebSocket 客户端 clawdbot-websocket.js记忆方法改为调用 REST API JS 工作区模块 opencode-workspace.jswriteToClawdbotMemory()改用 REST APIPHP 加载器 class-agent-loader.php加载并初始化 REST 端点 关键代码变更（REST API 调用）：
callMemoryRestApi: function(endpoint, data, method) { method = method || 'POST'; // 使用 REST nonce（wp_rest）而不是 AJAX nonce var url = this.config.restUrl + '/clawdbot/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: clawdbot: volumes: - ./data:/app/workspace # Clawdbot 工作空间 filebrowser: volumes: - ./data:/srv # FileBrowser 服务目录这样，WordPress 可以通过 FileBrowser API 直接操作 Clawdbot 的记忆文件，无需经过 AI。
六、前沿研究与未来趋势
6.1 2026 年最新动态
根据 Agent Memory Paper List 追踪的最新论文：
论文 发表时间 核心贡献 Agentic Memory 2026年1月 学习统一的长短期记忆管理 EverMemOS 2026年1月 用于结构化长程推理的自组织记忆操作系统 MemRL 2026年1月 通过运行时强化学习实现自进化的情景记忆 6.2 Claude-Cognitive 工作记忆系统
根据 Medium 深度报道，claude-cognitive 项目于 2025 年 12 月 31 日发布，在 4 天内获得 310 个 GitHub 星标，NASA、Microsoft、Amazon、NVIDIA 和 GSA 的工程师都参与了互动。
其核心创新是"分层记忆注入"：
温度层 注意力分数 注入策略 🔥 HOT > 0.8 完整文件注入（活跃开发） ☀️ WARM 0.25-0.8 仅标题注入（背景感知） ❄️ COLD < 0.25 不加载但可检索 注意力衰减机制：每个回合，注意力分数衰减 15%；提及某个主题会将相关文件跳回 1.0。
6.3 未来方向
根据 Claude Code Meetup Tokyo 的信息，开发者 Boris Cherny 表示对两个方向感兴趣：
- 长时间运行任务（Long Running Tasks）：支持跨越数小时甚至数天的任务
- 群体智能（Swarm）：多 Agent 协作和记忆共享
七、实践建议
7.1 选择合适的记忆架构
场景 推荐架构 理由 个人 AI 助手 Clawdbot 模式 完整的日志+长期记忆，隐私保护 代码助手 Claude Code 模式 项目级规则，递归继承 团队协作 OpenCode + 插件 灵活的插件生态 7.2 Token 优化最佳实践
- 区分读写路径：读取需要 AI 理解，写入可以绕过 AI
- 利用共享存储：通过 Docker 卷或共享文件系统实现直接访问
- 实现 REST API 层：为前端提供直接文件操作的能力
- 使用正确的认证：WordPress REST API 需要
wp_restnonce
📚 参考资料与延伸阅读
官方文档
深度分析
- How Clawdbot Remembers: A Deep Dive into AI Agent Memory Architecture
- The Sovereign Agent: A Comprehensive Treatise on Clawdbot
- Clawdbot Showed Me What the Future of Personal AI Assistants Looks Like
- Beyond Prompts: 4 Context Engineering Secrets for Claude Code
学术论文
- Memory in the Age of AI Agents (arXiv:2512.13564)
- AI Agents Need Memory Control Over More Context (arXiv:2601.11653)
- Context Engineering for Multi-Agent LLM Code Assistants (arXiv:2508.08322)
📝 小结
本文深入探讨了 AI Agent 记忆系统的理论基础与工程实践：
- 理论层面：理解了情景记忆、语义记忆、程序记忆三种核心记忆类型及其应用场景
- 架构层面：详细分析了 Clawdbot 的 MEMORY.md + 日志记忆双层架构，以及与 Claude Code、OpenCode 的对比
- 工程层面：解决了实际项目中的 Token 消耗问题，将"对话模式"改造为"直接写入模式"
- 前沿层面：了解了 2026 年最新的记忆系统研究动态和未来发展方向
核心洞见：
在 AI Agent 时代，记忆不再是可选项，而是核心竞争力。选择透明、可控、高效的记忆架构，将直接决定你的 Agent 能走多远。
-
0 回复
歡迎留言回复交流。
Log in to reply.