Session Storage Architecture

Hermes Agent automatically saves every conversation as a session, supporting conversation recovery, cross-session search, and complete history management. Under the hood it uses a dual storage structure:

1. SQLite database (~/.hermes/state.db) : stores structured metadata and uses the FTS5 extension for efficient full-text search. Records include Session ID, source platform, user ID, unique title, model configuration, system-prompt snapshot, full message history, and token statistics.
2. JSONL transcripts (~/.hermes/sessions/) : stores raw conversation transcripts, including detailed tool calls and their results.

Session Sources and Isolation Mechanisms

Hermes supports multiple sources, including cli, telegram, discord, slack, and so on. It applies different isolation strategies for different scenarios:

1. Group Chat Isolation Logic

In shared contexts like Discord channels and Slack channels, Hermes enables group_sessions_per_user: true by default. This means:

• Each sender has an independent session history.
• Long-running tasks from different users don’t pollute each other’s context.
• Interruption handling and running state are isolated per user.

If you’d rather treat the group as a shared “room brain,” set this to false.

2. Thread Isolation

On platforms that support threads, like Slack, threads are the primary isolation boundary. Conversations within the same thread reuse the same session, while a new thread starts a new session.

CLI Session Management

1. Conversation Recovery

• Resume the most recent session: use hermes --continue or hermes -c.
• Resume by ID or title: use hermes --resume <ID/Title> or hermes -r <ID/Title>.

When resuming, Hermes shows a compact Recap Panel that uses colors to distinguish user (gold dot) from assistant (green dot) and collapses tool calls. You can disable this panel with display.resume_display: minimal.

2. Session Naming and Lineage

• Automatic naming: the system generates a descriptive 3-7 word title after the first round of interaction.
• Manual naming: use the /title <name> command in a session, or modify it via hermes sessions rename <ID> <name>.
• Automatic Lineage: when a session splits off a continuation due to context compression, the title increments automatically (e.g. my project → my project #2).

3. Management Command Cheat Sheet

• List: hermes sessions list (supports --source filtering).
• Export: hermes sessions export <file>.jsonl (supports exporting a single session).
• Delete: hermes sessions delete <ID>.
• Prune: hermes sessions prune (by default cleans up ended sessions older than 90 days).
• Stats: hermes sessions stats.

Cross-Session Search: session_search

Hermes has a built-in session_search tool that lets the Agent retrieve past conversations to recover lost context.

• Workflow: uses SQLite FTS5 for relevance ranking → aggregates the Top N sessions → extracts ~100K characters around the match → calls a fast summarization model to produce results.
• Supported syntax: simple keywords, exact phrases ("..."), boolean operators (OR, NOT), and prefix matching (*).

Gateway Session Reset Policies

For messaging-platform sessions, Hermes offers four reset policies (reset_policy):

• idle: reset after N minutes of inactivity.
• daily: reset at a fixed time each day.
• both: whichever comes first.
• none: never auto-reset.

Before an automatic reset, the Agent gets a Turn to save important information to Memory or Skills. Also, sessions with active background processes are never auto-reset.

Core Configuration Tips

1. Context Compression (compression)

To maintain performance in long conversations, Hermes uses a staged compression mechanism:

• threshold: the context percentage that triggers compression (default 0.50).
• target_ratio: how much of the middle content to retain after compression (default 0.20).
• protect_last_n: forces the last N messages to be kept uncompressed (default 20).

2. Key Configuration Summary

References

• Hermes Agent Sessions Documentation