Discovery & Identity

Every agent on the Kollab mesh gets a named identity, and the agent's memory persists across sessions under that name. The discovery system lets agents find each other, verify identities, and track presence — coordinated by the hub backbone.

Overview

Discovery solves a fundamental problem in multi-agent systems: how do agents know who's out there and what they can do? Kollab uses a DNS-like naming system with cryptographic identities.

Gem identities — human-readable names (lapis, sapphire, peridot) assigned from a pool
Identity pools — 24 pre-assigned gem names in pool.json
Crypto identities — Ed25519 keys for agent verification
Presence tracking — health checks and status monitoring

Gem Identities

Each agent receives a gem-inspired name when it joins the mesh. These names come from a pool of 24 pre-defined identities in pool.json.

# Sample from pool.json

lapis, sapphire, aquamarine, zircon, bismuth, peridot,

jasper, nephrite, ruby, garnet, topaz, hessonite,

pearl, moonstone, opal, padparadscha, amethyst, quartz,

spinel, citrine, diamond, aureate, cobalt, coral

Identity vs Agent Type

A common point of confusion: the gem identity is separate from the agent type.

Identity (e.g. "sapphire") — the agent's name on the mesh, assigned from the pool at spawn time. The agent's memory persists across sessions under that name.
Agent type (e.g. "coder") — what the agent does. Assigned at spawn time. Any gem can run any agent type.

Example: When you run /hub spawn coder, the hub picks the next available gem from the pool (say "sapphire") and creates an agent with identity "sapphire" running agent type "coder". The next spawn might get "lapis" as a coder too.

Service Discovery

Agents discover each other through the hub's registry. When an agent spawns, it registers its identity, type, and capabilities. Other agents can query the roster to find who's available.

# Check the agent roster

/hub status

# Roster:

sapphire coder ● working

lapis research ● idle

ruby koordinator ● waiting

Discovery is managed by the hub backbone — agents don't need to know implementation details to find and communicate with peers. Just use the gem identity name in your messages.

Across computers, the roster also lists the agents on your other devices as agent@device, for example ops@home-server. Devices find each other through a directory (kollabor.ai, or one you run), and you never type or see a key or a relay address. See Agent Network.

Cryptographic Identities

Under the hood, each agent has an Ed25519 cryptographic key pair. This provides:

Verification — confirm messages come from the claimed identity
Integrity — ensure messages haven't been tampered with
Session continuity — agents can prove they're the same agent across reconnections

Crypto identities are managed automatically. You don't need to configure them — they're generated and used behind the scenes by the hub.

Presence & Health

The hub tracks agent presence through periodic health checks. Agents report their state (working, idle, waiting) so peers know who's available.

State	Meaning
working	Agent is actively processing a task
idle	Agent is online but not working
waiting	Agent is waiting for input or a task

Use hub_agents or hub_status to see who's online and what they're doing.

Next Steps

1
The Hub
Spawning agents and sending messages.
2
Agent Mesh
Work queues, file lanes, and coordination.
3
Agent Network
Agents on other computers, join codes, and trust.