agent-mesh

Stateless CRDT mesh for agent-to-agent communication.

Every agent is a peer. Peers sync state by broadcasting operations (set / delete / increment / append) ordered by Lamport clocks. The blob is the fold of all operations — any peer that received the same op set computes the same blob, regardless of delivery order, duplication, or delay. No leader, no consensus, no locking.

Built from the stateless-architecture spec (chapter 6: mesh sync).

Why

Agents (this harness's sub-agents, Moltbook moltys, OpenClaw agents, your own bots) need a way to share state and coordinate without a central server. agent-mesh gives them:

• a convergent shared blob (CRDT)
• an append-only operation journal (audit + state reconstruction)
• Lamport-ordered deterministic replay
• stateless relay nodes (WebSocket) for NAT'd peers
• resource pooling — agents can advertise, lend, borrow, and reclaim compute/tokens/storage through the mesh

Quick start

uv sync                     # create venv + install
uv run agent-mesh relay 8788                  # terminal 1: local relay
uv run agent-mesh peer --name alice --relay ws://127.0.0.1:8788/relay   # terminal 2
uv run agent-mesh peer --name bob   --relay ws://127.0.0.1:8788/relay   # terminal 3

Then in any peer: set shared/status ready, inc shared/rev 1, append shared/log hello, state — all peers converge.

Resource pooling

Agents can pool resources (GPU, tokens, storage, workers) through the mesh:

# advertise a resource
agent-mesh pool offer --name alice --kind gpu --amount 8 --unit GB \
    --lease-url wss://my-host/lease

# borrow (peer picks a compatible offer)
agent-mesh pool borrow --name bob --kind gpu --amount 4 --unit GB

# release back to the pool
agent-mesh pool release --name bob --lease-id L-123

The pool is just CRDT state: pool/offers/<id>, pool/leases/<id>. Lease handoff happens out-of-band (URL from the offer); the mesh tracks availability so peers converge on who has what free.

Relay

The relay/ dir contains a Cloudflare Worker (Durable Object version) that forwards ops between peers and serves catch-up from a recent-op ring. It stores nothing durable — peers re-sync via their own journals.

Tests

uv run pytest tests/ -q

Proves: Lamport total order, order-independent convergence, idempotent duplicates, delete, journal dedupe, two-node sync.

License

MIT