The spec, in plain English
A system is stigmergic if and only if it has all six. Miss one and you have something else - a knowledge base, a queue, a workflow engine, a manager-in-disguise. All six, designed together, are the minimum load-bearing structure.
01
The one place agents read from and write to.
The medium is where coordination happens. It is the only legitimate coordination channel in the system. If two agents talk to each other directly - over a queue, an API, a shared prompt - you have re-invented the manager.
In the reference implementation the medium is Postgres. Tables encode signal types. Rows are individual signals. Columns carry metadata: type, strength, expiry, origin agent, claim state.
Requirements
Anti-pattern
“The agents share a message bus.”
A message bus is not a medium because signals flow through, they are not deposited. Without deposition there's nothing to read later, nothing to decay, nothing that persists.
02
Every signal evaporates unless reinforced.
This is the primitive every previous attempt at database-backed stigmergy has gotten wrong. Biological pheromones evaporate. Database rows do not. If you do not build decay in from day one, stale signals will poison the colony.
Stigmergy refuses to register a signal type without a declared decay policy. Pick one of three: explicit expiry, strength decay, or reinforcement-only.
Three decay kinds - strength over time
Requirements
Anti-pattern
“We'll add decay later.”
This is the failure mode of every naive attempt. Every hour without decay accumulates state that will later require archaeology to untangle. Decay isn't an optimization. It's the primitive.
03
Agents know what kind of work they do - not who else exists.
Specialization is the cheapest way to get useful division of labor in an LLM colony without writing a planner. A role bundles three things: which signal types it reads, which it writes, and what its local query looks like.
Roles never reference each other. A Worker role does not know that a Validator role exists. It knows only the signals.
The reference implementation ships three composable defaults - Scout, Worker, Validator - but you can declare any role you like.
Requirements
Anti-pattern
“The Supervisor role reads everything and decides who does what.”
That is a manager. Delete it.
04
The identity that enacts roles. Distinct from the role itself.
One ant does many jobs across its life - nurse when young, food-processor in middle age, forager at the end. It's always the same ant. Identity stays; function shifts. The biology term is polyethism.
Stigmergy makes the same split. An Agent is who a colony member is - stable id, declared roles, and optional identity documents (SOUL, SKILL, MEMORY). A Role is what function the agent is enacting at this tick.
Multi-role agents select which role to enact each tick. They do not enact several at once - that would break locality.
Requirements
Anti-pattern
“Agents can message each other directly to coordinate.”
Coordination is mediated by signals in the medium - never by direct reference between agents.
05
Every role sees only its slice.
Locality is what stops specialization from collapsing back into hierarchy. If an agent can see the whole medium, it will start reasoning about the whole medium, which means it will start making plans about the whole medium, which means it is now a manager.
Every role declares its local query. The framework enforces that query as the agent's only read access. There is no peeking.
Locality is a coordination mechanism, not a privacy mechanism. Partial views are what make emergent specialization actually emerge.
Requirements
Anti-pattern
“The Worker also needs to peek at the Validator queue to pre-empt.”
If the Worker needs information from the Validator, the Validator writes a signal the Worker reads. No peeking.
06
Successful outcomes deposit more signal than mere activity.
Without validation, noise wins. Any agent can deposit any signal and the medium fills with garbage. With validation, the colony converges on actually-good work.
Reinforcement is a distinct operation from deposition. An agent deposits; a Validator reinforces. Reinforcement changes a signal's strength, expiry, or visibility - never its content.
Validation can be rule-based, agent-based, or human-in-the-loop. All three are first-class. Early systems often start with a human-in-the-loop validator (Telegram, dashboard, webhook) and replace it with a rule once thresholds are known.
Requirements
Anti-pattern
“Every signal immediately has full strength.”
Then whoever runs first wins, regardless of quality. Reinforcement is the mechanism that lets quality beat speed.
Now see how they fit together.
Install, run the worked example, and watch a three-agent colony coordinate in real time.