nucleus_federation
Coordinate multiple AI agents across distributed environments by joining federations, syncing state between peers, and routing requests to the appropriate brain.
Instructions
Coordinate multiple Nucleus brain instances across distributed environments by joining federations, syncing state between peers, and routing requests to the appropriate brain. Use this tool when multiple AI agents on different machines or projects need to share memory, synchronize decisions, or coordinate work across separate .brain directories. Do NOT use for single-brain agent coordination (use nucleus_agents), artifact sharing within one brain (use nucleus_sync), or session handoffs (use nucleus_sessions). Actions: 'status' returns current federation membership and connection state (read-only). 'join' connects the current brain to a named federation (side effect: writes federation config to .brain/federation/). 'leave' disconnects from a federation. 'peers' lists all connected brains with their last-sync timestamps. 'sync' replicates state between brains — 'delta' mode merges only changes (safe), 'full' mode overwrites the target entirely (destructive). 'route' forwards a tool request to a specific peer brain and returns its response. 'health' checks connectivity and latency to all peers. Prerequisites: .brain directory. Federation requires filesystem access for local peers or network access for remote peers. Returns JSON with {success: boolean, data: object}. Example: {action: 'join', params: {federation_id: 'team-alpha', brain_path: '/shared/project/.brain'}} returns {success: true, data: {joined: true, peer_count: 3}}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Select the federation action. 'status'/'peers'/'health' are read-only queries returning federation state. 'join' connects to a federation (writes config). 'leave' disconnects. 'sync' replicates data between brains — 'full' mode is destructive and overwrites the target brain. 'route' forwards a request to a specific peer brain. | |
| params | No | Action-specific parameters as key-value pairs. join: {federation_id: string (required, unique federation name), brain_path: string (required, filesystem path to remote .brain directory)}. leave: {federation_id: string (required)}. route: {target_brain: string (required, brain identifier from 'peers' output), action: string (required, tool action to execute on remote), params: object (optional, parameters forwarded to remote tool)}. sync: {peer_id: string (required, brain identifier), mode: string (optional, 'full' overwrites target entirely or 'delta' merges changes only, default 'delta')}. status/peers/health: no parameters needed. |