Memory 记忆系统
Memory 是 OpenClaw 的持久化记忆系统。OpenClaw 通过写入本地 Markdown 文件来"记住"信息——模型只记住被保存到磁盘的内容，没有隐藏状态。这些记忆文件存储在 Agent 的工作空间中，可以跨会话保持，重启 Gateway 后依然存在。
为什么需要 Memory？
没有 Memory 的 AI 每次都像第一次认识你：
- 需要反复解释需求和偏好
- 上下文容易丢失
- 无法形成长期协作关系
有了 Memory 后：
- 一次配置，长期有效：重要信息只需告诉 Agent 一次
- 越用越懂你：Agent 会记住你的风格和习惯
- 跨会话保持：重启 Gateway 后记忆依然存在
- 语义搜索：配置嵌入向量后，支持智能检索相关记忆
工作空间文件结构
Agent 的工作空间（默认 ~/.openclaw/workspace）包含多个重要文件，共同构成完整的记忆和配置体系：
核心文件概览
| 文件 | 用途 | 自动创建 |
|---|---|---|
AGENTS.md | 操作指令 + 记忆（核心配置） | 是 |
SOUL.md | 人格定义、边界、语气 | 是 |
MEMORY.md | 向量搜索记忆库 | 否 |
TOOLS.md | 工具使用约定和偏好 | 否 |
USER.md | 用户档案和称呼偏好 | 否 |
IDENTITY.md | Agent 名称和形象 | 否 |
HEARTBEAT.md | 心跳任务专用上下文 | 否 |
BOOTSTRAP.md | 首次运行引导（完成后删除） | 首次创建 |
运行 openclaw setup 会自动创建这些文件的默认模板。
AGENTS.md（操作指令与记忆）
AGENTS.md 是最重要的配置文件，包含 Agent 的操作指令和记忆内容。它会被自动注入到系统提示词中，告诉 Agent 如何工作以及记住重要信息。
# 操作指令
## 核心职责
- 帮助用户完成代码编写、调试和重构
- 执行文件操作和 Shell 命令
- 浏览网页获取信息
## 工作习惯记忆
- 用户偏好使用 TypeScript
- 代码风格遵循 Prettier 配置
- 提交信息使用 Conventional Commits 格式
## 项目相关记忆
- 项目路径：~/projects/main-app
- 技术栈：React + Node.js + PostgreSQL
- 部署方式：Docker Compose
## 重要规则
- 修改代码前先备份
- 发送邮件前需要用户确认
- 重要操作记录到日志文件
AGENTS.md 的特点：
- 操作指令 + 记忆合一：既能指导 Agent 行为，也能存储重要事实
- 每次会话加载：内容会自动注入到系统提示词
- 用户可编辑：随时修改，立即生效
引导文件大小限制
当工作空间引导文件内容过长时，OpenClaw 会自动截断：
- 单文件最大字符数：
agents.defaults.bootstrapMaxChars（默认 20000） - 所有文件总字符数：
agents.defaults.bootstrapTotalMaxChars（默认 150000）
SOUL.md（人格定义）
SOUL.md 定义 Agent 的性格、边界和交流风格，塑造 Agent "是谁"。
# 你是谁
你是一位严谨但友好的技术助手，专注于帮助用户提高工作效率。
## 性格特点
- 专业但不刻板
- 解释清晰，避免过度简化
- 主动提供上下文和相关建议
## 语言风格
- 中文为主，技术术语保留英文
- 使用代码块展示示例
- 复杂概念分步骤解释
## 行为边界
- 不主动执行危险操作（如删除文件）
- 敏感操作需要用户确认
- 不泄露 API Key 等敏感信息
## 自我认知
- 我是用户的技术助手
- 我帮助用户解决问题
- 我尊重用户的工作习惯
SOUL.md vs AGENTS.md
| 文件 | 作用 | 内容类型 |
|---|---|---|
| SOUL.md | 定义 Agent 人格 | 性格、语气、边界 |
| AGENTS.md | 操作指令 + 记忆 | 工作规则、事实信息 |
简单理解：SOUL.md 定义"Agent 是什么样的人"，AGENTS.md 存储"Agent 如何工作以及记住什么"。
MEMORY.md（向量搜索记忆）
MEMORY.md 和 memory/ 目录下的文件支持语义搜索，适合存储大量需要检索的信息。
# 项目文档摘要
## API 设计
用户服务提供以下端点：
- POST /api/users - 创建用户
- GET /api/users/:id - 获取用户信息
- PUT /api/users/:id - 更新用户
数据库连接字符串格式：
`postgresql://user:pass@host:5432/dbname`
## 会议记录摘要
2026-04-01 产品评审会议：
- 决定优先开发移动端
- API v2 需要向后兼容
- 下次评审时间：2026-04-15
按日期记忆
memory/ 目录支持按日期组织记忆：
workspace/
├── MEMORY.md
└── memory/
├── 2026-04-01.md
├── 2026-04-02.md
└── 2026-04-03.md
这种方式适合存储临时性、按时间组织的信息，如每日任务、会议记录等。
记忆后端（Memory Backends）
OpenClaw 支持多种记忆后端，从简单的内置引擎到高级的本地搜索和云端记忆。
内置引擎（默认）
基于 SQLite 的默认后端，开箱即用，无需额外依赖。
核心特性
| 特性 | 说明 |
|---|---|
| 关键词搜索 | 通过 FTS5 全文索引，使用 BM25 评分 |
| 向量搜索 | 通过嵌入向量支持语义搜索 |
| 混合搜索 | 结合关键词和向量，提供最佳结果 |
| CJK 支持 | 通过 trigram 分词支持中日韩文字 |
支持的嵌入向量提供商
| 提供商 | ID | 自动检测 | 说明 |
|---|---|---|---|
| OpenAI | openai | 是 | 默认使用 text-embedding-3-small |
| Gemini | gemini | 是 | 支持多模态（图片 + 音频） |
| Voyage | voyage | 是 | |
| Mistral | mistral | 是 | |
| Ollama | ollama | 否 | 本地部署，需显式配置 |
| Local | local | 是（优先） | GGUF 模型，约 0.6 GB 下载 |
索引工作机制
OpenClaw 将 MEMORY.md 和 memory/*.md 文件索引为约 400 token 的块，并存储到每个 Agent 独立的 SQLite 数据库中。
- 索引位置：
~/.openclaw/memory/<agentId>.sqlite - 文件监控：记忆文件变更触发 1.5 秒防抖重新索引
- 自动重建：当嵌入向量提供商、模型或分块配置变更时，自动重建索引
- 手动重建：
openclaw memory index --force
配置示例
{
"agents": {
"defaults": {
"memorySearch": {
"provider": "openai",
"model": "text-embedding-3-small"
}
}
}
}
何时使用内置引擎
内置引擎适合大多数用户：
- 开箱即用，无需额外依赖
- 关键词和向量搜索都能很好处理
- 支持所有嵌入向量提供商
- 混合搜索结合两种检索方式的优势
QMD Memory Engine
QMD 是一个本地优先的搜索辅助程序，结合了 BM25、向量搜索和重排序功能。它作为独立进程与 OpenClaw 并行运行。
相比内置引擎的优势
| 功能 | 说明 |
|---|---|
| 重排序和查询扩展 | 提供更高质量的搜索结果 |
| 索引额外目录 | 可以索引项目文档、团队笔记等任意磁盘内容 |
| 索引会话记录 | 可以检索历史对话内容 |
| 完全本地 | 通过 Bun + node-llama-cpp 运行，自动下载 GGUF 模型 |
| 自动回退 | 如果 QMD 不可用，自动回退到内置引擎 |
先决条件
- 安装 QMD：
bun install -g @tobilu/qmd - SQLite 需要支持扩展（macOS：
brew install sqlite） - QMD 必须在 Gateway 的 PATH 中
- macOS 和 Linux 开箱即用，Windows 推荐使用 WSL2
启用 QMD
{
"memory": {
"backend": "qmd"
}
}
启用后，OpenClaw 会在 ~/.openclaw/agents/<agentId>/qmd/ 创建集合，自动管理 sidecar 生命周期。
首次使用注意事项
首次搜索可能较慢，因为 QMD 会自动下载 GGUF 模型（约 2 GB）用于重排序和查询扩展。可以提前预热：
qmd query "test"
搜索范围
默认情况下，QMD 搜索结果只在 DM 会话中返回（不包括群组或频道）。可以通过配置修改：
{
"memory": {
"qmd": {
"scope": "all"
}
}
}
引用来源
当 memory.citations 为 auto 或 on 时，搜索片段会包含 Source: <path#line> 页脚。设置为 off 可省略页脚。
何时使用 QMD
选择 QMD 的场景：
- 需要重排序获得更高质量的搜索结果
- 需要搜索项目文档或工作空间外的笔记
- 需要检索历史会话内容
- 需要完全本地的搜索，不依赖 API
索引额外路径：
让 QMD 搜索工作空间之外的目录：
{
"memory": {
"backend": "qmd",
"qmd": {
"paths": [
{ "name": "docs", "path": "~/notes", "pattern": "**/*.md" },
{ "name": "project", "path": "~/projects/main-app/docs" }
]
}
}
}
索引会话记录：
启用会话索引来检索历史对话：
{
"memory": {
"backend": "qmd",
"qmd": {
"sessions": {
"enabled": true,
"retentionDays": 30
}
}
}
}
何时使用 QMD：
- 需要重排序获得更高质量的搜索结果
- 需要搜索项目文档或工作空间外的笔记
- 需要检索历史会话内容
- 需要完全本地的搜索，不依赖 API
Honcho Memory
Honcho 是 AI 原生的跨会话记忆系统，支持用户建模、语义搜索和多 Agent 感知。
特点：
- 跨会话记忆持久化
- 用户建模和个性化
- 多 Agent 感知
- 语义搜索
通过插件安装：
openclaw plugins install @openclaw/honcho
记忆搜索配置
嵌入向量提供商
记忆搜索需要嵌入向量提供商来支持语义搜索。OpenClaw 会自动检测可用的提供商：
自动检测顺序：
local- 如果配置了本地模型路径openai- 如果有 OpenAI API Keygemini- 如果有 Gemini API Keyvoyage- 如果有 Voyage API Keymistral- 如果有 Mistral API Key
手动配置提供商：
{
"agents": {
"defaults": {
"memorySearch": {
"provider": "openai",
"model": "text-embedding-3-small"
}
}
}
}
API Key 环境变量：
| 提供商 | 环境变量 |
|---|---|
| OpenAI | OPENAI_API_KEY |
| Gemini | GEMINI_API_KEY |
| Voyage | VOYAGE_API_KEY |
| Mistral | MISTRAL_API_KEY |
混合搜索配置
混合搜索结合了向量相似度（语义含义）和 BM25（关键词匹配），提供更准确的搜索结果。
{
"agents": {
"defaults": {
"memorySearch": {
"query": {
"hybrid": {
"enabled": true,
"vectorWeight": 0.7,
"textWeight": 0.3,
"mmr": {
"enabled": true,
"lambda": 0.7
},
"temporalDecay": {
"enabled": true,
"halfLifeDays": 30
}
}
}
}
}
}
}
参数说明：
vectorWeight：向量搜索权重（0-1）textWeight：BM25 权重（0-1）mmr：最大边际相关性，增加结果多样性temporalDecay：时间衰减，较新的内容权重更高
多模态记忆（Gemini）
使用 Gemini Embedding 2 可以索引图片和音频：
{
"agents": {
"defaults": {
"memorySearch": {
"provider": "gemini",
"model": "gemini-embedding-2-preview",
"multimodal": {
"enabled": true,
"modalities": ["all"],
"maxFileBytes": 10000000
}
}
}
}
}
支持的格式：
- 图片：
.jpg,.jpeg,.png,.webp,.gif,.heic,.heif - 音频：
.mp3,.wav,.ogg,.opus,.m4a,.aac,.flac
索引额外路径
让记忆搜索索引工作空间之外的文件：
{
"agents": {
"defaults": {
"memorySearch": {
"extraPaths": [
"../team-docs",
"/srv/shared-notes"
]
}
}
}
}
自动记忆刷新
在压缩对话之前，OpenClaw 会运行一个静默回合，提醒 Agent 将重要上下文保存到记忆文件。这是默认启用，无需配置。
可以通过配置调整行为：
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": true
}
}
}
}
CLI 记忆命令
OpenClaw 提供专门的记忆管理命令：
# 查看记忆索引状态
openclaw memory status
# 重新索引记忆文件
openclaw memory index
# 语义搜索记忆
openclaw memory search "API 设计规范"
openclaw memory search --query "数据库连接配置"
其他配置文件
TOOLS.md（工具使用约定）
记录工具使用的偏好和约定：
# 工具使用约定
## 代码编辑
- 使用 4 空格缩进
- 字符串优先使用单引号
- 组件使用函数式写法
## Shell 命令
- 优先使用 npm 而非 yarn
- Git 提交前运行 lint
- 禁止使用 rm -rf 无确认
## 浏览器操作
- 截图保存到 ~/screenshots/
- 超时时间默认 30 秒
USER.md（用户档案）
记录用户个人信息：
# 用户档案
## 基本信息
- 称呼：张工
- 角色：全栈开发工程师
- 团队：产品研发部
## 偏好称呼
- 工作场景：张工
- 非正式场合：老张
## 时区
- Asia/Shanghai (UTC+8)
IDENTITY.md（Agent 身份）
定义 Agent 的名称和形象：
# Agent 身份
## 名称
Claw Assistant
## 形象
一只红色的龙虾，专业但亲切
## 表情符号
🦞
HEARTBEAT.md（心跳上下文）
心跳任务专用的轻量级上下文文件，仅在心跳运行时加载：
# 心跳检查
每次心跳时执行以下检查：
1. 检查系统资源使用情况
2. 查看是否有重要通知
3. 确认服务正常运行
记忆管理最佳实践
结构化组织
使用清晰的标题和层级组织记忆：
# 推荐的组织方式
## 项目配置
| 项目 | 路径 | 技术栈 |
|------|------|--------|
| alpha | ~/projects/alpha | React, Node.js |
| beta | ~/projects/beta | Vue, Python |
## 开发规范
- 代码风格：Prettier
- 提交格式：Conventional Commits
- 分支策略：GitFlow
## 重要 API Key 存放位置
- 使用 SecretRef 管理，不要写入文件
保持精简
记忆文件不是日记，只记录：
- 反复使用的信息
- 重要决策和约定
- 难以重新获取的知识
定期维护
# 检查工作空间状态
openclaw status
# 查看配置文件
cd ~/.openclaw/workspace
ls -la
定期清理：
- 删除过时信息
- 合并重复内容
- 归档历史记录到
memory/目录
敏感信息处理
不要在记忆文件中存储敏感信息：
# 错误示例 ❌
API Key: sk-xxxxx
密码: mypassword123
# 正确示例 ✓
API Key: 使用环境变量 ANTHROPIC_API_KEY
数据库密码: 使用 SecretRef 管理
使用 SecretRef 管理敏感信息：
{
"secrets": {
"providers": {
"env": {
"source": "env"
}
}
},
"agent": {
"model": {
"apiKey": {
"ref": {
"provider": "env",
"id": "ANTHROPIC_API_KEY"
}
}
}
}
}
文件位置汇总
| 文件 | 位置 | 说明 |
|---|---|---|
| AGENTS.md | ~/.openclaw/workspace/AGENTS.md | 操作指令 + 记忆 |
| SOUL.md | ~/.openclaw/workspace/SOUL.md | 人格定义 |
| MEMORY.md | ~/.openclaw/workspace/MEMORY.md | 向量搜索记忆 |
| TOOLS.md | ~/.openclaw/workspace/TOOLS.md | 工具使用约定 |
| USER.md | ~/.openclaw/workspace/USER.md | 用户档案 |
| IDENTITY.md | ~/.openclaw/workspace/IDENTITY.md | Agent 身份 |
| HEARTBEAT.md | ~/.openclaw/workspace/HEARTBEAT.md | 心跳上下文 |
| 日期记忆 | ~/.openclaw/workspace/memory/YYYY-MM-DD.md | 日记式记忆 |
| 索引存储 | ~/.openclaw/memory/{agentId}.sqlite | 搜索索引 |
多 Agent 记忆隔离
每个 Agent 有独立的工作空间，记忆完全隔离：
~/.openclaw/
├── workspace/ # main Agent 工作空间
│ ├── AGENTS.md
│ ├── SOUL.md
│ └── MEMORY.md
└── agents/
├── writer/ # writer Agent 工作空间
│ └── workspace/
│ ├── AGENTS.md
│ └── SOUL.md
└── developer/ # developer Agent 工作空间
└── workspace/
├── AGENTS.md
└── SOUL.md
每个 Agent 的记忆索引也相互独立，存储在各自的 SQLite 数据库中。
常见问题
记忆不生效
原因：文件路径错误或格式问题。
解决：
# 检查工作空间配置
openclaw config get agents.defaults.workspace
# 验证配置
openclaw doctor
# 检查记忆文件是否存在
ls ~/.openclaw/workspace/MEMORY.md
记忆搜索无结果
原因：未配置嵌入向量提供商或未建立索引。
解决：
# 检查记忆搜索状态
openclaw memory status
# 配置嵌入向量提供商
export OPENAI_API_KEY="sk-xxx"
# 重新索引
openclaw memory index --force
QMD 首次搜索很慢
原因：QMD 首次使用时会下载 GGUF 模型（约 2GB）。
解决：提前预热：
qmd query "test"
QMD 未找到
原因：QMD 不在 Gateway 的 PATH 中。
解决：创建符号链接：
# 如果 OpenClaw 作为服务运行
sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd
群聊中 QMD 结果为空
原因：默认搜索范围只允许 DM 会话。
解决：
{
"memory": {
"qmd": {
"scope": "all"
}
}
}
AGENTS.md 过大
原因：长期使用积累了大量信息。
解决：
- 将历史信息移到
memory/目录 - 使用 QMD 后端进行语义搜索，减少 AGENTS.md 内容
- 定期归档过时信息
- 调整
bootstrapMaxChars增加限制
搜索超时
原因：QMD 搜索超时（默认 4 秒）。
解决：
{
"memory": {
"qmd": {
"limits": {
"timeoutMs": 120000
}
}
}
}
记忆搜索被禁用
原因：未检测到嵌入向量提供商。
解决：
# 检查状态
openclaw memory status
# 设置提供商
export OPENAI_API_KEY="sk-xxx"
# 或在配置中显式设置
索引结果过时
原因：文件监控可能在罕见情况下遗漏变更。
解决：
openclaw memory index --force
sqlite-vec 未加载
原因：扩展加载失败。
解决：OpenClaw 会自动回退到进程内余弦相似度计算。检查日志了解具体加载错误。
下一步
- 定时任务 - 配合 Memory 实现自动化
- 多 Agent 协作 - 每个 Agent 有独立的 Memory
- 最佳实践 - 生产环境配置建议