Skip to main content

Session Storage

Hermes uses a SQLite-backed session store as the main source of truth for historical conversation state.

Primary files:

  • hermes_state.py
  • gateway/session.py
  • tools/session_search_tool.py

Main database​

The primary store lives at:

~/.hermes/state.db

It contains:

  • sessions
  • messages
  • metadata such as token counts and titles
  • lineage relationships
  • full-text search indexes

What is stored per session​

Examples of important session metadata:

  • session ID
  • source/platform
  • title
  • created/updated timestamps
  • token counts
  • tool call counts
  • stored system prompt snapshot
  • parent session ID after compression splits

Lineage​

When Hermes compresses a conversation, it can continue in a new session ID while preserving ancestry via parent_session_id.

This means resuming/searching can follow session families instead of treating each compressed shard as unrelated.

Gateway vs CLI persistence​

  • CLI uses the state DB directly for resume/history/search
  • gateway keeps active-session mappings and may also maintain additional platform transcript/state files
  • some legacy JSON/JSONL artifacts still exist for compatibility, but SQLite is the main historical store

The session_search tool uses the session DB's search features to retrieve and summarize relevant past work.