A Write-Ahead Log for AI Agents
Have an agent record what it is about to do before it does it, in an append-only file that survives crashes and refuses secrets.
Answer first
A write-ahead log for an agent is an append-only file in which the agent records what it is about to do, before it does it, and what happened afterwards. Make it a plain file with one JSON record per line, flushed to disk on every write, readable by a person, refusing anything that looks like a credential, and repairable after a crash. Add a nudge for the case where an agent edits dozens of lines without leaving a note. It will not resume work for you, but it gives the next session or the next human a trustworthy record of intent to resume from.
Why intent first
Databases write the intended change to a log before applying it, so that after a crash the system knows what was in flight (PostgreSQL describes the idea). An agent has the same problem at a different level. Sessions end, contexts are compacted, processes get stopped, and the next session knows only what was written down.
The failure we built this for: an agent made nine fixes across two files and left no journal entry at all. The commit-time check that was supposed to catch missing notes never fired, because the work had not been committed yet. Automatic hook records existed, but the harness documentation is explicit about what they prove: a hook entry shows that a tool was attempted, not that the scope or the decision was sound.
What the log holds
Two kinds of rows, written differently:
- Metadata rows from hooks. Before a write-capable tool runs, a hook records the tool name, the tool-use id and a character count of the target. It never records the content, so a file body never reaches the log.
- Human-readable notes from the agent. Short entries with an event name such as intent, scope, decision, check, commit, blocker or handoff. Intent goes in before the action. Results follow after the focused check.
Keep notes factual and redacted. No secrets, no personal data, no full prompts.
Making the file trustworthy
Properties worth copying, all read from the harness source at commit 504d930 or exercised in the lab below:
- Append-only, one record per line. A reader can parse each line independently.
- Flushed on every write (
fsync) and guarded by a file lock, so two writers do not interleave a line. - Private. File mode 0600, directories 0700, and the writer refuses symbolic links and hard links so it cannot be redirected into another file.
- Torn-tail repair. If a writer is stopped mid-line, the next append truncates the unterminated fragment under the lock. It refuses if the damaged tail is larger than a 64 KiB scan budget, rather than guess.
- Secret refusal. A note that looks like a credential is rejected and nothing is written.
A cadence nudge for the notes nobody writes
Rules are weakest where an agent is busiest. The harness has a check, labelled W04, that fires when a session stops with at least 40 changed source lines uncommitted and no human-readable entry in the last 20 minutes. It blocks once per diff, not repeatedly, and applies at stop time in a linked worktree. Per the source, it can be switched off with an environment variable; we did not test the off switch. It nudges; it does not write the note for you.
Resuming
Read the log, then the repository state, then any unfinished work. In the files we read, nothing replays open intents automatically, so do not describe the log as crash recovery for the task itself. It is recovery for the file and evidence for the human or the next session.
What we ran
From our lesson labs, standard library only, in a throwaway home directory with a scratch repository. First a toy log and its tests, then planted bugs: writing intent after the action, skipping tail repair, and counting hook metadata as a human note.
Ran 10 tests in <t>s
OK
mutant ORDER: FAILED (failures=2)
mutant HEAL: FAILED (errors=1)
mutant META: FAILED (failures=1)
Then the real tools at commit 504d930:
== 1. pretool hook records metadata only (the file body never reaches the log)
{"agent_id": null, "event": "pretool", "target_chars": 11, "tool": "Write", "tool_use_id": "t1"}
== 2. a human-readable intent
{'status': 'WROTE', 'event': 'intent'}
== 3. a note that looks like a credential is refused, nothing written
wal_note.py: error: note appears to contain a credential; redact it first
exit 2 lines before=2 after=2
== 4. a killed writer leaves half a line; the next append heals it
every line parses: 3 of 3 lines
== 5. permissions
file 0o600 dir 0o700
And the cadence check on a linked worktree with 50 uncommitted lines:
-- session with no human entry:
exit 2
-- same session stops again on the same diff:
exit 0
-- another session, but it writes a note first:
exit 0
Not run: a real process crash (we simulated a torn line, not a crash), and recovery of open intents, which the files we read do not implement.
Decision framing
Keeping the log costs a few seconds per step and some discipline. It pays when you need to answer "what was this agent trying to do" after a session ended, or hand a half-finished task to someone else. For a one-line typo fix, a short intent and result note is plenty.
Risks and limits
- The log is as truthful as the agent writing it. It records stated intent, not verified behavior.
- Per the source, a cadence nudge can be switched off, and a determined agent that edits the hooks can defeat it. Our stated threat model is careless or hurried agents, not adversarial ones.
- Notes can still leak by paraphrase. The credential check catches patterns, not meaning.
Related reading
- AI Reliability & Operations
- Recovery Playbooks for AI Systems
- Access Control Patterns for Enterprise Agents
- Requirement provenance for AI agents
- Courses
FAQ
- What is a write-ahead log for an AI agent?
- It is an append-only file where the agent writes down what it intends to do before it does it, then what happened. The idea is borrowed from databases, where changes are logged before they are applied so that a crash can be understood and repaired.
- Why not just rely on tool-call logs?
- A tool-call log proves a tool was attempted. It does not say why, what the agent decided, or whether the plan was sound. A human-readable intent entry written first records the reasoning that the tool metadata cannot.
- Should the log contain secrets or full prompts?
- No. Keep notes short and redacted, and refuse any note that looks like a credential. A log that is easy to write safely is a log that actually gets written.
- Does a write-ahead log let an agent resume automatically?
- Not by itself. In the files we read, nothing replays open intents automatically. The log is what a person or a new session reads to resume, together with the repository state and unfinished work.