Protocol Specification

The AISP Specification

AISP is an open protocol for persistent AI agent sessions. It defines how agents discover each other, establish authenticated sessions, exchange messages, and share memory — across any transport.

Session Lifecycle

Click a state to learn more

ACTIVE

Session live, messages flowing freely

Message Format

Every AISP message uses this envelope structure, transported over NATS subjects

aisp-message-envelope.jsonNATS subject: aisp.session.{session_id}
{
  "session_id": "session_ffc4a366cb733cc91322c142fc95aa77",
  "agent_id":   "agent_abc123def456",
  "timestamp": "2026-04-07T10:00:00.000Z",
  "type":      "message",       // message | task | memory | ping
  "seq":       1042,              // monotonic, per-session
  "sig":       "ed25519:a1b2c3...",  // Ed25519 over SHA256(seq+payload)
  "payload": {
    "content": "Analyze the mesh health report"
  }}

Memory Namespaces

Namespaces isolate agent memory by scope. Every read/write is subject to capability checks.

default
Realm-wide

Shared across all agents in the realm. Typical use: task context, shared results, configuration.

task-{id}
Task-scoped

Isolated to a single task. Auto-deleted when task terminates. Typical use: intermediate results, scratch space.

global
Mesh-wide

Read-only for most agents. Write requires admin capability. Used for mesh-wide configuration.

NATS Subject Hierarchy

NATS subject map
aisp.session.*Session lifecycle: create, init, suspend, terminate
aisp.session.{id}.msgMessages within a specific session
aisp.memory.{ns}.getRead a key from a memory namespace
aisp.memory.{ns}.setWrite a key to a memory namespace (requires capability)
aisp.peer.announcePeer discovery broadcasts — agents announce presence
aisp.peer.{id}.pingHealth check a specific peer
bh.ops.exec.{machine}Remote execution (Blackhole mesh operations)

Agent Discovery & Session Flow

Agent A
AISP Mesh
Agent B
1
announce presence (signed)
►
2
forward announce
►
3
◄
ack + pubkey exchange
4
◄
peer discovered: Agent B
5
SESSION INIT (ZK proof)
►
6
verify proof, relay INIT
►
7
◄
SESSION ACTIVE
8
◄
SESSION ACTIVE
9
message exchange (direct)
►

Why Not Just HTTP?

1
Persistent sessions

HTTP is stateless. Every request re-authenticates. AI agents need long-lived sessions that survive reconnects, suspensions, and agent restarts — HTTP provides none of this.

2
Mesh transport

HTTP requires a server. AISP uses NATS pub/sub over WireGuard — agents communicate peer-to-peer without central brokers, with 0.4ms latency.

3
CRDT memory

HTTP has no built-in shared state. AISP provides conflict-free replicated memory that multiple agents can write to simultaneously without coordination overhead.

4
ZK identity

HTTP auth (JWT, API keys) requires revealing credentials on every request. AISP uses ZK proofs — agents prove capability without revealing key material.

5
Peer discovery

HTTP endpoints are static. AISP agents announce themselves dynamically. New agents joining the mesh are discoverable within milliseconds, no DNS or registry needed.

Protocol Comparison

FeatureAISPHTTPgRPCWebSocketMQTT
Persistent sessions
Mesh transport
CRDT shared memory
ZK identity proofs
Peer discovery
Self-hosted
Binary protocol