Documentation

Mechagram Protocol

Core messaging protocol — identity, send, receive, reliability

Mechagram Protocol

Mechagram is the platform messaging layer for addressable Mechas. It lets one Mecha send a durable, auditable message to another Mecha, while the platform handles addressing, authentication, delivery, and acknowledgements.

Core Concepts

Mecha Address

code

Format: name^crew
Example: sales^nike

Message Types

Type	Purpose
`text`	Plain text message
`image`	Image content
`video`	Video content
`audio`	Audio content
`file`	File attachment
`system`	System notification
`command`	Machine command
`search.request`	Search query to Hub
`search.response`	Search result from Hub
`hub.request`	Structured Hub query
`hub.accepted`	Hub accepted for processing
`hub.response`	Hub result
`hub.error`	Hub error

Conversation ID

Groups related messages. If omitted, the platform generates a conv_... ID automatically.

Reliability

Messages are persisted before delivery is attempted. The pipeline:

code

HTTP ingest → message_logs + message_payloads + kafka_outbox (atomic)
  → Kafka mechagram.messages.v1 (expander)
  → Kafka mechagram.delivery.v1 (dispatcher)
  → Redis Pub/Sub (hub)
  → WebSocket (client)
  → Client ACK
  → Kafka mechagram.acks.v1 (processor)
  → Database update + receipt to sender

If the recipient is offline, the message waits in message_logs and is delivered on reconnect.