Chat Message Lifecycle

What happens between pressing Enter and seeing tokens land in the message thread

You browser Switch UI port 3000 Hermes Agent port 8642 AI Provider Anthropic / OpenAI / etc. ~/.hermes/ persistent storage 0 ms ~50 ms ~100 ms ~300 ms streaming complete post 1. Type prompt and press Enter composer.onSubmit 2. POST /api/send REST • session_id, message, attachments 3. Forward prompt + tool defs API call • provider router selects endpoint 4. Stream tokens (multi-chunk) SSE / chunked transfer • delta events 5. SSE chunks /api/chat-events EventSource • text deltas, tool calls, status 6. Render tokens live Zustand chat-store updates • message thread paints 7. Persist session + extracted memory writes • sessions.db, memory/, MEMORY.md Transport cyan = Switch UI ↔ Agent (REST/SSE) emerald = Agent ↔ Provider/Agent-side SSE violet = storage write

What's streaming?

  • • Server-Sent Events (SSE) over plain HTTP
  • • Provider emits tokens as it generates them
  • • Agent relays each chunk to Switch UI live
  • • Switch UI appends to the assistant bubble token-by-token

What gets persisted?

  • • Full message thread saved in ~/.hermes/sessions.db
  • • Memory facts extracted into memory/
  • • Session metadata (model, tokens, cost)
  • • Survives restarts; reload to resume

What about errors?

  • • Provider error → Agent returns error SSE event
  • • Switch UI shows error inline in message thread
  • • Common: invalid API key, rate limit, context overflow
  • • See Models not appearing or Agent won't connect

Hermes Switch UI • chat message lifecycle • REST request, SSE response, persistent storage