Agent WAL (Write-Ahead Log)

---

name: agent-wal

description: "Write-Ahead Log protocol for agent state persistence. Prevents losing corrections, decisions, and context during conversation compaction. Use when: (1) receiving a user correction — log it before responding, (2) making an important decision or analysis — log it before continuing, (3) pre-compaction memory flush — flush the working buffer to WAL, (4) session start — replay unapplied WAL entries to restore lost context, (5) any time you want to ensure something survives compaction."

---

# 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):

# 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:

{"id": "abc123", "timestamp": "ISO8601", "agent_id": "agent1", "action_type": "correction", "payload": "Use Podman not Docker", "applied": false}