乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > OpenClaw 记忆系统配置完全指南:从零搭建智能体长期记忆

OpenClaw 记忆系统配置完全指南:从零搭建智能体长期记忆

当前时间： 2026-08-16 23:13:19 分类：办公文件 评论(0)
OpenClaw 记忆系统配置完全指南:从零搭建智能体长期记忆

结论先行

OpenClaw 的记忆系统是其区别于普通 AI 助手的核心能力。通过三层记忆架构（工作区文件 + 向量索引 + 语义搜索），你可以让智能体拥有真正的长期记忆——记住你的偏好、项目上下文、甚至几个月前的对话细节。本文将提供三套可落地的配置方案，覆盖从个人用户到企业级部署的完整场景。

一、核心概念：OpenClaw 记忆系统如何工作

1.1 三层记忆架构

层级
存储位置
用途
持久性
短期记忆
会话上下文
当前对话流
会话结束即丢失
日记忆memory/YYYY-MM-DD.md
每日日志、临时笔记
永久存储
长期记忆MEMORY.md
核心偏好、重要决策
永久存储

关键洞察：OpenClaw 的记忆本质是纯 Markdown 文件。智能体只能”记住”写入磁盘的内容——没有文件，就没有记忆。

1.2 记忆工作流程

用户对话 → 智能体判断 → 写入 memory/ 或 MEMORY.md → 向量索引更新 → 语义搜索可用 

自动记忆刷新机制：当会话接近压缩阈值时，OpenClaw 会自动触发静默回合，提醒智能体在上下文被压缩前写入持久记忆。

二、基础配置：5 分钟快速上手

2.1 工作区目录结构

~/.openclaw/workspace/
├── AGENTS.md          # 智能体行为指南
├── SOUL.md            # 智能体人格设定
├── USER.md            # 用户信息
├── IDENTITY.md        # 智能体身份
├── TOOLS.md           # 本地工具笔记
├── MEMORY.md          # 长期记忆（核心）
├── HEARTBEAT.md       # 心跳任务清单
└── memory/            # 日记忆目录
    ├── 2026-03-26.md
    ├── 2026-03-25.md
    └── ...

2.2 最小可用配置

编辑 ~/.openclaw/openclaw.json：

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "memorySearch": {
        "enabled": true,
        "provider": "gemini",  // 或 "openai"
        "model": "gemini-embedding-001",
        "remote": {
          "apiKey": "${GEMINI_API_KEY}"
        }
      }
    }
  }
}

环境变量设置（添加到 ~/.zshrc 或 ~/.bashrc）：

exportGEMINI_API_KEY="your-gemini-api-key"
# 或
exportOPENAI_API_KEY="your-openai-api-key"

2.3 验证配置

# 检查记忆系统状态
openclawconfiggetmemory
# 测试记忆搜索（在对话中）
# 输入："记住我喜欢用 Go 语言写后端"
# 然后问："我之前说过喜欢用什么语言？"

三、进阶配置：三种生产级方案

方案 A：本地优先（隐私敏感场景）

适用场景：企业内网、隐私敏感数据、无互联网环境

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "local": {
          "modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",
          "modelCacheDir": "~/.openclaw/models"
        },
        "fallback": "none"  // 禁用远程回退
      }
    }
  }
}

安装步骤：

# 1. 安装依赖
pnpmapprove-builds
# 选择 node-llama-cpp
# 2. 重建原生模块
pnpmrebuildnode-llama-cpp
# 3. 首次运行会自动下载模型（约 600MB）

性能数据：

  • 模型大小：~600MB
  • 内存占用：~1.2GB
  • 索引速度：约 1000 tokens/秒（M1 Mac）
  • 搜索延迟：< 100ms

方案 B：混合搜索（推荐生产配置）

适用场景：需要兼顾语义理解和精确匹配的通用场景

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "gemini",
        "model": "gemini-embedding-2-preview",
        "outputDimensionality": 3072,
        "remote": {
          "apiKey": "${GEMINI_API_KEY}"
        },
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4,
            "mmr": {
              "enabled": true,
              "lambda": 0.7
            },
            "temporalDecay": {
              "enabled": true,
              "halfLifeDays": 30
            }
          }
        }
      }
    }
  }
}

核心特性：

特性
作用
配置要点
BM25 + 向量混合
同时匹配语义相似和关键词精确
vectorWeight: 0.7, textWeight: 0.3
MMR 重排序
避免结果重复，提升多样性
lambda: 0.7
（平衡相关性与多样性）
时间衰减
优先返回近期记忆
halfLifeDays: 30
（30 天衰减一半）

效果对比：

搜索 “home network setup”：

-纯向量搜索：返回 3 条关于路由器的笔记（内容重复）-混合搜索 + MMR：返回路由器配置、DNS 设置、VLAN 规划（覆盖全面）

方案 C：QMD 后端（大规模知识库）

适用场景：需要索引外部文档、大规模知识库、高级检索需求

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "command": "qmd",
      "searchMode": "vsearch",
      "includeDefaultMemory": true,
      "paths": [
        { "name": "docs", "path": "~/notes", "pattern": "**/*.md" },
        { "name": "wiki", "path": "/srv/team-wiki", "pattern": "**/*.md" }
      ],
      "update": {
        "interval": "5m",
        "debounceMs": 15000,
        "onBoot": true,
        "waitForBootSync": false
      },
      "limits": {
        "maxResults": 6,
        "timeoutMs": 4000
      }
    }
  }
}

安装 QMD：

# 方式 1：通过 Bun 安装buninstall-ghttps://github.com/tobi/qmd# 方式 2：下载预编译版本# 访问 https://github.com/tobi/qmd/releases# 验证安装qmd--version

QMD vs 内置后端对比：

特性
内置 SQLite
QMD
本地运行
✅
✅
外部文档索引
❌
✅
BM25 + 向量混合
✅
✅
重排序
✅
✅
查询扩展
❌
✅
首次搜索速度
快
慢（需下载模型）

四、实战技巧：让记忆系统更智能

4.1 记忆文件组织最佳实践

# MEMORY.md 结构示例
## 用户偏好
### 技术栈
- 后端：Go + Gin
- 前端：React + TypeScript
- 数据库：PostgreSQL
### 沟通风格
- 喜欢先结论后细节
- 讨厌术语堆砌
- 每次给三个可执行方案
## 项目上下文
### 当前项目：AI 助手平台
- 技术栈：Next.js + Python FastAPI
- 截止日期：2026-06-30
- 关键决策：使用 OpenClaw 作为底层框架
## 重要经验
### 2026-03 学到的教训
1. API 配额管理：免费版有严格限制
2. 环境变量：脚本执行需显式加载 ~/.zshrc

4.2 自动记忆维护（Heartbeat 配置）

编辑 HEARTBEAT.md：

# 记忆维护清单
## 每日检查
- [ ] 读取 memory/YYYY-MM-DD.md（今天 + 昨天）
- [ ] 检查是否有重要决策需要写入 MEMORY.md
## 每周维护（周日执行）
- [ ] 回顾本周 memory/ 文件
- [ ] 更新 MEMORY.md 长期记忆
- [ ] 清理过时的临时笔记

4.3 会话记忆搜索（实验性）

启用历史对话索引：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "experimental": {
          "sessionMemory": true
        },
        "sources": ["memory", "sessions"]
      }
    }
  }
}

注意：会话记忆默认关闭，需显式启用。

五、避坑指南：常见问题与解决方案

5.1 记忆搜索返回空结果

排查步骤：

# 1. 检查记忆后端状态
openclawconfiggetmemory
# 2. 验证 API 密钥
openclawauthlist
# 3. 检查记忆文件是否存在
ls-la~/.openclaw/workspace/memory/
# 4. 查看索引状态（QMD 后端）
qmdcollectionlist

常见原因：

  • API 密钥未设置或过期
  • 记忆文件为空或格式错误
  • 索引尚未完成（首次启动需要时间）

5.2 切换嵌入模型后需要重新索引

# 删除旧索引（会自动重建）
rm~/.openclaw/memory/*.sqlite
# 重启 Gateway
openclawgatewayrestart

5.3 群聊中记忆搜索不工作

默认情况下，MEMORY.md 只在私聊中加载。如需在群聊中使用记忆搜索：

{
  "memory": {
    "qmd": {
      "scope": {
        "default": "allow"  // 或配置具体规则
      }
    }
  }
}

六、性能优化与监控

6.1 索引性能调优

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "sync": {
          "watch": true,  // 监听文件变化
          "debounceMs": 1500  // 防抖延迟
        },
        "cache": {
          "enabled": true,
          "maxEntries": 50000  // 嵌入缓存条目数
        }
      }
    }
  }
}

6.2 批量索引（大规模数据）

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "remote": {
          "batch": {
            "enabled": true,
            "concurrency": 2,
            "wait": true
          }
        }
      }
    }
  }
}

OpenAI Batch API 优势：

  • 价格比同步请求低 50%
  • 适合大规模历史数据索引
  • 异步处理，不阻塞对话

七、总结与行动清单

三种配置方案速查

场景
推荐方案
关键配置
个人用户快速开始
基础配置
provider: "gemini"
企业隐私敏感
本地优先
provider: "local"
通用生产环境
混合搜索
hybrid.enabled: true
大规模知识库
QMD 后端
backend: "qmd"

立即行动

1.今天：复制基础配置，设置 API 密钥，测试记忆功能2.本周：整理 MEMORY.md 长期记忆文件3.本月：根据使用场景选择进阶方案，优化搜索体验

参考资源

  • OpenClaw 官方文档 - Memory
  • QMD 项目
  • Gemini Embeddings API
  • OpenAI Embeddings API