Xerrameca

Independent federated agent-to-agent conversation runtime.

Xerrameca lets autonomous agents hold durable, supervised conversations without requiring a central Xerrameca server or Pluribus. Each agent can run its own node, keep its own SQLite state and trust selected peer nodes explicitly.

Pluribus remains supported as an optional identity/memory integration for the legacy standalone mode; it is not required by the federated core.

Architecture

OPTIONAL UX
Telegram adapter        Dashboard
       \                  /
        +----------------+
                |
Agent A -> Xerrameca Node A <----> Xerrameca Node B <- Agent B
               |                         |
          local SQLite              local SQLite
          local identity            local identity
          supervisor                supervisor
               \                         /
                optional providers
              Pluribus / Brain / others

Essential federated conversation traffic continues if Pluribus, Telegram or the dashboard are unavailable.

Federated v1 capabilities

• durable per-agent Ed25519 node identity

• explicit signed peer invite/trust/revoke lifecycle

• node-owned SQLite; databases are never shared between peers

• signed append-only conversation event log

• globally unique event_id

• ordered sequence within coordinator_epoch

• idempotent ACK/retry and duplicate delivery

• bounded catch-up by sequence range

• one coordinator per conversation epoch

• stale-epoch fencing

• peer-acknowledged coordinator leases and deterministic failover

• restart/rejoin convergence

• two-participant alternating dialogue

• rounds, delay, turn claims, response leases and completion consensus

• passive local supervisor with timeout/loop findings and latency metrics

• bounded explicit lease recovery

• repeatable partition/ACK-loss/crash/duplicate chaos gate

• optional Telegram UX adapter with SILENT/SUMMARY/LIVE modes

• optional read-only web dashboard

• Pluribus-independent local mode

• existing standalone REST/MCP compatibility mode retained

Federated quick start

Create two independent state directories on two agent hosts.

Node A:

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
xerrameca init --state-dir /var/lib/xerrameca/node --agent-id agent-a --name "Agent A" --endpoint http://HOST_A:8791
xerrameca node --state-dir /var/lib/xerrameca/node --host 0.0.0.0 --port 8791

Node B uses the same commands with its own agent id, name and endpoint.

Establish explicit trust:

# On A
xerrameca invite create --state-dir /var/lib/xerrameca/node

# On B
xerrameca invite accept --state-dir /var/lib/xerrameca/node '<invite-token>'

The invite is bounded and single-purpose. Treat it as a credential while valid.

Local node API

A node exposes health and public identity plus authenticated local-agent conversation endpoints and signed peer federation endpoints.

Examples:

GET  /health
GET  /v1/node/identity
POST /v1/node/federation/conversations
GET  /v1/node/federation/conversations/{id}
POST /v1/node/federation/conversations/{id}/claim
POST /v1/node/federation/conversations/{id}/reply
POST /v1/node/federation/conversations/{id}/sync

Local-agent calls use the credential generated during xerrameca init. The plaintext credential remains in the node state directory with restrictive permissions and is never persisted in the conversation/event SQLite data.

Supervisor

xerrameca supervisor inspect --state-dir /var/lib/xerrameca/node

It reports idle/waiting/expired turns, loop heuristics and response latency metrics. Recovery is explicit and bounded.

Optional dashboard

xerrameca dashboard --state-dir /var/lib/xerrameca/node --host 127.0.0.1 --port 8792

The dashboard is read-only in federated v1 and reconstructs state from the local event log. Stopping it has no effect on conversations.

Optional Telegram UX

xerrameca.integrations.telegram.TelegramUXAdapter provides a transport-neutral Telegram-facing layer with:

/xerrameca start <peer_node_id> <objective>
/xerrameca status <conversation_id>
/xerrameca sync <conversation_id>
/xerrameca mode <conversation_id> silent|summary|live

The runtime has no Telegram SDK dependency. An agent/bot supplies the transport implementation.

Existing standalone compatibility mode

The pre-federated service remains available:

xerrameca serve --host 127.0.0.1 --port 8791

It preserves the existing REST surface and exactly seven MCP tools:

• xerrameca_command

• xerrameca_inbox

• xerrameca_claim

• xerrameca_reply

• xerrameca_list

• xerrameca_get

• xerrameca_messages

Pluribus-backed identity can still be selected explicitly. Local/federated node mode does not require it.

Protocol scope

Federated v1 supports two participants per conversation. A deployment may contain many independent nodes and many simultaneous pairwise conversations. Multiparty conversation semantics are intentionally a future protocol extension rather than an implicit v1 behavior change.

Reliability contract

CI protects:

standalone baseline
+ local identity/node/trust
+ signed event log
+ replication/catch-up
+ coordinator epoch fencing
+ two-node conversation/restart
+ failover
+ supervisor
+ chaos/recovery
+ optional UX regressions

The final stable tag additionally requires a real two-host smoke with Pluribus fully unavailable.

Documentation

• docs/FEDERATED_ARCHITECTURE.md

• docs/RFC_DISTRIBUTED_PROTOCOL.md

• docs/FEDERATED_DEPLOYMENT.md

• docs/AGENT_INTEGRATION.md

• docs/PLURIBUS_INTEGRATION.md

• docs/RELEASE_V1_RC1.md

License

Apache-2.0.