Agent Wal

Write-Ahead Log protocol for agent state persistence. Prevents losing corrections, decisions, and context during conversation compaction. Use when: (1) recei...

Security Scan

The skill's code and runtime instructions align with its stated purpose (local write‑ahead logging for agent state); it reads/writes local JSONL files and does not request credentials, external network access, or unusual installs.

Purpose & Capability

Name/description describe a Write‑Ahead Log for agent persistence and the included script implements that behavior. The required files, commands, and storage locations (~/clawd/memory/wal) are consistent with the stated purpose.

Instruction Scope

SKILL.md instructs the agent to run local commands (scripts/wal.py) and to read/write local WAL and buffer files; it does not instruct the agent to access unrelated files, environment secrets, or external endpoints. Integration points and commands are narrowly scoped to WAL operations.

Install Mechanism

No install spec; the skill is instruction‑only with a bundled Python script. No downloads or package installs are performed. This is low risk and consistent with the skill's purpose.

Credentials

The skill declares no environment variables or credentials. The script uses HOME to place files under the user's home directory, which is proportional to a local persistence utility. There are no requests for unrelated secrets or external service keys.

Persistence & Privilege

always is false and the skill does not modify other skills or global agent configuration. It writes only to its own WAL directory under the user HOME, which is an expected level of persistence for a local logging helper.

Assessment

This skill is internally coherent and implements a local write‑ahead log. Before installing/use, consider: (1) sensitive data: anything you append will be stored in plaintext under ~/clawd/memory/wal — avoid appending secrets or encrypt the directory if needed; (2) file permissions: ensure the WAL directory is appropriately permissioned to prevent other users/processes from reading it; (3) backups/retention: the tool appends entries indefinitely unless pruned — plan retention and pruning to limit disk growth; (4) concurrency: simultaneous agent processes appending to the same file may cause races; test in your environment; (5) provenance: skill.toml version differs from registry metadata (1.0.0 vs 1.0.1) — minor but worth noting. Otherwise the behavior matches the description and there are no hidden network calls or credential requests.

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}