WAL Memory
Two-file system for session crash recovery. Survives gateway disconnects, provider outages, and context compaction. Co-designed with Gemini.
The Problem
OpenClaw agents lose state in two ways:
- 1. Compaction — context window fills, gets summarized, detail lost
- Session rollover — session dies (crash/disconnect/overload), new session starts cold with zero history
The Two Files
- -
memory/GOALS.md — The "why": current milestone, sprint tasks, architecture decisions. Updated manually at major milestones or end of session. STATE.log — The "what just happened": append-only WAL, auto-timestamped. Never edit manually. Written via state-log.js.
Setup
1. Install the logger script
Copy scripts/state-log.js to ~/clawd/scripts/state-log.js.
Test it:
CODEBLOCK0
2. Create GOALS.md
Copy assets/GOALS.template.md to ~/clawd/memory/GOALS.md. Fill in your current objective, sprint tasks, and key decisions. Keep it under 30 lines — this is the "why", not the "what".
3. Update AGENTS.md — Cold Boot Recovery Hook
Add this to your "Every Session" startup sequence:
CODEBLOCK1
4. Update HEARTBEAT.md — Safety Net Flush
Add this as the first step of every heartbeat:
CODEBLOCK2
This guarantees STATE.log has a timestamp even if the session crashes immediately after — you'll always know exactly when things flatlined.
The Logging Rule
After any meaningful action, run:
CODEBLOCK3
Categories:
- -
ACTION — file created, code edited, config changed - INLINECODE8 — pushed to production, service restarted
- INLINECODE9 — dispatched or agent task completed
- INLINECODE10 — milestone completed
- INLINECODE11 — bug or system fix applied
- INLINECODE12 — cold boot (always log this first)
- INLINECODE13 — interval ping
- INLINECODE14 — something failed
Examples:
CODEBLOCK4
Do NOT log: reads, searches, minor tool calls. Signal only.
Never log: passwords, API keys, tokens, or sensitive payloads — STATE.log is plaintext.
Recovery Protocol
On cold boot or post-compaction, first action is always:
CODEBLOCK5
File Details
- -
STATE.log lives at INLINECODE16 - Auto-rotates at 5MB (renames to
STATE.log.old, starts fresh) - Format: INLINECODE18
- Add
STATE.log to .gitignore — it may contain sensitive action descriptions, credentials referenced in log messages, or private task details. Do not commit it to source control unless you have reviewed its contents and are certain it contains no sensitive data.
WAL 内存
用于会话崩溃恢复的双文件系统。能够应对网关断开、服务商中断和上下文压缩。与 Gemini 共同设计。
问题
OpenClaw 代理在两种情况下会丢失状态：
- 1. 压缩 — 上下文窗口填满后被总结，细节丢失
- 会话切换 — 会话终止（崩溃/断开/过载），新会话从零开始，无历史记录
两个文件
- - memory/GOALS.md — 为什么：当前里程碑、冲刺任务、架构决策。在重大里程碑或会话结束时手动更新。
- STATE.log — 刚刚发生了什么：仅追加写入的 WAL，自动添加时间戳。切勿手动编辑。通过 state-log.js 写入。
设置
1. 安装日志脚本
将 scripts/state-log.js 复制到 ~/clawd/scripts/state-log.js。
测试：
bash
node ~/clawd/scripts/state-log.js STARTUP WAL memory system initialized
应输出：Logged: STARTUP
STATE.log 应出现在 ~/clawd/ 中
2. 创建 GOALS.md
将 assets/GOALS.template.md 复制到 ~/clawd/memory/GOALS.md。填写当前目标、冲刺任务和关键决策。保持在 30 行以内 — 这是为什么，不是是什么。
3. 更新 AGENTS.md — 冷启动恢复钩子
将以下内容添加到每次会话启动序列中：
markdown
每次会话 — 冷启动恢复钩子
- 1. 读取 memory/GOALS.md — 当前任务和进行中的事项
- 运行 tail -n 20 ~/clawd/STATE.log — 最近 20 个操作，了解上次中断的位置
- 读取今天的 memory/YYYY-MM-DD.md 获取近期上下文
4. 更新 HEARTBEAT.md — 安全网刷新
将以下内容作为每次心跳的第一步：
bash
node ~/clawd/scripts/state-log.js HEARTBEAT Interval reached $(date +%Y-%m-%d %H:%M)
这确保即使会话在之后立即崩溃，STATE.log 也有时间戳 — 你总能确切知道系统何时停止运行。
日志记录规则
在任何有意义的操作之后，运行：
bash
node ~/clawd/scripts/state-log.js CATEGORY What you just did
分类：
- - ACTION — 文件创建、代码编辑、配置更改
- DEPLOY — 推送到生产环境、服务重启
- AGENT — 代理派遣或代理任务完成
- TASK — 里程碑完成
- FIX — 错误或系统修复
- STARTUP — 冷启动（始终先记录此项）
- HEARTBEAT — 间隔心跳
- ERROR — 发生故障
示例：
bash
node ~/clawd/scripts/state-log.js AGENT Dispatched Owsley to build auth system
node ~/clawd/scripts/state-log.js DEPLOY FF ElasticSearch secured, 6027 docs indexed
node ~/clawd/scripts/state-log.js FIX Cron syntax fixed — was using session spawn, now uses agent --deliver
不要记录： 读取、搜索、次要工具调用。仅记录信号。
切勿记录： 密码、API 密钥、令牌或敏感负载 — STATE.log 是纯文本。
恢复协议
在冷启动或压缩后，第一步始终是：
bash
1. 读取为什么
cat ~/clawd/memory/GOALS.md
2. 读取刚刚发生了什么
tail -n 20 ~/clawd/STATE.log
3. 从最后一条日志条目继续
文件详情
- - STATE.log 位于 ~/clawd/STATE.log
- 自动轮转，大小为 5MB（重命名为 STATE.log.old，重新开始）
- 格式：[2026-03-03T09:00:00.000Z] [CATEGORY] Message
- 将 STATE.log 添加到 .gitignore — 它可能包含敏感操作描述、日志消息中引用的凭据或私人任务细节。除非你已审查其内容并确定不包含敏感数据，否则不要将其提交到源代码管理。
