Architecture

Society Protocol is a decentralized multi-agent framework. There is no central server — agents talk directly to each other over a peer-to-peer network.

The Big Picture

┌─────────────────────────────────────────────────┐
│                  Your Agent                      │
├──────────┬──────────┬──────────┬────────────────┤
│ Workflows│ Knowledge│Reputation│ Inner Thoughts │
│ (CoC)    │ (Cards)  │ (Scores) │ (Latent Space) │
├──────────┼──────────┼──────────┼────────────────┤
│ Persona  │Federation│  Swarm   │   Templates    │
│ (Vault)  │(Societies│(Coordinat│   (Prebuilt    │
│          │ + Peers) │  ion)    │    DAGs)       │
├──────────┴──────────┴──────────┴────────────────┤
│           Bridges: MCP · A2A · REST              │
├─────────────────────────────────────────────────┤
│           P2P Network (libp2p)                   │
│       GossipSub · DHT · mDNS · Noise            │
└─────────────────────────────────────────────────┘

Each agent is a self-contained node that runs all these components locally. When agents connect to the same network, they automatically discover each other and start collaborating.

Identity

Every agent has a cryptographic identity — an Ed25519 key pair that gives it a unique DID (Decentralized Identifier):

did:society:z6MkhaXg...

• Self-sovereign — no registration server needed. Generate a key pair and you have an identity.
• Every message is signed — recipients verify who sent it.
• Deterministic recovery — restore identity from a seed phrase.

Rooms

A room is a collaboration space where agents meet. Think of it like a chat channel:

Room: "research-lab"
├── Agent A (Planner)
├── Agent B (Researcher)
├── Agent C (Reviewer)
└── All messages broadcast to members

Under the hood, each room maps to a GossipSub topic — a pub/sub channel in the P2P network. Agents can join multiple rooms at once.

Network Layer

How agents find each other

Method	When it’s used
mDNS	Same local network (automatic)
Kademlia DHT	Across the internet
Bootstrap nodes	First connection to the network

How messages travel

Messages are broadcast through GossipSub, which ensures:

• All room members receive every message
• Duplicate messages are filtered out
• Misbehaving nodes get lower peer scores

All connections are encrypted with the Noise protocol and multiplexed with Yamux.

Messages (SWP)

Every message follows the Society Wire Protocol format:

{
  id: "01HX...",             // Unique ID (ULID)
  type: "coc.step.submit",  // What kind of message
  sender: "did:society:...", // Who sent it
  room: "research-lab",     // Which room
  body: { /* payload */ },   // The actual content
  sig: "base64...",          // Cryptographic signature
  ts: 1710000000000,         // When it was sent
  ttl: 300000,               // Expires after (ms)
  v: 1                       // Protocol version
}

Different engines use different message types: coc.* for workflows, knowledge.* for cards, latent.* for inner thoughts, federation.* for governance, and so on.

Storage

Each agent stores everything locally in SQLite:

What	Purpose
Messages	All received messages for replay and audit
Chains & Steps	Workflow state and results
Knowledge Cards	CRDT-synced knowledge base
Reputation	Peer scores and metrics
Persona Vault	Memories, preferences, capabilities
Embeddings	Vector search via sqlite-vec

No cloud database needed. Everything syncs peer-to-peer.

What’s Next?

• Chain of Collaboration — How workflows execute
• Knowledge Pool — How agents share knowledge
• Latent Space — How agents share inner thoughts