OpenClaw 核心配置文件：MEMORY.md — 长期记忆与检索

置顶 | 发表于 | 分类于

我们在使用 OpenClaw 时都有过这样的困惑：明明安装了许多强大的 Skills（技能），API 也是最贵的，但代理的表现却依然笨拙，只能被动响应，无法主动思考，甚至经常重复提问。这并不一定是大模型本身的能力不足，也不是插件质量问题，核心原因在于忽略了系统底层的“灵魂”配置。真正决定 OpenClaw 智商上限的，不是昂贵的模型调用，而是那些藏在 /.openclaw/workspace/ 目录下不起眼的 .md 配置文件。本文将深入拆解这些核心文件的功能与配置逻辑，带你通过修改底层配置，彻底告别 AI 代理的机械感。
OpenClaw 的所有核心逻辑都存储在工作空间目录(**/.openclaw/workspace/** )下。如果不熟悉命令行界面的话，也可以在 Web UI 中查看和编辑。位置如下图：
alt text
打开这个目录，我们会看到如下层级的文件结构，每个文件都承担着不同的职责：

  • AGENTS.md：LLM的工作手册，代理调度规则与标准作业程序。
  • BOOTSTRAP.md：初始化序列与核心系统提示词。
  • HEARTBEAT.md：定时执行逻辑与主动任务状态自检。
  • IDENTITY.md：代理身份定义与系统边界约束。
  • MEMORY.md：长期上下文数据与既定规则的持久化存储。
  • SOUL.md：LLM的性格，响应语气、行为特征及输出格式配置。
  • TOOLS.md：工具授权注册表及调用参数规范。
  • USER.md：用户(你的)画像数据，包含特定偏好与交互限制配置。
  • memory/：存储日常运行日志与短期上下文。
  • skills/：已安装的第三方技能扩展目录。
    今天我们介绍 MEMORY.md 文件，这是 OpenClaw 的核心文件。

什么是 MEMORY.md？

MEMORY.md 是 OpenClaw 的长期记忆中枢。代理表现“不聪明”往往并非模型不够强，而是记忆策略未配置好：重要信息未持久化、检索召回不稳定、历史无法跨会话复用。下文集中说明记录内容、memory_search / memory_get、索引与混合检索、压缩前的 memoryFlush，以及运维与安全要点。

与相关文件的分工

  • USER.md：偏静态画像，由你手动维护的偏好与约束。
  • MEMORY.md：偏动态事实，由对话沉淀的项目背景、决策与待办。
  • memory/：按日期或任务拆分的短期/过程型笔记，可与 MEMORY.md 搭配使用。
    一句话：USER 是你写死的“人设”，MEMORY 是长出来的“经历”。

MEMORY.md 记录什么

建议只保留“跨会话仍有价值”的信息：

  • 用户偏好：表达风格、禁忌、常用语言
  • 项目背景：仓库结构、关键命令、部署约定
  • 决策结论：为什么采用某方案，何时变更
  • 历史状态：已解决问题、阻塞点、待办跟踪
  • 环境信息：关键路径、依赖版本、常见故障
    示例结构：
1
2
3
4
5
6
7
8
9
10
11
12
# MEMORY.md
## 用户偏好
- 回复先结论后细节
- 文档中保留可复制命令
## 当前项目
- 项目：openclaw-docs
- 技术栈：TypeScript + React
- 发布方式：GitHub Pages + CI
## 关键决策
- 2026-03-01：记忆检索改为混合搜索（BM25 + 向量）
## 待办
- [ ] 补充 memory_search 参数说明

记忆工具协同

  • 从 MEMORY.md、memory/**/*.md 以及 memorySearch.extraPaths 中做语义检索
  • 按块检索并返回片段（不是整篇），包含路径、行范围、分数等元数据
  • 默认不会阻塞索引；后台同步未完成时，结果可能有轻微延迟

memory_get

  • 读取指定记忆文件内容（可按起始行和行数读取）
  • 默认只允许访问记忆域文件；额外路径需在 extraPaths 中显式声明
    工具启用前提：memorySearch.enabled = true。

索引范围、存储与刷新

索引范围

  • 仅索引 Markdown 文件
  • 默认来源：
    • MEMORY.md
    • memory/**/*.md
    • memorySearch.extraPaths 下的 .md

索引存储

  • 每个代理独立 SQLite 索引（避免代理间记忆串扰）
  • 可通过 agents.defaults.memorySearch.store.path 自定义，支持 {agentId} 占位

刷新触发

  • 监视记忆文件变更，去抖动后异步更新
  • 会话开始、检索触发、定时任务都可能触发同步
  • 当嵌入提供商、模型、端点指纹或分块参数改变时，会自动重建索引

会话压缩前的记忆冲刷

当上下文接近压缩阈值，可先触发一次静默记忆写入，把高价值信息落盘：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

要点：

  • 每个压缩周期最多触发一次
  • 工作区只读时会跳过
  • 默认静默（通常返回 NO_REPLY）

向量检索与提供商选择

如果未显式配置 memorySearch.provider，通常按以下顺序选择：

  1. local.modelPath 可用时走本地
  2. 可解析 OpenAI 密钥时走 OpenAI
  3. 可解析 Gemini 密钥时走 Gemini
  4. 都不可用则保持禁用
    本地模式基于 node-llama-cpp，可能需要执行：
  • pnpm approve-builds
  • pnpm rebuild node-llama-cpp

混合搜索（BM25 + 向量）

纯向量适合语义近义召回，BM25 擅长精确 token（ID、变量名、报错字符串）。混合搜索能同时覆盖“自然语言提问”和“精确定位”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4
          }
        }
      }
    }
  }
}

实践建议：

  • 初始权重可从 0.7 / 0.3 起步
  • 代码检索场景可适当提高 textWeight
  • 如果平台缺少 FTS5，系统应退化到纯向量而非硬失败

性能优化（缓存、sqlite-vec、会话索引）

嵌入缓存

1
2
3
4
5
6
7
8
9
10
11
12
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "cache": {
          "enabled": true,
          "maxEntries": 50000
        }
      }
    }
  }
}

作用：避免重复嵌入未改动文本，显著降低增量更新成本。

SQLite 向量加速（sqlite-vec）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "store": {
          "vector": {
            "enabled": true,
            "extensionPath": "/path/to/sqlite-vec"
          }
        }
      }
    }
  }
}

扩展不可用时，应自动回退到进程内相似度计算。

会话记忆索引（实验性）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "experimental": { "sessionMemory": true },
        "sources": ["memory", "sessions"],
        "sync": {
          "sessions": {
            "deltaBytes": 100000,
            "deltaMessages": 50
          }
        }
      }
    }
  }
}

说明：会话索引默认应视为可选能力，按代理隔离，且后台异步更新。

额外记忆路径

当团队文档不在默认目录时，可显式扩展：

1
2
3
4
5
6
7
8
9
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "extraPaths": ["../team-docs", "/srv/shared-notes/overview.md"]
      }
    }
  }
}

建议：

  • 路径尽量收敛，避免索引噪音
  • 仅纳入高价值 Markdown 文档
  • 避免把高敏感内容加入共享检索域

运维与安全

  • 隐私优先：记忆文件可能含个人或业务敏感信息
  • 定期整理：删除过期事实，保留稳定结论
  • 纠错要快：记忆写错后应第一时间手动修正
  • 按代理隔离：不同角色代理使用独立工作区
  • Git 审慎：默认不建议把私有记忆纳入公共仓库

推荐优化流程

  1. 先规范 MEMORY.md 章节结构（偏好、项目、决策、待办）
  2. 开启 memoryFlush，保证压缩前关键信息落盘
  3. 开启混合检索并设置缓存
  4. 根据场景调 vectorWeight/textWeight
  5. 每周做一次记忆审计（去重、纠错、删旧）
    做到这 5 步后，OpenClaw 的“连续性”和“可协作性”通常会有明显提升。
-------------本文结束感谢您的阅读-------------