第6章记忆系统

一句话：OpenClaw 的记忆存储就是纯 Markdown 文件——没有外部数据库，搜索基于本地向量索引，简单但够用。

6.1 记忆的本质

OpenClaw 的记忆系统有一个极简的设计哲学：所有记忆都是 Markdown 文件。

没有 SQLite，没有 ChromaDB，没有 Pinecone——存储层就是 workspace 目录下的 .md 文件。你可以用任何文本编辑器打开它们，直接阅读、修改甚至删除。搜索基于向量索引，OpenClaw 会自动选择 embedding 提供商：优先使用远程 API（OpenAI、Gemini 等，需要 API Key），也可以配置 memorySearch.provider = "local" 使用本地模型（基于 node-llama-cpp）或使用 Ollama。

这意味着：

记忆完全透明——你随时能看到 Agent 记住了什么
记忆完全可控——你可以直接编辑记忆文件
备份和迁移——复制文件夹即可

6.2 两层记忆

MEMORY.md — 长期记忆

由 Agent 主动策展（curate）的核心信息。不同于流水账，MEMORY.md 保存的是经过筛选和整理的重要信息：

# Long-term Memory

## 用户偏好
- 编程语言偏好：TypeScript > Python > Go
- 编辑器：VS Code + Vim 键位
- 讨厌写注释，但接受 JSDoc

## 项目信息
- 主项目：电商后台管理系统（Next.js 14 + FastAPI）
- 数据库：PostgreSQL（2024-12 从 MySQL 迁移）
- 部署：AWS ECS + CloudFront

## 重要约定
- 代码风格：严格遵循 ESLint + Prettier
- Git 提交信息用英文
- PR 描述用中文

memory/ 目录 — 每日日记

Agent 在每天的对话中自动追加重要信息到当天的日志文件：

# 2024-12-15

## 14:23 - 数据库迁移
用户提到数据库从 MySQL 迁移到 PostgreSQL，需要更新所有 SQL 查询。

## 16:45 - 部署问题
用户的 Docker 镜像在 ARM64 上构建失败，改用 multi-platform build 解决。

## 18:00 - 明日计划
用户明天需要完成 API v2 的文档编写。

每日日记是 append-only（只追加不修改）的。

两者的区别

	MEMORY.md	memory/YYYY-MM-DD.md
写入方式	Agent 策展，可增删改	只追加
内容特点	精华、去重、结构化	流水账、按时间排列
生命周期	长期保留	按天滚动
类比	个人档案	工作日志

6.3 记忆工具

Agent 内置两个记忆相关工具：

工具	作用	使用场景
`memory_search`	语义搜索所有记忆文件	”我之前提过数据库迁移的事？“
`memory_get`	精确读取指定记忆文件	读取某天日志或 MEMORY.md

用户无需手动调用——Agent 在需要时自动使用。比如你问”上次讨论的那个 bug 修了吗？“，Agent 会自动调用 memory_search 查找相关记忆。

6.4 搜索配置

记忆搜索支持多种策略，可以组合使用获得最佳效果。

向量搜索

基于语义相似度的搜索，能找到意思相近但措辞不同的内容。例如搜”数据库迁移”能找到”我们把 MySQL 换成了 PostgreSQL”。

混合搜索（推荐）

结合向量（语义）+ BM25（关键词）匹配，兼顾理解力和精确度：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",  // local | openai | gemini | ollama
        query: {
          hybrid: {
            enabled: true,
            vectorWeight: 0.7,    // 语义权重
            textWeight: 0.3,      // 关键词权重
          },
        },
      },
    },
  },
}

为什么用混合搜索？

向量搜索：“Mac上跑Gateway” 能匹配到 “macOS部署”
关键词搜索：ERR_MODULE_NOT_FOUND 精确匹配错误信息
组合使用：两全其美

时间衰减

较新的记忆权重更高，模拟人类记忆的自然衰减：

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            temporalDecay: {
              enabled: true,
              halfLifeDays: 30,    // 30 天半衰期
            },
          },
        },
      },
    },
  },
}

时间	权重
今天	100%
7 天前	~84%
30 天前	50%
180 天前	~1.6%

注意：MEMORY.md 和非日期文件不受时间衰减影响（常青文件）。

排错提示：如果 Agent 好像”忘记”了某些事情，检查 memory/ 目录下对应日期的文件。如果信息在文件中但 Agent 没找到，可能是语义搜索没命中，尝试用更明确的关键词重新提问。

6.5 自动压缩刷新（Compaction Flush）

当会话的 token 消耗接近模型上限时，Agent 会自动执行 compaction flush：

将当前会话中的重要信息写入每日日志
如果有值得长期保留的信息，更新 MEMORY.md
清理较旧的上下文，释放 token 空间
整个过程对用户透明

关键点：写入记忆后释放上下文——这保证了即使在超长对话中，Agent 也不会”忘记”重要信息，因为它们已经被持久化到文件。

用户也可以手动触发：

/compact    ← 在聊天中发送

6.6 QMD 后端（高级）

对于有更高搜索质量需求的用户，OpenClaw 支持 QMD（Queryable Markdown）后端，提供更精确的语义搜索能力。这是可选的高级配置，默认的文件搜索对大多数用户已经足够。

6.7 记忆维护最佳实践

定期审查

# 查看 MEMORY.md 内容
cat ~/.openclaw/workspace/MEMORY.md

# 查看最近的每日日记
ls -la ~/.openclaw/workspace/memory/ | tail -10

手动编辑记忆

你可以直接编辑记忆文件来纠正 Agent 的认知：

# 修正长期记忆中的错误信息
vim ~/.openclaw/workspace/MEMORY.md

修改后在下次会话中发送 /new 开始新会话，Agent 就会使用更新后的记忆。

清理过期日记

长时间运行后，memory/ 目录会积累大量日记文件。可以定期清理较旧的：

# 删除 30 天前的日记（谨慎操作）
find ~/.openclaw/workspace/memory/ -name "*.md" -mtime +30 -delete

备份记忆

# 备份整个 workspace（包括记忆）
cp -r ~/.openclaw/workspace/ ~/backup/openclaw-workspace-$(date +%Y%m%d)/

6.8 小结

概念	说明
设计哲学	纯 Markdown 文件，透明可控
MEMORY.md	长期记忆，Agent 策展维护
memory/ 目录	每日日记，只追加不修改
memory_search	语义搜索工具，自动调用
memory_get	精确读取工具
Compaction Flush	自动压缩：写入记忆 → 释放上下文
维护	可直接编辑文件，备份即复制目录

下一章进入渠道接入——如何把 Agent 连接到各个聊天平台。

第6章 记忆系统