HHermes Explained

Runtime

Session State

The durable and transient records that let a session continue coherently across turns.

Importance 4/53 backlinks1 source refs

Session State

What it is

The durable and transient records that let a session continue coherently across turns.

In plain terms

Slipping a bookmark into a thick novel lets you set the book down for weeks and pick back up on the exact page and sentence you left off, without rereading every chapter that came before. Session state is Hermes’s version of that bookmark: what was said and decided, kept ready for whenever the conversation picks back up.

Why it matters

Continuing a conversation where it left off only works because turn_finalizer writes durable and transient records after each turn, and turn context reads them back in at the start of the next one. Strip this away and every message would have to re-establish context from scratch, which defeats the point of a session versus a stateless API call. Compression governs how much of this state survives long-term, while session search is what lets a user retrieve it again later.

How it works

After each turn, _persist_session (run_agent.py) writes the message history to state.db, a SQLite store that’s the canonical record — an optional JSON snapshot per session can also be enabled for external tooling, but the database is what Hermes actually reads from. Writes are deduplicated with a marker stamped onto already-flushed messages, so repeated persistence calls from different exit paths don’t create duplicate rows. At the start of the next turn, agent/turn_context.py’s build_turn_context step restores the system prompt and splices the prior exchanges back into the conversation before the model ever sees the new message. Later, a dedicated session-search tool (tools/session_search_tool.py) lets a user query back through that stored history directly, independent of whatever’s still active in the live conversation.

A concrete example

A user spends Monday afternoon working through a multi-step project with Hermes, then closes the terminal without formally ending the session. Wednesday morning they reopen it: the same session ID picks the conversation back up mid-thread, with Monday’s history and system prompt restored exactly as left — no re-explaining the project from scratch. A week later, unable to remember which file a script lived in, they run a session search and pull up the exact exchange where it was mentioned.

How it connects

This note belongs to the Runtime family. Its closest neighboring concepts are: Compression, Agent Runtime, Personal OS.

Source evidence

  • vendor/hermes-agent/agent/turn_finalizer.py#<file> — Structural Source Map fallback for agent/turn_finalizer.py. A core source file in the Conversation Turn Loop structure within Agent Runtime.

Workflows

  • No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
  • Inside Hermes: How the Agent Loop, Context, Memory, Gateways, and Cron Jobs Work Together
  • How to Use Hermes Better Than Most People: Architecture, Project Isolation, and Scalable Workflows
  • Ten Hermes Workflows That Turn a Chatbot into a 24/7 Assistant