{% extends "base.html" %} {% block title %}Agent Mesh — Maxim Docs | Multi-Agent Primitives & Peer Networking{% endblock %} {% block meta_description %}The mesh primitives Maxim ships today — in-process message bus, agent identity, uniform memory references — plus the peer/leader tunnel model for cross-machine LLM routing and Hivemind substrate sharing.{% endblock %} {% block meta_keywords %}Maxim agent mesh, multi-agent runtime, LocalMessageBus, MeshMessage, AgentProfile, peer leader tunnel, Cloudflare tunnel, Hivemind substrate sharing, maxim peer CLI, distributed inference{% endblock %} {% block meta_author %}Maxim Project{% endblock %} {% block og_site_name %}Maxim{% endblock %} {% block og_type %}article{% endblock %} {% block structured_data %}
{% endblock %} {% block content %}
← Back to Overview

### 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

1. Design Philosophy
2. Mesh Primitives
3. The Local Message Bus
4. Identity & Memory References
5. Multi-Agent Runtime
6. Peer / Leader Networking
7. The `maxim peer` CLI
8. Substrate Sharing (Hivemind)
9. What's Reserved for Later

## 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.

Bus API bus = LocalMessageBus() bus.register("writer", on_message) # handler by nickname bus.send(MeshMessage(sender="researcher", recipient="writer", msg_type=MeshMessageType.EXPERIMENT_DATA, payload={...})) bus.send(MeshMessage(..., recipient="*", ...)) # broadcast to all but sender bus.get_history(sender="researcher") # filtered query

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:

UMR format — nickname.region.id researcher.hippo.exp_001 # experiment 001 in researcher's hippocampus writer.paper.methods # methods section of writer's paper reviewer.review.round_1 # reviewer's first-round review parse_umr("writer.paper.methods") # → UMR(nickname, region, ref_id)

`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 `LocalMessageBus` so 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_RESULT` messages between Researcher, Writer, and Reviewer roles.
- Agent setup — `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.

## 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).

maxim substrate maxim substrate export out.zip --session <id> --contributor-id <you> maxim substrate inspect out.zip # print the manifest, no extraction maxim substrate import out.zip --output-dir ./incoming

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 `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.
- 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.

← Previous Networking Next → Simulation

### All Chapters

Overview The Agent Brain Memory Systems Math & Statistics Attention & Salience Body Awareness Communication Usage Guide Technical Deep Dive Operating Modes Networking Agent Mesh Embodiment Simulation Benchmarks Roadmap
{% include "_maxim_footer.html" %}
{% endblock %}