Session Lifecycle

State machine for chat sessions — creation, transitions, branches, and persistence

start + click / /new NEW no title • no messages first message sent title auto-generated ACTIVE receiving messages persists every turn send / receive archive action sidebar context menu ARCHIVED read-only • hidden by default delete action unarchive DELETED removed from sessions.db fork FORK (child session) copies history up to fork point new ACTIVE session ACTIVE (child session) RENAME in-place title update PIN pinned flag set on row ~/.hermes/sessions.db (SQLite) sessions table: id, title, status, pinned, created_at, updated_at messages table: session_id, role, content, tokens, tool_calls Every state transition writes to sessions.db via Hermes Agent REST Survives restarts — UI reloads session list on reconnect all writes In-place ops (no state change): RENAME — updates title field; session stays ACTIVE PIN — sets pinned=true; floats session to top of sidebar

State transitions

  • • NEW: session created, no messages yet, no title
  • • ACTIVE: first message sent; title auto-generated
  • • ARCHIVED: hidden from sidebar by default; read-only
  • • DELETED: removed from sessions.db; unrecoverable

Fork

  • • Creates a new ACTIVE child session
  • • Copies message history up to the fork point
  • • Parent session remains independent and ACTIVE
  • • Useful for exploring alternate conversation branches

Persistence

  • • All state lives in ~/.hermes/sessions.db (SQLite)
  • • Every turn written server-side by Hermes Agent
  • • PIN keeps session at top of the sidebar list
  • • RENAME does an in-place title PATCH via /api/sessions/:id

Hermes Switch UI • session lifecycle • state machine backed by ~/.hermes/sessions.db