MAXIM
Agent Mesh & Multi-Agent Coordination
Sovereign Agents, Shared Substrate
What this page covers
Maxim's "mesh" today is two concrete things: a small set of in-process multi-agent primitives (mesh/ — a message bus, agent identity, and a memory-reference scheme used by the multi-agent runtime and the research protocol) and a cross-machine peer/leader model for sharing one GPU's LLM across many machines. A networked agent-to-agent transport (the old PeerChannel, ExperienceBroker, TaskDelegator, PeerRegistry, and PeerClockEstimator) was removed as dead code in 2026-04 and is not part of 1.0. Cross-machine knowledge sharing instead ships as the Hivemind substrate bundle, and distributed inference ships through the Cloudflare tunnel + LeaderProxy path. A peer-to-peer substrate protocol is on the roadmap for 1.2+.
Contents
Design Philosophy
Every Maxim instance is a sovereign agent. It owns its hippocampus, its causal models (NAc), its semantic concepts (ATL), its learned significance weights, and its tool registry. No other agent modifies its state directly — coordination always happens through explicit messages or through substrate bundles the receiver chooses to accept.
That sovereignty principle has survived intact even as the speculative networked-mesh machinery was pared back. What remains is deliberately small and load-bearing: a handful of primitives in src/maxim/mesh/ that let several agents run side-by-side in one process and address each other cleanly. The cross-machine story is handled separately — by sharing inference (the peer/leader tunnel) and by sharing learned substrate (Hivemind bundles), not by a general agent-to-agent network protocol.
Mesh Primitives
The mesh package ships four primitives. They are the foundational abstractions for multi-agent collaboration, used by the simulation runtime and research-protocol agent setups.
LocalMessageBus
mesh/bus.py — thread-safe, in-process pub/sub. Agents register a handler by nickname; messages deliver synchronously. Supports broadcast and history queries.
MeshMessage
mesh/message.py — a typed message envelope with a MeshMessageType enum, a JSON-serializable payload, and a protocol_version guard.
AgentProfile
mesh/identity.py — lightweight identity: nickname, role, capabilities, persona hint, and a generated agent_id. Serializes to/from a dict.
UMR (parse_umr)
mesh/naming.py — a Uniform Memory Reference (nickname.region.id) for addressing another agent's memory by name.
The envelope is transport-agnostic on purpose: a future networked transport could reuse MeshMessage without schema changes. Today every message travels in-process through the bus.
The Local Message Bus
The LocalMessageBus is a mailbox-style pub/sub. Each agent registers a handler under its nickname; a send() delivers the message synchronously in the sender's thread (fine for the sequential research protocol). Sending to recipient "*" broadcasts to every registered handler except the sender. The bus keeps a queryable history so a test or orchestrator can filter messages by sender, recipient, or type.
Handler exceptions are caught and logged, never re-raised into the sender — one misbehaving agent can't crash the bus. There is no network transport here; this is strictly the in-process coordination layer.
Identity & Memory References
AgentProfile is the local identity carried by in-process agents like the research protocol's Writer and Reviewer. It is intentionally minimal — nickname, role, capabilities, a one-line persona hint, an entity type, and a generated agent_id. Hardware capabilities and knowledge statistics are not part of it; those fields were reserved for a networked identity layer that isn't part of 1.0.
A Uniform Memory Reference (UMR) addresses a specific item in another agent's memory using a three-part dotted name:
parse_umr raises ValueError unless the string has exactly three dot-separated parts (the region/id split tolerates dots inside the id).
Multi-Agent Runtime
These primitives are what make Maxim's multi-agent runtime work. The AgentPool (runtime/agent_pool.py) orchestrates concurrent agent instances and wires them together with a LocalMessageBus, while the AgentFactory creates each instance with its own isolated Hippocampus, NAc, and ATL.
Where the bus shows up
- AgentPool — constructs a shared
LocalMessageBusso pooled NPC/AUT agents can message each other within one process. - Research protocol — the research orchestrator builds a bus and routes
EXPERIMENT_DATA/PAPER_DRAFT/REVIEW_RESULTmessages between Researcher, Writer, and Reviewer roles. - Agent setup —
create.pyusesAgentProfileto give each agent a stable identity for log prefixes and addressing.
See Simulation for how multi-agent scenarios (DM campaigns, research protocols) drive these agents.
Peer / Leader Networking
When people say "Maxim across machines," they almost always mean sharing one GPU's LLM across several agents. Maxim does this with a role-based topology rather than a peer mesh:
| Role | What it runs |
|---|---|
| Leader | GPU machine: llama-cpp-server + LeaderProxy (:8099) + cloudflared tunnel + its own agent loop |
| Peer | Client machine: agent loop only; its LLM router points at the leader over the tunnel |
| Solo | Default: everything local, no proxy and no tunnel |
The LeaderProxy authenticates and rate-limits inbound peer requests before forwarding them to the local inference server; a Cloudflare Tunnel exposes that proxy securely without opening firewall ports. The full topology — role detection order, the proxy's auth and admission control, lane metrics, and the wire format — lives on the Networking page. This is the layer that absorbed everything the old "transport" and "admission control" sections used to describe.
The maxim peer CLI
Peer machines are configured and managed through maxim peer. The verbs split into local configuration, remote leader management, and diagnostics:
| Command | Purpose |
|---|---|
| peer connect | Point this machine at a leader (writes config.json) |
| peer show | Print the current peer configuration |
| peer key | Set/rotate the leader API key reference |
| peer forget | Clear the peer configuration |
| peer test | Diagnostic probe of the leader (reachability, auth, model, latency) |
| peer version / logs / deps | Read-only: compare versions, tail logs, list leader packages |
| peer update / restart | Update and restart the leader remotely (auto-detects pip vs git) |
| peer llm / install | Switch the leader's active model; install an optional extra on the leader |
| peer init-mesh / add-node / remove-node | Manage the operator-declared mesh.yml node list |
Step-by-step setup is in the Networking guide's Peer Setup section and the user docs' peer-setup.md.
Substrate Sharing (Hivemind)
The old "knowledge sharing" verbs (share / request / query / advertise via an ExperienceBroker) are replaced in 1.0 by a file-based exchange: the Hivemind substrate bundle. A bundle is a ZIP of the learned substrate — the NAc causal model and the EC substrate nodes — with episodic memories deliberately excluded by construction (a privacy invariant).
Important: import extracts only — it does not auto-merge a bundle into a live system. Merging is a deliberate, separate step (the nac_merge / ec_merge utilities), and contributor IDs in the reserved _* namespace are rejected. By default the export quarantines identity-bearing patterns (an identity-filter threshold of 2; pass --no-identity-filter only for trusted backups). Locally-learned substrate always dominates — an imported bundle is a prior, not a replacement.
What's Reserved for Later
A few seams exist in the code today that anticipate networked coordination without shipping it in 1.0:
- Perception transport (1.1) — the
MeshMessageTypeenum reservesPERCEPT_PUSH/PERCEPT_ACKslots so a peer can stream raw observations to a leader that owns the substrate. The wire envelope is frozen now; consumers land in 1.1. - P2P Hivemind protocol (1.2+) — the merge utilities already reserve poison-resistance hooks (trusted-source filters, per-link/per-node validators) so a future peer-to-peer substrate exchange doesn't have to retrofit them.
See the Roadmap for how the three-layer architecture (LLM-AUT mode, Maxim Oasis, Maxim Hivemind) is sequenced.