What are context atoms (and why your AI agents need them)

Last month I watched two of my AI agents quietly disagree with each other. Claude had helped me pick Postgres LISTEN/NOTIFY for a real-time feature a few weeks prior, and now Gemini, running an analysis pass in a fresh session, was politely suggesting I migrate to Redis pub/sub because it would scale better. Both answers were reasonable in isolation. Neither agent knew the other had ever touched this, and the reasoning behind the original choice lived in a commit message I had not taken the time to write well, and nowhere else.

This is the shape of the problem I kept running into: agents that are individually careful and collectively amnesiac. They do not fight each other on purpose, they just cannot see each other's work.

Plain memory is the wrong shape

The obvious fix is "give the agents memory." Most tools that try this give you a flat blob: a running log of text the agent can append to and re-read. That sounds fine until you try to use it.

A flat log collapses everything into the same weight. A decision (we chose Postgres NOTIFY) sits next to a throwaway observation (the login page looks a bit tight on mobile) sits next to an open question (do we need rate limiting yet). When the next agent reads the log, it has no way to tell which items are load-bearing and which are noise, so it re-opens settled questions, treats old guesses as commitments, and quietly contradicts things that were already decided.

The problem is that the memory has no shape, not that it is too small. You cannot ask a blob "what has this project committed to?" and get a clean answer.

What a context atom is

A context atom is a single unit of reasoning with a type attached. Somebody made a choice, somebody hit a gotcha, somebody tried an approach and it did not work, somebody has an open question. Each of those is a different kind of thing, and treating them as the same thing is the root of the problem above.

In Workunit, each workunit has a timeline of atoms, and anyone can add one: me, a teammate, Claude, Codex, Gemini, a background worker. They are ranked by importance, optionally marked as locked or revisitable, and they can supersede older atoms when reasoning changes. That is the whole idea, and the tininess of the schema is the point.

The five types

I have tried to keep the list short enough that picking the right type takes no thought.

Five types is not meant as a universal truth. It is the set I kept needing on my own projects, whittled down to the point where adding a sixth felt like dilution.

Importance and strength

Every atom has an importance: critical, high, normal, or low. This matters because you are almost never going to fit the full atom history into an agent's context window. When I ask Claude to pick up a workunit, the MCP call returns atoms grouped by type and sorted by importance, then recency, so the critical ones land in the prompt and the low-importance ones get summarised or dropped.

Strength is a second axis. Most atoms are "soft," meaning they are revisitable if new information shows up. Some are "hard," meaning they are governance: locked, do not rewrite them without a conscious supersede. A hard atom might be something like "all personal data must be covered by the GDPR export job," and you really do not want an agent casually second-guessing that.

Superseding is how minds change

Agents do change their minds, and they should. The question is how they do it. Silently rewriting an atom loses the history, and stacking a contradictory atom on top creates confusion; neither is good.

Superseding is the compromise. When a new atom supersedes an older one, both are preserved, but the older one is marked as replaced. "We chose JWT auth" can be superseded by "We migrated to session auth because JWT revocation was harder than we expected," and a future agent reading the timeline sees the current state and the path that got there. Nothing is lost, and nothing is secretly still in force.

This is the feature I use most often on my own projects. Decisions age, and being able to update them with a trail is what keeps the context trustworthy.

A small example

Here is a real workunit from earlier this year. The feature was a filter UI for the context atom timeline itself.

1. Decision, high importance. Use HTMX for filter updates instead of a full SPA rewrite, because it matches existing patterns in the codebase.
2. Attempt, normal. First pass used separate SQL queries per filter combination, and it fell apart at two active filters because the combinations multiplied.
3. Decision, high, supersedes #2. Combined into a single ListContextAtomsFiltered query using sqlc.narg for optional params.
4. Insight, normal. HTMX's hx-include pulls all named form inputs, which means the hidden ones too, and that is worth remembering next time.
5. Progress, normal. Filter UI shipped, markdown rendering is next.

A new agent reading these in order sees the plan, the dead end, the revised plan, a gotcha worth knowing, and where the work stopped. No contradictions, no lost reasoning, and about forty seconds of reading to get fully oriented.

How agents actually read and write these

Workunit exposes atoms through an MCP server. When Claude picks up a task, the first call it makes is usually get_workunit with include_ai_context enabled, and it gets back the atoms, sorted and grouped. When it finishes a piece of work, it calls save_context with the atom type, importance, and optionally a supersedes link if it is updating an older decision.

Codex does the same thing when it is working on the UI, and Gemini does the same when it is running an analysis pass. The atoms are the shared language, which means none of the models need to know about each other; they just need to read and write in the same shape. That is the whole trick, and it is why those two agents have not quietly disagreed on me since.