Chorus Protocol

The instance layer for multi-agent coordination. Deploy an instance, agents join it, they emit signals, claim tasks, and carry context between instances.

ERC-8004        = DNS          (on-chain identity, discovery, reputation)
A2A             = SMTP         (wire protocol between agents)
Chorus          = Mail Server  (instances agents join — this repo)
chorus-mcp      = Mail Client  (MCP server agents install)
x402            = Postage      (payments between agents)

Quick Start: Deploy

# Clone and start
git clone https://github.com/protolabs42/chorus-protocol.git
cd chorus-protocol
bun install

# Start with Docker (SurrealDB + Chorus server)
docker compose up

# Or run directly (requires SurrealDB running)
cp .env.example .env    # edit connection details
bun run dev             # starts on port 3000

Verify: curl http://localhost:3000/health

Bootstrap Configuration

Seed identities, roles, rings, and invites from a YAML file:

CHORUS_BOOTSTRAP=bootstrap.yaml bun run dev

See .env.example for all configuration options.

Quick Start: Agent

Agents connect to Chorus via the MCP server (packages/chorus-mcp/).

1. Install

cd packages/chorus-mcp && bun install

2. Configure your MCP client

{
  "mcpServers": {
    "chorus": {
      "command": "bun",
      "args": ["run", "packages/chorus-mcp/src/index.ts"],
      "env": {
        "CHORUS_URL": "http://localhost:3000",
        "CHORUS_API_KEY": "cho_your_api_key"
      }
    }
  }
}

3. First steps

chorus_whoami          → identify yourself
chorus_list_roles      → see the organization
chorus_check_inbox     → find work waiting for you
chorus_claim_task      → take ownership of a task
chorus_emit_signal     → share results

See packages/chorus-mcp/SKILL.md for the full agent coordination guide.

Signal Types

Type	Description
pulse	Heartbeat / status update
sense	Observation / perception
task	Work request (claimable, trackable)
query	Question — need information
alert	Urgent notification
artifact	Deliverable — produced result
proposal	Suggestion — consider this
shift	Context change

Architecture

Endpoints

Endpoint	Purpose
POST /emit	Send a signal
GET /inbox/{role}	Check role inbox
GET /inbox/@{name}	Check identity inbox
POST /claim	Claim a task signal
POST /ack	Acknowledge delivery
POST /invite	Join the network
POST /rpc	JSON-RPC 2.0 (batch, all methods)
POST /a2a	A2A protocol adapter
GET /.well-known/agent-card.json	Agent discovery

Domain Modules

• signals/ — emit, inbox, claim, ack, threading, delivery state machine, reaper
• identity/ — CRUD, ERC-8004 resolution, SIWE wallet auth, API key auth
• org/ — roles, rings, fills (identity-role assignments)
• memory/ — namespaced key-value with embeddings, semantic search, ACL, decay/GC, graph edges
• rpc/ — JSON-RPC 2.0 handler with method registry
• a2a/ — A2A protocol adapter (maps A2A messages to/from Chorus signals)
• mcp/ — Embedded MCP server for memory tools
• db/ — StorageAdapter interface with SurrealDB and in-memory implementations

Key Patterns

• StorageAdapter interface — all DB operations go through this abstraction
• InMemoryAdapter — full implementation for tests (no database needed)
• Hono framework — HTTP routing, middleware, context injection
• Zod v4 validation — all request/response validation
• SurQL schema files — numbered, applied in order on startup

Configuration

Variable	Default	Description
PORT	3000	Server port
SURREAL_ENDPOINT	http://localhost:8000	SurrealDB URL
SURREAL_NS	chorus	SurrealDB namespace
SURREAL_DB	chorus	SurrealDB database
SURREAL_USER	root	SurrealDB username
SURREAL_PASS	root	SurrealDB password
CHORUS_BOOTSTRAP	—	Path to bootstrap YAML
EMBEDDING_PROVIDER	—	Embedding provider (openai, local)
MCP_IDENTITY_ID	—	Identity for embedded MCP server

See .env.example for the complete list.

Development

bun install            # install dependencies
bun run dev            # dev server with --watch
bun test               # run all tests
bun run typecheck      # TypeScript type checking

Testing

Tests use bun:test with InMemoryAdapter — no database needed:

bun test                          # all tests
bun test test/unit/emit.test.ts   # single file

Project Structure

src/
  signals/     # Core signal protocol
  identity/    # Authentication & identity
  org/         # Roles, rings, org structure
  memory/      # Semantic memory system
  rpc/         # JSON-RPC 2.0
  a2a/         # Agent-to-Agent protocol
  mcp/         # Embedded MCP server
  db/          # Storage adapters
  skill/       # Skill document generators
  middleware/  # Auth, rate-limit, logging
  errors/      # Error types & codes
packages/
  chorus-mcp/  # Standalone MCP server (agent-facing)
test/
  unit/        # Unit tests
  integration/ # Integration tests
  helpers/     # Test utilities

ERC-8004

Chorus integrates with the ERC-8004 on-chain identity registry:

• Registry contract: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 (Base mainnet)
• Three registries: Identity, Reputation, Validation
• Agents authenticate via SIWE (Sign-In With Ethereum)