智能体记忆系统配置

为任意 OpenClaw 智能体构建完整的三层记忆系统。包含目录结构、记忆文件、语义搜索及上下文压缩功能。

快速开始

# 1. 运行配置脚本
bash scripts/setup_memory.sh /path/to/workspace

# 2. 将 AGENTS.md 模板复制到工作区
# （阅读 references/AGENTS_TEMPLATE.md，按需调整后写入 workspace/AGENTS.md）

# 3. 在 openclaw.json 中添加配置（详见下方第 3 步中的确切 JSON 内容）

# 4. 重启
openclaw gateway restart

完整细节请参阅下方各章节。

不建议使用本技能的场景

• 备份或导出记忆 — 本技能仅用于初始化记忆系统，不处理备份/迁移任务
• 记忆系统已配置完成 — 请直接运行第 4 步中的验证清单，无需重复执行配置流程
• 调试特定记忆问题 — 请直接查阅“故障排除”章节
• 修改记忆层级的内容 — 这属于智能体在常规运行期间的职责，而非配置任务

前置条件

运行配置前，请确保满足以下条件：

• OpenClaw CLI 已安装并位于系统 PATH 中（执行 openclaw --version 可验证）。若未安装，配置脚本仍将创建目录与记忆文件，但插件安装和配置修改需手动完成。
• Python 3.8+（仅 QMD 所需，可选）。通过 python3 --version 验证。QMD 提供对记忆文件的语义搜索能力（memory_search）。核心记忆系统（含层级划分、每日日志、Lossless Claw）在无 QMD 时仍可完全运行。若您无法安装 QMD（如服务器无 Python 或受限制），将仅失去语义搜索功能，其余一切保持不变。
• Node.js 18+（用于 OpenClaw 和 Lossless Claw 插件）。

平台说明

• Linux：完全支持，无需额外注意事项。
• macOS：完全支持。配置文件路径为 ~/.openclaw/openclaw.json（与 Linux 相同）。配置脚本使用 POSIX 兼容的 date 和 mkdir 命令，不依赖 GNU 特有参数。
• Windows（WSL2）：通过 WSL2（Ubuntu 或类似发行版）支持。所有操作须在 WSL 内执行，不可从 Windows CMD/PowerShell 启动。注意事项：若您的工作区位于 Windows 挂载驱动器上（例如 /mnt/c/...），文件权限行为可能异常；建议使用 WSL 文件系统内的路径（如 ~/workspace）以确保权限管理可靠。脚本中使用的 set -euo pipefail 和 mkdir -p 在 WSL2 下运行正常。
• Windows（原生）：不支持。OpenClaw 依赖 Unix shell 环境。

配置步骤

第 1 步：运行配置脚本

bash scripts/setup_memory.sh /path/to/agent/workspace

该脚本将创建以下内容：

• memory/、memory/hot/、memory/warm/ 目录
• memory/hot/HOT_MEMORY.md（当前会话状态）
• memory/warm/WARM_MEMORY.md（稳定配置与偏好设置）
• MEMORY.md（长期归档）
• memory/YYYY-MM-DD.md（当日每日日志）
• memory/heartbeat-state.json（心跳状态追踪）

脚本还会检查 QMD 和 Lossless Claw 是否已安装，并在可行时自动安装。

第 2 步：复制 AGENTS.md 模板

阅读 references/AGENTS_TEMPLATE.md，并将其内容写入智能体工作区，保存为 AGENTS.md。

需自定义的部分：

• 心跳部分 —— 根据智能体所属领域调整检查项（例如：CFO 智能体检查成本，营销智能体检查社交指标，DevOps 智能体检查 CI 流水线）
• HEARTBEAT.md —— 编写一份针对该智能体角色的周期性任务小清单
• 记忆层级描述 —— 若智能体无特殊记忆模式，请保持默认内容不变

应保持默认的部分：

• 会话启动流程（读取 SOUL.md、USER.md 及各类记忆文件）
• 记忆分层说明（HOT/WARM/COLD 流程）
• “Write It Down” 与 “No Mental Notes” 章节
• MEMORY.md 的安全规则（仅主会话可写）

第 3 步：配置 openclaw.json

在 agents.defaults（或对应智能体的专属配置）中添加以下字段：

"memorySearch": { "provider": "local" },
"compaction": { "mode": "safeguard" },
"contextPruning": { "mode": "cache-ttl", "ttl": "1h" },
"heartbeat": { "every": "1h" }

各配置项作用说明：

为智能体启用以下插件：

"session-memory": { "enabled": true },
"bootstrap-extra-files": { "enabled": true },
"lossless-claw": { "enabled": true }

各插件功能说明：

手动安装插件（若配置脚本未自动完成）：

pip install qmd                # 或：pipx install qmd / brew install qmd
openclaw plugins install @martian-engineering/lossless-claw

第 4 步：重启并验证

openclaw gateway restart

验证清单 —— 逐项执行并确认结果：

# 1. 记忆目录存在
ls -d memory/ memory/hot/ memory/warm/

# 2. 记忆文件存在
ls memory/hot/HOT_MEMORY.md memory/warm/WARM_MEMORY.md MEMORY.md memory/heartbeat-state.json

# 3. 当日每日日志存在
ls memory/$(date +%Y-%m-%d).md

# 4. QMD 已安装
qmd --version

# 5. Lossless Claw 插件已启用
openclaw plugins list | grep lossless-claw

# 6. AGENTS.md 已就位
head -5 AGENTS.md

# 7. 配置已生效（检查 openclaw.json）
grep -c "memorySearch|compaction|contextPruning|lossless-claw" ~/.openclaw/openclaw.json

若任一检查失败，请参阅下方“故障排除”章节。

迁移已有记忆

若您此前已存在 MEMORY.md 或历史每日日志，请按以下步骤迁移：

1. 正常运行配置脚本 —— 脚本会对每个文件执行 if [ ! -f ] 判断，仅在目标文件不存在时才创建，因此您的现有文件将被完整保留。
2. 重新组织现有内容至对应层级：
   • 将 MEMORY.md 中的活跃/临时上下文迁移至 memory/hot/HOT_MEMORY.md
   • 将稳定的偏好设置、API 参考、重复性配置迁移至 memory/warm/WARM_MEMORY.md
   • 将长期决策、里程碑事件、经验教训保留在 MEMORY.md（COLD 层级）中
3. 已有每日日志 可保留在 memory/ 目录下，系统默认即从此处读取。

恢复方案

记忆文件损坏：删除损坏文件，然后重新运行 bash scripts/setup_memory.sh /path/to/workspace。脚本仅创建不存在的文件，其余记忆文件均不受影响。您也可参考脚本中的模板头手动重建该文件。

AGENTS.md 丢失或被删除：从 references/AGENTS_TEMPLATE.md 重新复制并按需定制。

openclaw.json 配置损坏：从备份中恢复（配置脚本不会修改 openclaw.json，所有配置变更均为手动操作）。若无备份，请参照上方第 3 步重新添加配置。

通用原则：配置脚本可安全重复运行，绝不会覆盖已存在的文件。

配置完成后使用 Lossless Claw

安装完成后，Lossless Claw 将自动运行：

1. 压缩过程全自动 —— 随着对话不断增长，旧消息将在后台自动压缩为摘要。
2. 智能体按需检索上下文，使用如下工具：
   • lcm_expand —— 将压缩后的摘要还原为原始消息
   • lcm_grep —— 使用正则表达式或文本在整个压缩历史中搜索
   • lcm_expand_query —— 提出问题，从压缩上下文中获取答案
3. 无需修改智能体代码 —— 只要智能体具备 lcm_* 工具访问权限（OpenClaw 默认支持），即可检索所有已被压缩的内容。
4. AGENTS.md 指导智能体操作 —— 要求智能体在压缩刷新前更新 HOT_MEMORY，从而确保关键运行状态即使在上下文裁剪后仍得以保留。

各记忆层级运作机制

各层级具体示例

🔥 HOT —— “当前正在为客户 X 排查认证流程问题。等待 Bob 提供 API 密钥。下一步：密钥到位后测试接口。”

🌡️ WARM —— “用户偏好项目符号列表而非段落。Slack 工作区为 #eng-team。API 限流为每分钟 100 次请求。时间戳一律使用 UTC。”

❄️ COLD —— “2025-03-15：完成 v1 至 v2 API 迁移。关键经验：始终锁定依赖版本。决策：采用主干开发模式（trunk-based development）。”

每日日志（memory/YYYY-MM-DD.md）记录原始会话事件。智能体将定期回顾这些日志，并将重要条目提升至 COLD 层级。

多智能体与多上下文工作区

共享工作区（多个智能体共用一个目录）

• HOT_MEMORY 为共享资源 —— 所有智能体均可读取。切勿在此存放智能体专属调试上下文（例如：“当前任务：修复认证 Bug”），否则其他智能体（包括语音/头像智能体）可能误读并过度关注该内容。
• HOT_MEMORY 应保持通用性 —— 仅用于一般性状态，例如：“用户正在开会至下午 3 点”或“部署冻结至本周五”。
• 每日日志同样共享 —— 多个智能体向同一 memory/YYYY-MM-DD.md 写入时，应在每条记录前添加自身名称以避免混淆。
• WARM 与 COLD 通常安全 —— 偏好设置与长期记忆通常适用于所有智能体。

独立上下文（单个智能体服务多个领域）

每个 OpenClaw 智能体映射一个工作区。若您需要隔离的记忆上下文（例如工作 vs. 个人）：

• 选项 A：部署两个独立智能体 —— 各自拥有独立工作区与记忆系统，实现最彻底的隔离。
• 选项 B：利用 WARM 记忆实现上下文切换 —— 在 WARM_MEMORY 中维护多个上下文（如“工作”与“个人”章节），依据对话内容动态切换焦点。
• 选项 C：分离记忆子目录 —— 创建 memory/work/ 和 memory/personal/ 子目录，分别配备独立的 HOT 文件，并在 AGENTS.md 中指示智能体根据上下文选择对应文件。此为进阶方案，需定制 AGENTS.md 逻辑。

长期维护

每日日志随时间持续增长。 每日生成一个新文件 memory/YYYY-MM-DD.md。一年内将累积约 365 个小型文件。该设计通常无问题（每个文件体积较小，通常为 1–10 KB），但对于长期运行的智能体：

• 归档旧日志：将超过 90 天的日志移至 memory/archive/，以维持主 memory/ 目录的扫描效率。若已配置，QMD 仍可索引归档目录。
• 智能体负责内容提升：在心跳检查期间，智能体会回顾每日日志并将重要内容提升至 COLD（MEMORY.md）。一旦提升完成，对应日志即转为只读参考。
• 磁盘占用可控：即使积累多年日志，总体磁盘用量也仅达数十 MB 级别。Lossless Claw 生成的摘要由插件独立存储并自动管理。

故障排除