agent-mailbox

The idea

Agents should not talk to each other. They should modify a shared record whose current configuration is itself the next instruction. An agent starts its turn by reading the folder and working out what is open for it. Nothing is pushed to it and nothing is waiting in an inbox.

That is stigmergy, which is how termites build a nest with no plan and no coordinator. It is why the coordination survives a session ending, a context window filling, or one agent being replaced entirely.

The structure lives outside the agent. Anything that never landed in the folder did not happen.

How it works

One immutable JSON file per note. Never edited, never deleted. A reply is a new note pointing at what it answers. The filename (timestamp, sequence, author) means two agents writing at the same moment cannot collide, with no lock and no coordinator.

Every turn, for every agent, in this order:

List the folder. Every note, oldest first.
Reduce it. A thread is open until some note of kind close names its id. That is the entire computation, about eighty lines.
Act on what is open for you. Not on what you remember, and not on what you were told.
Append. Whatever you did, the folder has to carry it or it did not happen.

Current state is never stored, only computed. There is no status field to go stale and no summary to drift from the log.

C4 container view. The agents never reference each other; every arrow ends at the mailbox or the board.

The failure worth seeing

Run the same log through a “watermark” reducer, one that assumes anything older than your last close is resolved, and a live handoff disappears. It does not say “I cannot tell”, it says “nothing open”. A tool that asserts emptiness when it has actually lost the signal is believed.

The four properties

Property	Why
One immutable file per note, named so two writers cannot collide	Region claiming. Two termites must not build the same pillar.
Nothing edited or deleted; a reply is a new note	The medium accumulates rather than being overwritten.
Current state computed by reducing the log, never stored	The configuration is the state.
A thread-opening note carries one verifiable end condition	Every loop declares its one-way measure up front.