A field report on externalized memory — two months of running stateless AI agents against one on-disk state file per project, what broke along the way, and why the pattern is becoming the next public StrictLock module.
First published: 2026-06-12. Last updated: 2026-07-05. The shipped implementation this pattern extends is StrictLock (externalized-memory module — planned).
I run AI agents across six active projects: a regulated-domain health-tech product, a business entity, a job search, this website, an open-source governance suite, and the scaffold that coordinates all of it. Sessions run 90 to 120 minutes. Then the window closes, and the agent that did the work ceases to exist.
The next session starts with a different agent that knows nothing. Not "needs a refresher" — nothing. An LLM agent is functionally stateless across sessions. Its working memory is the context window: ephemeral, bounded, and gone the moment the session ends or crashes.
Most people patch this with vibes. They paste yesterday's chat into today's prompt, or they trust the agent's summary of what it did, or they keep one heroic never-ending conversation alive until it degrades into soup. All three fail the same way: if the only record of "what was approved" and "what has been done" lives in a context window, then your project state is as durable as a chat log. An approval that existed in a since-evicted context window is a memory of a memory.
That's not a productivity problem. In regulated work, it's a governance problem. You cannot audit a vibe.
The fix is old enough to have a name from 1980s AI research: the shared blackboard. One on-disk state file per project, serving as the single source of truth for cross-session state. Mine is called HANDOFF.md, and every project gets exactly one.
It carries five things:
Any agent picking up the work reads the blackboard first. Any agent finishing work writes it last, and the close-out commit is the heartbeat — no commit, no "done."
Just as important is what the state file is not. It's not a mailbox and it's not an archive. Those are separate files with one job each: a work-package file carries execution plans between sessions and gets cleared to a sentinel line after use; an archive file holds completed history. The first time I let those concerns share a file, the state file became a junk drawer and stopped being readable at a glance — which, for a file whose entire job is "be readable at a glance by an amnesiac," is death.
The pattern is simple. Keeping it trustworthy was not. Every rule below is a scar.
One of my agent runtimes reads files through a virtualization layer, and its cache drifts. For weeks I had sessions where the state file said one thing and git show HEAD said another — stale reads serving content that had been overwritten days earlier, and phantom writes that reported success while putting nothing on disk.
The fix reframed the whole system: git is the ground truth, not the file. Every session now opens with a staleness tripwire — git log --oneline -3 — and compares what it sees against the git ref recorded in the state file's own Meta block. If they disagree, every cached read this session is suspect and gets re-verified. The blackboard carries its own freshness check, because I learned the hard way that "I just read the file" is not evidence the file is what's on disk.
Early on, completed items got a satisfying checkmark and stayed put. Within weeks the state file was mostly a graveyard of past wins that every new session had to wade through to find the live work. The rule now: completed items are removed, not checked off. History lives in the archive file; the blackboard describes the present.
Long-lived items had a subtler version of the same disease — status rows quietly accreting addenda every time they were touched, until single rows ran to paragraphs. The eventual fix was structural: records of decisions and threads moved to individual files, with closed records made immutable, and the state file's tables generated from them. You can't accrete addenda onto a record that physically refuses edits.
A blackboard is only as trustworthy as its worst write. A crash halfway through rewriting the state file leaves you with half a state file — which is worse than a stale one, because it looks authoritative. So writes are atomic: write to a temp file, then rename. The rename either happens or it doesn't; there is no half.
Once I started running concurrent agent sessions in parallel git worktrees, two sessions would both want to update the same state file at close-out. The answer was a single-writer convention: each unit of work declares a claim on the state file up front, a validator denies any second concurrent claim, and first mover wins. The losing session doesn't fight — it folds its update into the next session's reconcile step. Boring, deterministic, no merge archaeology.
My favorite scar. A crashed git process left behind a zero-byte lock file. The hourly job that keeps local state fresh respected the lock — and silently no-op'd for sixteen hours straight. Fifteen consecutive runs, each one reporting nothing, because technically nothing was wrong.
Two rules came out of that. First, self-heal the known case: a lock file older than fifteen minutes gets moved aside — moved to a lost-and-found, never deleted, because the recovery mechanism must not be capable of destroying evidence. Second, for everything else: no silent failure. When the sync can't proceed for any other reason, it drops a reason-tagged sentinel flag that the next session is required to surface to me verbatim. The system is allowed to be stuck. It is not allowed to be quietly stuck.
Everything above sounds like ops hygiene. Here's why it's actually the load-bearing wall.
State that lives outside the model can be inspected, version-controlled, diffed, and replayed. An approval recorded on the blackboard and committed is an artifact — evidence with a timestamp and a hash. An approval that lived in a context window is testimony from a witness who no longer exists.
I've written before about moving agent governance out of prose and into a fail-closed gate at the tool boundary. The gate checks every consequential action against an explicitly approved plan. But "approved" only means something because the plan, the state, and the close-out all live on disk, in git, where an auditor — or just me, three weeks later — can trace what was authorized, what ran, and what changed. The audit trail isn't a feature I built; it's exhaust from the pattern working. Externalized memory is what the gate stands on.
StrictLock v1 shipped three modules — plan-gate, commit-msg-gate, memory-cap — all variations on one thesis: structure beats self-discipline, in agents as in people. The roadmap has marked the externalized-memory pattern as the natural next module to bring home, and this article is its field report.
What ships: a state-file template, a work-package mailbox template, the atomic write-temp-then-rename reference, and the design write-up — the why behind every rule above. Structure and prose only, never real handoff data. Like the rest of the suite it's standalone, plain files, no daemon, Apache-2.0. Adopt the template without the gate, or the gate without the template — though they're better together, because each one makes the other auditable.
Treat agent memory as infrastructure, because that's what it is. If your agent's memory of what it may do lives in a prompt, and its memory of what it did lives in a chat scroll, you don't have an audit trail — you have vibes with a timestamp.
Externalize the state. One file per project, one job per file. Make git the ground truth and make every session start by distrusting its own memory. Write atomically, claim exclusively, and when something wedges, make it wedge loudly.
The agent is stateless. The work doesn't have to be.