The Session Lifecycle: From Launch to Compaction

+15 Mana ✨
Hermes Quickstart(DOCUMENTATION)

Introduction

When you run hermes, a lot happens before your first message reaches the model, and much more happens between turns. Understanding the lifecycle helps you recognize what the agent is doing, why it pauses where it does, and what each step costs you in tokens and time.

Key Concepts

  • Launch: Hermes loads your config, opens state.db, picks up the most recent session (or starts a new one), and contacts the model provider.
  • Turn: One round-trip, your message, the model's response, possibly tool calls and their results.
  • Compaction: When the conversation grows past a threshold, Hermes summarizes older turns to free up context for new ones.
  • Persistence: Every message and tool result is written to state.db as it happens.

Real World Context

If you have ever wondered why a long conversation seems to "speed up" suddenly, you are observing compaction. Hermes detected that the context window was filling up, summarized the older history, and replaced it with a compressed summary so future turns have headroom. The conversation feels continuous to you; the model is actually working with a smaller, condensed history.

Deep Dive

What happens at launch

text
1. Read config       → which provider, which model, which tools
2. Open state.db     → your session store and memory
3. Resume?           → if --continue, pick up most recent session
4. Greet             → display banner, available skills, status bar
5. Wait for input    → the prompt is yours

What happens on each turn

text
1. You send a message
2. Hermes assembles context: system prompt + memory + history + your turn
3. The provider returns a response, possibly with tool calls
4. If tool calls: Hermes executes them and sends results back
5. The provider returns a final user-facing response
6. State is written to state.db
7. The status bar updates (tokens, cost, time)

What happens at compaction

When the context window approaches its limit, Hermes triggers a compaction:

text
Old turns (1..N-k)    →  Summary (one or two messages)
Recent turns (N-k..N) →  Kept verbatim

The summary is also persisted, so you can audit what was condensed. From your perspective, the agent's recall feels uninterrupted; under the hood, the prompt got smaller.

Common Pitfalls

  1. Treating each turn as ephemeral, Every message is durable in state.db. There is no "undo this turn", there is /rollback to a checkpoint, and there is starting a new session.
  2. Worrying about compaction destroying memory, Compaction is summarization, not deletion. The agent keeps a condensed view; the raw messages remain in state.db.

Best Practices

  1. Watch the status bar near token limits, If it shows you near the model's context limit, expect a compaction soon and write a clear "save this" message before it fires.
  2. Start a fresh session for new tasks, Long sessions accumulate context that is irrelevant to a new problem. A new session is faster and cheaper.

Summary

  • A Hermes session has a clear lifecycle: launch → turns → compaction → persist.
  • Every turn is written to state.db; nothing is purely ephemeral.
  • Compaction summarizes older turns when the context window fills up.
  • Knowing the lifecycle helps you read the status bar and time your prompts.

Code Examples

markdown
Turn 1   ─►  context: system + your turn                        (small)
Turn 12  ─►  context: system + 11 turns of history + your turn   (growing)
Turn 30  ─►  context: 90% full → compaction fires
            ─►  context: system + summary of turns 1..20 + turns 21..29 + yours  (small again)
✓ Completed