MAXIM
Sovereign Agents, Shared Substrate
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+.
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.
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.
mesh/bus.py — thread-safe, in-process pub/sub. Agents register a handler by nickname; messages deliver synchronously. Supports broadcast and history queries.
mesh/message.py — a typed message envelope with a MeshMessageType enum, a JSON-serializable payload, and a protocol_version guard.
mesh/identity.py — lightweight identity: nickname, role, capabilities, persona hint, and a generated agent_id. Serializes to/from a dict.
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 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.
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).
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.
LocalMessageBus so pooled NPC/AUT agents can message each other within one process.EXPERIMENT_DATA / PAPER_DRAFT / REVIEW_RESULT messages between Researcher, Writer, and Reviewer roles.create.py uses AgentProfile to 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.
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.
maxim peer CLIPeer 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.
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.
A few seams exist in the code today that anticipate networked coordination without shipping it in 1.0:
MeshMessageType enum reserves PERCEPT_PUSH / PERCEPT_ACK slots 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.See the Roadmap for how the three-layer architecture (LLM-AUT mode, Maxim Oasis, Maxim Hivemind) is sequenced.