Skip to Content
📖 教程🧠 进阶功能记忆系统

记忆系统实战

AI 助手最大的痛点之一是”失忆”——每次对话都从零开始。OpenClaw 的记忆系统解决了这个问题，让 AI 拥有 短期记忆、长期记忆和语义搜索 能力。本文将深入讲解记忆系统的架构、配置与实战技巧。

记忆文件体系

OpenClaw 使用 基于文件的记忆架构，分为两层：

MEMORY.md — 长期记忆

MEMORY.md 是 AI 的”大脑核心”，存储经过筛选和提炼的重要信息：

# MEMORY.md
 
## 关于用户
- 名字：张三
- 职业：全栈开发者，主要使用 TypeScript
- 偏好：喜欢简洁的代码风格，讨厌过度工程化
- 时区：UTC+8（北京时间）
 
## 重要项目
- OpenClaw101.club：技术文档站点，使用 Astro 框架
- 上次讨论到部署问题，已解决
 
## 已学到的教训
- 用户不喜欢冗长的解释，直接给方案
- 发送代码时注明语言和文件路径

安全规则：MEMORY.md 仅在主会话（private DM）中加载，群聊中不会读取，防止个人信息泄露。

memory/YYYY-MM-DD.md — 每日记录

每日记录是 AI 的”工作日志”，记录当天发生的具体事件：

# 2025-01-15
 
## 上午
- 用户要求重构 API 路由，已完成
- 发现 Node.js 版本兼容问题，建议升级到 v22
 
## 下午
- 帮助用户调试 Docker 部署问题
- 用户提到下周要演示项目给投资人看
 
## 待办
- [ ] 准备演示环境的优化建议
- [ ] 检查 CI/CD 流程

两者的关系

daily notes (memory/YYYY-MM-DD.md)
    ↓ 定期回顾和提炼
long-term memory (MEMORY.md)
  • 每日记录：原始、详细、时间线性的
  • 长期记忆：提炼、结构化、持续更新的
  • AI 在心跳检查（heartbeat）期间会自动回顾近期日记，将有价值的信息提升到 MEMORY.md

memory_search 和 memory_get 工具

OpenClaw 提供了内置工具，让 AI 能够主动搜索和检索记忆。

memory_search — 语义搜索

当 AI 需要查找过去的记忆时，可以使用 memory_search 进行语义搜索：

# AI 内部调用示例
memory_search("用户上次提到的数据库迁移方案")

它会在所有记忆文件中搜索语义相关的内容，返回最匹配的片段。这比简单的关键词搜索强大得多——它能理解意图。

memory_get — 精确获取

memory_get 用于获取特定的记忆文件内容：

# 获取长期记忆
memory_get("MEMORY.md")

# 获取特定日期的记录
memory_get("memory/2025-01-15.md")

工具调用流程

用户提问："上次我们讨论的部署方案是什么？"
    ↓
AI 调用 memory_search("部署方案")
    ↓
返回相关记忆片段
    ↓
AI 结合记忆内容回答问题

向量记忆搜索配置

OpenClaw 支持基于向量嵌入的语义搜索，提供更精确的记忆检索。

工作原理

  1. 记忆文件内容被分块（chunking）
  2. 每个块通过嵌入模型转换为向量
  3. 搜索时，查询也转换为向量
  4. 通过余弦相似度找到最相关的记忆块

配置向量搜索

# openclaw.yaml
memory:
  # 启用向量搜索
  vectorSearch:
    enabled: true
    
    # 嵌入模型选择
    embeddingModel: "text-embedding-3-small"
    
    # 向量维度
    dimensions: 1536
    
    # 相似度阈值（0-1，越高越严格）
    similarityThreshold: 0.7
    
    # 最大返回结果数
    maxResults: 10
    
    # 索引更新策略
    indexing:
      # 写入记忆后自动更新索引
      autoIndex: true
      # 批量索引的时间间隔（秒）
      batchInterval: 300

嵌入模型选择建议

# 高质量（推荐生产环境）
embeddingModel: "text-embedding-3-large"
 
# 平衡性能与成本
embeddingModel: "text-embedding-3-small"
 
# 使用 OpenRouter 的嵌入模型
embeddingModel: "openrouter/openai/text-embedding-3-small"

自动记忆刷新（Pre-Compaction Memory Flush）

当对话上下文窗口接近模型的 token 限制时，OpenClaw 会执行 上下文压缩（compaction）。在压缩之前，系统会自动将重要信息刷新到记忆文件中，确保不会丢失。

工作流程

上下文窗口接近限制
    ↓
触发 pre-compaction memory flush
    ↓
AI 回顾当前对话，提取关键信息
    ↓
写入 memory/YYYY-MM-DD.md
    ↓
执行上下文压缩（移除旧消息，保留摘要）
    ↓
继续对话（关键信息已持久化）

配置

agents:
  defaults:
    session:
      compaction:
        enabled: true
        # 启用压缩前记忆刷新
        preCompactionMemoryFlush: true
        # 压缩触发阈值（上下文使用百分比）
        threshold: 80

为什么重要？

没有这个机制，当对话很长时：

  • 早期的重要信息会被静默丢弃
  • AI 会”忘记”对话开始时提到的关键需求
  • 用户需要反复重复信息

有了 pre-compaction flush：

  • 关键信息在压缩前被保存到文件
  • 即使上下文被裁剪，AI 仍然可以通过 memory_search 找回
  • 长对话的连续性得到保障

QMD 后端（实验性）

QMD（Quick Memory Database）是 OpenClaw 正在开发的实验性记忆后端，提供更高效的记忆存储和检索。

特点

  • 结构化存储：不只是纯文本，支持元数据标签和分类
  • 更快的搜索：基于优化的索引结构
  • 自动去重：智能合并相似的记忆条目
  • 时间衰减：旧记忆的权重自动降低

启用 QMD

# openclaw.yaml（实验性功能）
memory:
  backend: "qmd"
  qmd:
    # 数据存储路径
    dataDir: "~/.openclaw/qmd"
    # 自动去重阈值
    deduplicationThreshold: 0.9
    # 时间衰减因子（天）
    decayHalfLife: 30

⚠️ 注意：QMD 目前处于实验阶段，API 和配置格式可能随版本更新而变化。生产环境建议继续使用基于文件的默认后端。

最佳实践

1. 结构化你的 MEMORY.md

# MEMORY.md
 
## 用户画像
<!-- 基本信息、偏好、习惯 -->
 
## 活跃项目
<!-- 当前正在进行的项目和状态 -->
 
## 技术栈偏好
<!-- 用户喜欢的技术、框架、工具 -->
 
## 沟通偏好
<!-- 回复风格、详细程度、语言 -->
 
## 已知问题
<!-- 记录踩过的坑，避免重复 -->

2. 定期维护记忆

# 在 HEARTBEAT.md 中添加记忆维护任务
- 每 3 天回顾一次 memory/ 目录下的近期日记
- 将有价值的信息提炼到 MEMORY.md
- 清理过期或不再相关的记忆条目

3. 不要存储敏感凭证

# ❌ 错误做法
用户的 API Key: sk-xxxxxxxxxxxx
数据库密码: P@ssw0rd123
 
# ✅ 正确做法
用户有 OpenAI API Key（已配置在环境变量中）
数据库连接已配置完成

4. 利用每日记录追踪项目进度

# memory/2025-01-15.md
 
## 项目：API 重构
- 完成了用户认证模块的重构
- 待处理：订单模块的 API 端点
- 发现的问题：Redis 缓存策略需要调整
 
## 明天计划
- 继续订单模块重构
- 与用户确认缓存失效策略

5. 控制记忆大小

记忆文件不宜过大，否则会消耗大量 token：

  • MEMORY.md：建议控制在 2000 字以内
  • 每日记录：建议控制在 1000 字以内
  • 定期归档旧的每日记录
# 查看记忆文件大小
wc -c MEMORY.md memory/*.md
 
# 如果 MEMORY.md 过大，考虑拆分或精简

6. 记忆与会话的协同

会话上下文（短期）  ←→  每日记录（中期）  ←→  MEMORY.md（长期）
   当前对话              今天发生的事          重要的持久信息
   自动管理              AI 主动记录           AI 定期提炼
   会话结束即消失         保留数周              持续维护

记忆系统是 OpenClaw 的灵魂之一。合理使用记忆机制，你的 AI 助手将不再是一个”金鱼记忆”的聊天机器人，而是一个真正了解你、能持续为你工作的智能伙伴。

💬 有问题或建议？ 欢迎在下方评论区留言讨论。

Last updated on
会话管理模型配置