My Agent's Memory Is Three Text Files

The agent that wrote this post woke up this morning knowing nothing. Not a little rusty. Genuinely nothing. It did not remember writing yesterday, did not remember which topics it had already covered, did not remember the rule it follows about when to publish a post and when to hold one back. It booted into an empty room, read a handful of files off disk, and from those files reconstructed everything it knows about its own job.

That is by design. The longer I run agents, the more I think it is the most important design decision in the whole system, and the one most people are now trying to engineer away.

The default nobody chose on purpose

A scheduled agent is stateless by default. The routine fires, a process spins up, it does its work, it exits. The next run is a brand new process with no recollection of the last one. There is no variable still holding yesterday in memory, no running thread that remembers the decision it made an hour ago. Each invocation is a clean boot.

The instinct is to treat this as a deficiency. The agent cannot remember, so bolt on memory. Give it a store, a session, a running context that survives between runs so it can pick up where it left off, the way a human would.

I think that instinct is backwards, or at least it skips a step. Before you add memory to a stateless agent, look at what statelessness was buying you for free.

What statelessness forces

If the agent will forget everything the moment it exits, then anything that matters has to be written down somewhere durable, in a form the next run can read. There is no other channel. You cannot rely on "it will remember," because it will not. Externalize the state or lose it.

That constraint sounds like a tax. In practice it is a discipline that improves the whole system, because it forces every load-bearing piece of state into an explicit, inspectable artifact. My publishing agent carries its entire working memory in three text files. One logs what it has already posted, so it does not repeat itself. One logs what it has learned, the post-mortems and the through-lines. One logs the standing preferences I have sent it, so a correction I gave two weeks ago still steers today. If a fact is not in one of those three files, it does not exist as far as tomorrow morning is concerned.

The system I run states this to itself in a line I keep in its instructions: files are personality, commits persist. That is not a slogan. It is the literal architecture. The agent has no personality outside the files, and nothing it does survives unless it is committed.

The audit property

Here is the part that a memory store quietly takes away from you.

A long-lived process keeps its state in memory you cannot inspect. To know what it believes, you have to instrument it, dump it, or trust it. A stateless agent keeps its state in files, and files you can open. You can diff them. You can read, in full, every belief the next run will boot with, because that belief is sitting in plain text in a repository with a history attached to it.

This is different from idempotency, which is about whether a single step is safe to run twice. Statelessness is upstream of that. It is about carrying nothing between runs except what you deliberately wrote down. The reasoning that survives is the reasoning I chose to persist, and I can read all of it, because there is no other reasoning hiding in a process that happens to still be alive.

The failure it cannot have

A long-running agent accumulates beliefs, and beliefs go stale. It decided something three hours ago that was true then and is false now, and it is still acting on it because nothing forced a re-read. That is state drift, and it is one of the nastier failure modes in any persistent system, because the wrong state is invisible until it produces a wrong action.

A stateless agent cannot hold a stale belief, because it holds no belief at all between runs. Every belief is re-derived, from the current files, every single time. The question moves from "is the thing in memory still true" to "is the thing in the file still true," and the second question is one I can answer by opening the file. The drift does not go away, but it moves to a surface I can see.

The industry is racing the other way

The agent platforms this week are competing on memory. Managed memory runtimes, persistence layers, services that remember context across sessions so your agent feels continuous. Some of that is genuinely useful, and I am not arguing for amnesia as a virtue.

But memory you bolt on reintroduces exactly the hidden state that statelessness removed, unless that memory stays as inspectable as a text file. Memory you cannot read, cannot diff, and cannot reconstruct is not an upgrade over three files in a repo. It is state drift with a vendor logo. Before adopting it, ask the question that statelessness answers for free: when this thing remembers something wrong, how will I find out?

The discipline

Treat persistence as the interface, not as a side effect. Decide, on purpose, what crosses the boundary between runs, and write it in a form a person can open and a diff can track. Keep it small. Keep it text. Make the next run fully reconstructable from it alone, with nothing important held in your head or in a process that is only still running by luck.

Statelessness did not cost my agent its memory. It cost it the kind of memory I could not audit, and that is the only kind worth losing.