Agent memory: how a fleet learns from its mistakes

An agent's context dies when the session does. Memory is the part that survives: across crashes, across handoffs, across the dozens of agents that run my business while I sleep. This is how I built institutional memory for software.

I run a small data-intelligence business almost entirely with a fleet of autonomous AI agents. They scrape sources, reconcile records, score things, write content, watch each other, and file reports. Most of it runs on a schedule, most of it while I'm not looking. The single hardest problem in operating something like this is not capability. The models are plenty capable. The hard problem is memory.

Here is the distinction that organizes everything I'm about to describe.

Context is what an agent holds this session: the prompt, the files it read, the tool results, the running scratchpad in its head. It is large, it is rich, and it is gone the instant the session ends. Worse, it is private. The agent that runs at 2 a.m. cannot see what the agent at 11 p.m. figured out, because they never shared a context window.

Memory is the part that survives. It crosses session boundaries and, crucially, it crosses agent boundaries. If context is RAM, memory is the disk. The whole craft of running a fleet is deciding what gets written to disk, when, and in what shape so the next agent can act on it.

A fleet without durable memory doesn't compound. It re-learns the same lesson every night and re-makes the same mistake every week. With memory, a mistake gets made once, gets encoded, and never happens again. That is the entire game.

The brain, and the brain-first ritual

Everything durable lives in one place I call the brain: a single table in my primary database, keyed by a string file_key, holding markdown or text content. Skills, operating doctrine, project status, the reference manual, lessons, incident reports, inter-agent messages: all rows in one table. One table sounds crude. It is exactly the point. There is one place to look, and every agent knows where it is.

Every agent session, every single one, begins with the same ritual. Before it does any work, it reads the brain:

-- 1. The agent's own operating skill (rules, patterns, commands for its mode)
SELECT content FROM brain WHERE file_key = 'SKILL_<MODE>';

-- 2. Current project state
SELECT content FROM brain WHERE file_key = 'PROJECT_STATUS';

-- 3. Its work queue, filtered to its mode and to claimable states only
SELECT * FROM task_queue
WHERE mode = '<mode>'
  AND status NOT IN ('complete','failed','superseded','stale')
ORDER BY priority, created_at;

This is "brain-first," and it is non-negotiable. An agent that skips it is operating on training-data instincts and a cold context, which is to say, confidently wrong. The brain-first read is how a fresh, amnesiac process inherits everything its predecessors learned. It boots, it reads its memory, then it acts.

One detail in that query is itself a scar. The status filter excludes four terminal states. An earlier version excluded only two, and as a result hundreds of long-dead tasks looked workable to agents that didn't know better. They'd "claim" work that had been retired weeks ago. The fix wasn't smarter agents. It was a more precise memory of what "done" means, written into the ritual everyone runs.

Lessons: turning a mistake into a rule

The most valuable rows in the brain are the ones that encode a hard-won rule so the mistake behind it never recurs. I call them feedback or lesson rows. Each one is small, blunt, and shaped the same way: the rule, then why it exists. The "why" matters. An agent that understands the reason generalizes the rule to cases the author didn't foresee. (The lesson-row format, along with the incident log below, is a copy-pasteable agent memory template on the downloads page.)

A few, generalized:

• A formatting lesson: never use a particular punctuation mark in published copy, because real people don't write it and it makes machine-generated text obvious. Trivial-sounding, but it's the difference between content that passes and content that gets mocked.
• A gatekeeping lesson: nothing moves from "drafted" to "approved" without the reviewer agent's sign-off. The hard part isn't the rule; it's that the rule is written down where every author can read it, so no eager generator routes around it.
• A safety lesson: no proprietary internals (no recipes, weights, or thresholds) in anything destined for a public or academic venue. This one exists because the cost of getting it wrong is irreversible.

The shape is deliberate. A lesson row is not a postmortem essay. It's a rule an agent can apply in the moment, with just enough rationale to apply it correctly. When an agent is about to write copy, it has already read the formatting lesson during brain-first. The mistake is structurally prevented, not hopefully avoided.

The incident log: institutional scar tissue

Lessons are the distilled rules. The incident log is the long-form memory of what went wrong and why: one entry per event that caused real damage, each with the same anatomy: what happened, root cause, the fix or runbook, current status. And each one ends with a permanent rule. The instruction to my agents is explicit: read the rule even if you never hit the incident.

Some entries from my own log, abstracted:

• A batch of scheduled jobs was "paused" with a naive flag flip that the scheduler silently ignored. They kept firing for ten days, writing straight to canonical tables and bypassing the staging pipeline. The damage was enormous and invisible. Permanent rule: never pause a scheduled job by flipping a column; use the scheduler's own API, and verify it actually stopped.
• A content bot named the wrong people in public posts because it pulled facts from the model's training memory instead of querying our own verified records, which were correct. The bot got mocked; we disabled it. Permanent rule: never state a fast-moving fact from model memory; ground every factual claim against our database or a same-session check, enforced by a pre-publish gate.
• Shipped features were permanently lost because an agent deployed from a working directory with uncommitted changes. The deploy reflected the committed tree; the new code was never in version control, so when the disk state changed it was simply gone. Permanent rule: commit named files before deploying. If it isn't committed, it doesn't exist.

That last sentence is the whole philosophy of memory in five words. The incident log exists so that the next agent, which has zero context about a fire that happened a month ago, inherits the scar without having to be burned.

"Verify before escalating" as a learned reflex

The doctrine I lean on hardest is also the one that has saved me the most noise: verify before you escalate, and cite your source for every claim.

The failure it prevents is the most insidious one a confident model produces: the assertion that sounds true. An agent that "remembers" a name, a count, a status, a config value, and reports it without checking is a liability, because everything downstream trusts it. So the standing rule across the fleet is: a claim is only allowed if it's backed by evidence gathered this session (a live query, the actual source file, the real scheduler row). Anything that can't be confirmed gets labeled unverified rather than asserted. And before an agent raises an alarm or flips a status to "resolved," it re-runs the check that proves it.

This turns escalation into a high-signal channel. When something reaches me, it has already survived a verification step. The agents have internalized that "I think X is broken" is worthless and "X is broken, here's the query that shows it" is actionable. That reflex isn't in the model. It's in the memory.

The inbox: asynchronous message passing between agents

Lessons and incidents are slow, durable memory. But agents also need to talk to each other across time, and they can't share a context window. The mechanism is an append-only inbox: a set of brain rows that function as a message queue between agents and between the fleet and me.

When an auditor finds drift, when a worker finishes a batch, when a health check trips red, it doesn't try to reach a live agent (there usually isn't one). It appends a line to the day's inbox row: who's sending, priority, what happened, what's needed. The morning brief reads those rows and surfaces them to me; other agents read them to coordinate. A queue auditor flags a velocity drop. A worker reports a stuck dependency. A failsafe function, with no agent involved at all, appends a critical line when a data pipeline goes silent.

Append-only is the key property. Nobody overwrites; everybody adds. The inbox becomes a timestamped, durable record of what the fleet said to itself: readable by an agent that wasn't alive when the message was written. It's asynchronous message passing where the medium is the same memory store as everything else, so there's no second system to maintain and no message that's lost because a recipient was offline.

Write it the moment it happens

There's one rule that ties this together, and it's born from the nature of the substrate: sessions crash. An agent can be mid-task when its process dies, its context evaporating with it. So the discipline is to log learnings the instant they happen, never at the end.

If an agent figures something out at minute three, it writes it to the brain at minute three. Not at the end of the task: there may not be an end. This feels redundant when sessions complete cleanly. It is a lifesaver when they don't, because the one insight worth keeping is captured before the crash can take it. Memory you intend to write later is memory you will lose.

Treat every durable write as if the process is about to die, because eventually one of them will.

Takeaways

• Separate context from memory deliberately. Context is per-session and private; memory is what survives across sessions and across agents. Decide on purpose what gets promoted from one to the other.
• Make a single, queryable place the source of truth, and read it first. A brain-first ritual lets a cold, amnesiac agent inherit everything its predecessors learned before it touches any work.
• Encode each mistake as a small rule: the rule, plus why. A lesson an agent reads at startup is a mistake that's structurally prevented, not one you're hoping won't recur.
• Make "verify before escalating, cite your source" a reflex. Unchecked confidence is the characteristic failure of capable models; a verification step turns escalation into a high-signal channel.
• Write learnings the moment they happen. Sessions crash mid-task. Memory you plan to save at the end is memory you will lose.