OpenClaw 的记忆是工作区中的纯 Markdown 文件。文件是唯一真相来源——模型只能「记住」写入磁盘的内容。本文深度解析这套记忆系统的工作原理和高级配置。
记忆文件双层架构
~/.openclaw/workspace/
├── MEMORY.md # 长期精华记忆（仅在主私人会话中加载）
└── memory/
├── 2026-03-10.md # 今日日志（启动时自动读取）
├── 2026-03-09.md # 昨日日志（启动时自动读取）
└── projects.md # 自定义常青文件（不受时间衰减影响）
| 文件 | 用途 | 加载时机 |
|---|---|---|
memory/YYYY-MM-DD.md | 日常日志（追加为主） | 每次 Session 启动时读取今天+昨天 |
MEMORY.md | 精华长期记忆 | 仅主私人 Session，绝不在群组中加载 |
两个核心工具
memory_search —— 语义召回，搜索相关笔记片段
memory_get —— 精准读取，按路径和行号获取内容
优化：
memory_get在文件不存在时优雅降级（返回空字符串），无需 try/catch 处理ENOENT。
何时写入记忆
- 决策、偏好、持久事实 → 写入
MEMORY.md - 日常笔记、运行上下文 → 写入
memory/YYYY-MM-DD.md - 有人说「记住这个」→ 立即写入文件（不要存在「脑子里」）
- 如果你想让 Agent 记住某事，让它写入记忆
自动记忆刷新（压缩前触发）
当 Session 接近自动压缩时，OpenClaw 会触发静默的 Agent 轮次，提醒模型在上下文被压缩前写入持久记忆：
json
{
"agents": {
"defaults": {
"compaction": {
"reserveTokensFloor": 20000,
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000,
"systemPrompt": "Session 即将压缩，现在保存持久记忆。",
"prompt": "将重要笔记写入 memory/YYYY-MM-DD.md；如无需保存，回复 NO_REPLY。"
}
}
}
}
}向量记忆搜索
OpenClaw 构建小型向量索引，支持语义查询（即使措辞不同也能找到相关笔记）。
嵌入提供商选择优先级
未配置 memorySearch.provider 时，自动选择：
- 本地模型（如配置了
local.modelPath） - OpenAI（有可用 Key）
- Gemini
- Voyage
- Mistral
- 否���禁用记忆搜索
Gemini 嵌入配置
json
{
"agents": {
"defaults": {
"memorySearch": {
"provider": "gemini",
"model": "gemini-embedding-001",
"remote": {
"apiKey": "YOUR_GEMINI_API_KEY"
}
}
}
}
}自定义 OpenAI 兼容端点
json
{
"agents": {
"defaults": {
"memorySearch": {
"provider": "openai",
"model": "text-embedding-3-small",
"remote": {
"baseUrl": "https://api.example.com/v1/",
"apiKey": "YOUR_API_KEY",
"headers": { "X-Custom-Header": "value" }
}
}
}
}
}混合检索（BM25 + 向量）
OpenClaw 结合两种检索信号：
| 方法 | 优势 | 劣势 |
|---|---|---|
| 向量搜索 | 理解语义（即使措辞不同） | 精确 Token 匹配较弱 |
| BM25 关键词 | 精确匹配 ID、代码符号、错误字符串 | 不理解同义词 |
| 混合（两者结合） | 兼顾语义和精确匹配 | — |
配置示例
json
{
"agents": {
"defaults": {
"memorySearch": {
"query": {
"hybrid": {
"enabled": true,
"vectorWeight": 0.7,
"textWeight": 0.3,
"candidateMultiplier": 4,
"mmr": {
"enabled": true,
"lambda": 0.7
},
"temporalDecay": {
"enabled": true,
"halfLifeDays": 30
}
}
}
}
}
}
}MMR 多样性重排序
MMR（最大边际相关性）解决搜索结果重复问题。
示例：搜索「家庭网络配置」时：
❌ 不用 MMR（重复结果）：
1. memory/2026-02-10.md 路由器 + VLAN 设置
2. memory/2026-02-08.md 路由器 + VLAN 设置（近似重复！）
3. memory/network.md 参考文档
✅ 使用 MMR（多样化结果）：
1. memory/2026-02-10.md 路由器 + VLAN（最相关）
2. memory/network.md 参考文档（多样化！）
3. memory/2026-02-05.md AdGuard DNS 配置（多样化！）
lambda 参数控制相关性与多样性的平衡：
1.0= 纯相关性（无多样性惩罚）0.0= 最大多样性- 默认
0.7（略偏向相关性）
时间衰减（让近期记忆更重要）
时间衰减解决「旧日志语义匹配更好但信息已过时」的问题：
decayedScore = score × e^(-λ × ageInDays)
默认半衰期 30 天效果：
- 今天：100% 原始分
- 7 天前：~84%
- 30 天前：50%
- 90 天前：12.5%
- 180 天前：~1.6%
永青文件不受时间衰减影响：MEMORY.md、非日期格式的 memory/*.md（如 memory/projects.md）
示例：搜索「Rod 的工作日程」时，时间衰减让 6 个月前的旧笔记排到底部，让今天的日程出现在顶部。
QMD 后端（实验性）
QMD 是结合 BM25 + 向量 + 重排序的本地优先搜索工具：
bash
# 安装 QMD
bun install -g https://github.com/tobi/qmdjson
{
"memory": {
"backend": "qmd",
"citations": "auto",
"qmd": {
"includeDefaultMemory": true,
"update": { "interval": "5m", "debounceMs": 15000 },
"limits": { "maxResults": 6, "timeoutMs": 4000 }
}
}
}注意：QMD 首次运行时会自动下载 GGUF 模型（约需几分钟），之后搜索速度很快。
扩展额外记忆路径
索引工作区之外的 Markdown 文件：
json
{
"agents": {
"defaults": {
"memorySearch": {
"extraPaths": ["../team-docs", "/srv/shared-notes/overview.md"]
}
}
}
}Session 记忆搜索（实验性）
将会话记录也加入记忆搜索索引：
json
{
"agents": {
"defaults": {
"memorySearch": {
"experimental": { "sessionMemory": true },
"sources": ["memory", "sessions"]
}
}
}
}嵌入缓存
缓存 Chunk 嵌入向量，避免未更改内容重复计算：
json
{
"agents": {
"defaults": {
"memorySearch": {
"cache": {
"enabled": true,
"maxEntries": 50000
}
}
}
}
}原文：Memory - OpenClaw | 来源：OpenClaw 官方文档