agent-wal

用于代理状态持久性的预写日志协议。防止在对话压缩期间丢失更正、决策和上下文。在以下情况下使用：(1) 收到用户更正 - 在响应之前将其记录下来，(2) 做出重要的决定或分析 - 在继续之前将其记录下来，(3) 预压缩内存刷新 - 将工作缓冲区刷新到 WAL，(4) 会话启动 - 重播未应用的 WAL 条目以恢复丢失的上下文，(5) 任何时候您想要确保某些内容在压缩中幸存下来。

## 概述（中文）

用于代理状态持久性的预写日志协议。防止在对话压缩期间丢失更正、决策和上下文。在以下情况下使用：(1) 收到用户更正 - 在响应之前将其记录下来，(2) 做出重要的决定或分析 - 在继续之前将其记录下来，(3) 预压缩内存刷新 - 将工作缓冲区刷新到 WAL，(4) 会话启动 - 重播未应用的 WAL 条目以恢复丢失的上下文，(5) 任何时候您想要确保某些内容在压缩中幸存下来。

## 原文

# Agent WAL (Write-Ahead Log)

Write important state to disk **before** responding. Prevents the #1 agent failure mode: losing corrections and context during compaction.

## Core Rule

**Write before you respond.** If something is worth remembering, WAL it first.

## When to WAL

| Trigger | Action Type | Example |
|---------|------------|---------|
| User corrects you | `correction` | "No, use Podman not Docker" |
| You make a key decision | `decision` | "Using CogVideoX-2B for text-to-video" |
| Important analysis/conclusion | `analysis` | "WAL/VFM patterns should be core infra not skills" |
| State change | `state_change` | "GPU server SSH key auth configured" |
| User says "remember this" | `correction` | Whatever they said |

## Commands

All commands via `scripts/wal.py` (relative to this skill directory):

```bash
# Write before responding
python3 scripts/wal.py append agent1 correction "Use Podman not Docker for all EvoClaw tooling"
python3 scripts/wal.py append agent1 decision "CogVideoX-5B with multi-GPU via accelerate"
python3 scripts/wal.py append agent1 analysis "Signed constraints prevent genome tampering"

# Working buffer (batch writes during conversation, flush before compaction)
python3 scripts/wal.py buffer-add agent1 decision "Some decision"
python3 scripts/wal.py flush-buffer agent1

# Session start: replay lost context
python3 scripts/wal.py replay agent1

# After applying a replayed entry
python3 scripts/wal.py mark-applied agent1 <entry_id>

# Maintenance
python3 scripts/wal.py status agent1
python3 scripts/wal.py prune agent1 --keep 50
```

## Integration Points

### On Session Start
1. Run `replay` to get unapplied entries
2. Read the summary into your context
3. Mark entries as applied after incorporating them

### On User Correction
1. Run `append` with action_type `correction` BEFORE responding
2. Then respond with the corrected behavior

### On Pre-Compaction Flush
1. Run `flush-buffer` to persist any buffered entries
2. Then write to daily memory files as usual

### During Conversation
For less critical items, use `buffer-add` to batch writes. Buffer is flushed to WAL on `flush-buffer` (called during pre-compaction) or manually.

## Storage

WAL files: `~/clawd/memory/wal/<agent_id>.wal.jsonl`
Buffer files: `~/clawd/memory/wal/<agent_id>.buffer.jsonl`

Entries are append-only JSONL. Each entry:
```json
{"id": "abc123", "timestamp": "ISO8601", "agent_id": "agent1", "action_type": "correction", "payload": "Use Podman not Docker", "applied": false}
```