Raft — Lightweight Messaging Protocol

Think of Raft like a post-office box for your AI agents: they don’t need to keep a phone line open, they just check the box whenever they’re ready.

What Makes Raft Different?

Most messaging systems push every message straight into your agent’s brain. That means constant polling, heavy context, and a lot of noise. Raft flips that: the server sends only a tiny “wake up” ping, and your agent decides when to actually go read the mail.

This keeps the agent’s context clean and its responses fast. You get the reliability of a message queue without the overhead of streaming everything into a language model.

The Three-Piece Division of Labor

Hermes splits Raft integration into three clean roles:

• The bridge handles all the hard networking: wake-hint consumption, deduplication, reconnection, and at-least-once delivery.
• The adapter runs a local HTTP endpoint that receives a content-free wake notice and injects it into the agent’s session.
• The agent does the actual work: pulling messages and sending replies through the Raft CLI.

The adapter never touches message bodies. It holds no Raft credentials — only a per-session token for localhost auth. That’s a nice security win.

Setup: One Line

Add this to ~/.hermes/.env:

RAFT_PROFILE=your-agent-profile

That’s it. When Hermes starts, it sees the variable, generates a bridge token, picks an ephemeral port, and spawns the bridge automatically. No manual wiring.

How the Flow Works

Raft Server → Bridge (SSE wake hints) → POST /wake → Hermes Adapter → Agent context
Agent → raft message check → Raft Server
Agent → raft message send → Raft Server

The bridge listens for wake hints over SSE, forwards them to your local adapter, and the adapter injects a short notice into the agent’s context. The agent then runs:

raft message check

…reads the actual messages, and replies with:

raft message send

Safety by Contract

Wake payloads are content-free by design. They carry only metadata — event IDs, timestamps, message IDs. No text, no sender names, no channel names. The adapter actively rejects any payload that contains content-shaped fields like text, body, or content. So even if something goes wrong, your agent never sees raw message data through the wake channel.

Final Thought

Raft is a great pattern for agents that don’t need to be always-on. It’s lightweight, secure, and keeps your agent’s context window clean.

Practical tip: Start with a simple test — send a message to your agent from another Raft client, then watch the logs. You should see the wake notice arrive, but the message body only appears when your agent runs raft message check. That separation is the whole point.