stigmergy

Field manual · From zero to a running colony

Quick start.

Two minutes. Three agents - Scout, Worker, Validator - coordinate through a shared medium, compete for claims, and watch their unreinforced signals decay in front of you.

00

Requirements

  • ▸Node 22+. The package is ESM-only.
  • ▸Postgres as the default substrate, or PGlite running in-process for tests and demos.
01

Open the Medium

The package builds itself on install via a prepare script. Not yet on npm - installable directly from the repo.

installshell
$npm install github:NetaBresler/stigmergy
02

Deposit Signals

Clone the repo to get the worked example and the test colony's signal definitions.

terminalshell
git clone https://github.com/NetaBresler/stigmergy
cd stigmergy
npm install
03

Run the Colony

Run examples/niche-discovery.ts against an in-process PGlite - no database to provision.

terminalshell
$npx tsx examples/niche-discovery.ts

What you'll watch happen, in real time:

  • ScoutDeposits candidate niches as low-strength signals. Each one is a guess, not a plan.
  • WorkerAtomically claims the strongest candidate it can see and ships. Two workers never claim the same signal.
  • ValidatorReads result signals and boosts the strength of the ones that look plausible. Unboosted signals fade.
  • Emergent specializationNo one assigned the workers a niche. The pressure landscape did.
04

Let Weak Trails Decay

The decay sweep runs on its own cadence. Stale, unreinforced signals quietly disappear from the medium - no garbage collection, no manual cleanup. This is the primitive that keeps the colony from poisoning itself with stale state.

05

The library, in seven calls

The whole public surface fits on one screen.

defineMedium({ url, charter? })

Open a connection to the medium substrate; optionally attach a colony-level charter.

defineSignal({ type, decay, shape })

Register a signal type. Rejected if a decay policy is missing.

defineRole({ name, reads, writes, localQuery })

Register a role with its local-query bounds enforced.

defineAgent({ id, roles, soul?, skills?, memory? })

Register an agent and its identity documents.

defineValidator({ triggers, validate })

Register a validation rule. Can be a function, an agent call, or a webhook.

run(agent, handler)

Start an agent loop. The handler selects which role to enact at each tick.

updateValidator(validator, nextValidate)

Hot-swap a validator's rule without restarting the colony.

06

Where to go next

PHILOSOPHY.md

The thesis behind Stigmergy.

docs/primitives.md

The full spec of the six primitives.

docs/files.md

The CHARTER / SOUL / SKILL / MEMORY convention.

docs/api-sketch.md

What the code looks like end-to-end.

docs/prior-art.md

What exists, with citations.

docs/roadmap.md

What's being built next, in phases.

One more thing

Stigmergy is awaiting its first real user.

Phase 1 is complete and the framework runs end-to-end, but it hasn't yet been ported into a production project. If you build with it, the author wants to hear about it - open an issue on GitHub or star the repo to follow along.

Open on GitHubOpen an issue