Hermes Agent: Sessions and Conversation Context

Introduction

If you've read our previous articles on Hermes Agent, you already know how to launch the agent, configure it with your models, discover its available tools, and master its CLI. But there's a fundamental aspect we haven't covered yet: session and conversation context management.

This is precisely what separates a basic AI agent from a truly persistent assistant. Hermes Agent doesn't just answer isolated questions — it saves every conversation, lets you resume right where you left off, and intelligently manages the context window so long exchanges stay coherent.

In this guide, we'll dive deep into Hermes Agent's session system, from creation to resumption, including automatic context compression and multi-session management best practices.

How Hermes Handles Sessions

Dual Storage System

Hermes Agent stores every conversation in two complementary systems:

• SQLite database (~/.hermes/state.db) — structured metadata with full-text search (FTS5)
• JSONL transcripts (~/.hermes/sessions/) — raw conversation transcripts including tool calls

The SQLite database records: session ID, source platform, user, session title, model used, system prompt, complete message history (role, content, tool calls), token counts, and timestamps.

Automatic Session Creation

Every conversation — whether in CLI, Telegram, Discord, Slack, WhatsApp, or any other platform — automatically creates a new session. You don't need to do anything: Hermes handles everything in the background.

Session IDs follow the format YYYYMMDD_HHMMSS_hex. CLI sessions use a 6-character hex suffix (e.g., 20250305_091523_a1b2c3), while gateway sessions use 8 characters.

Supported Platforms

Each session is tagged with its source platform: cli, telegram, discord, slack, whatsapp, signal, matrix, mattermost, email, sms, and more. This lets you filter and easily find conversations by origin.

Resuming Sessions with --continue and -c

One of Hermes Agent's most useful features is the ability to resume an interrupted conversation without losing context.

Resume the Last Session

# Resume the most recent CLI session
hermes --continue
hermes -c

# With the chat subcommand
hermes chat --continue
hermes chat -c

This command finds the most recent cli session in the SQLite database and loads its complete history. You pick up exactly where you left off.

Resume by Session Name

If you've given your session a title (see below), you can resume it by name:

hermes -c "my backend project"

If there are lineage variants (my backend project, my backend project #2, my backend project #3), Hermes automatically resumes the most recent one.

Resume a Specific Session

For precise resumption, use --resume or -r:

# By full ID or unique prefix
hermes --resume 20250305_091523_a1b2c3d4
hermes -r 20250305_091523_a1b2c3

# By exact title
hermes --resume "refactoring auth"

Session IDs are shown when you exit a CLI session and can be found with hermes sessions list.

Resume Recap

When you resume a session, Hermes displays a styled recap panel before the input prompt:

• User messages (gold ●)
• Assistant responses (green ◆)
• Tool calls summarized (e.g., [3 tool calls: terminal, web_search])
• System messages and tool results hidden
• Maximum 10 exchanges with ... N earlier messages ... indicator
• Limited to 300 chars for user messages and 200 chars / 3 lines for assistant responses

To disable the recap and revert to minimal display:

# ~/.hermes/config.yaml
display:
  resume_display: minimal  # default: full

Listing and Managing Sessions with hermes sessions list

Hermes provides a complete set of management commands via hermes sessions.

Listing Sessions

# 20 most recent sessions (default)
hermes sessions list

# Filter by platform
hermes sessions list --source telegram

# Show more sessions
hermes sessions list --limit 50

When sessions have titles, the output shows the title, a preview, and relative timestamps:

Title                    Preview                           Last Active  ID
────────────────────────────────────────────────────────────────────────────
refactoring auth         Help me refactor the auth module  2h ago       20250305_091523_a
my project #3            Can you check the test failures?  yesterday    20250404_143022_e
—                        What's the weather in Paris?     3d ago       20250303_101500_f

Naming a Session

# During an active conversation (CLI or gateway)
/title my research project

# Show current title
/title

# Rename from the command line
hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"

Title rules: unique, max 100 characters, control characters and RTL overrides stripped automatically. Full Unicode supported (emoji, CJK, accents).

Hermes also automatically generates a descriptive 3-7 word title after the first exchange, via a fast auxiliary model in the background (no added latency).

Exporting a Session

# All sessions to JSONL
hermes sessions export backup.jsonl

# Sessions from a specific platform
hermes sessions export telegram-history.jsonl --source telegram

# Single session
hermes sessions export session.jsonl --session-id 20250305_091523_a1b2c3d4

Deleting and Cleaning Up

# Delete a session (with confirmation)
hermes sessions delete 20250305_091523_a1b2c3d4

# Delete without confirmation
hermes sessions delete 20250305_091523_a1b2c3d4 --yes

# Prune ended sessions older than 90 days
hermes sessions prune

# Custom threshold
hermes sessions prune --older-than 30

# Session statistics
hermes sessions stats

Important: pruning only deletes ended sessions. Active sessions are always preserved.

Slash Commands: /new and /save

/new — Start a New Session

The /new command (available in CLI and gateway platforms) starts a fresh new session within the same Hermes instance. Useful when switching topics without exiting the agent.

# In an active conversation
/new
# → New session created, history reset

/save — Manual Save

The /save command forces an immediate save of the current session. While Hermes auto-saves, /save is useful before a risky operation or to ensure everything is persisted.

Context Window and Automatic Context Management

What is the Context Window?

The context window is the token limit the model can process in a single request. Every message you send, every agent response, and every tool result consumes tokens.

For example, with GPT-4o (128K tokens) or Claude Sonnet (200K tokens), you have a generous window. But in a long conversation with many tool calls, tokens accumulate quickly:

• A code file read = several thousand tokens
• A web search result = 500 to 2000 tokens
• A terminal call with output = potentially thousands of tokens

Compression Threshold

Hermes continuously monitors context window usage. When the configurable threshold is reached (default 50% of the limit), automatic compression triggers.

Configuration in ~/.hermes/config.yaml:

# Compression trigger threshold (fraction of limit)
context:
  compression_threshold: 0.5  # 50% default

Context Compaction: When Context Gets Too Long

How Compaction Works

Compaction is the mechanism by which Hermes compresses conversation history into a more compact summary to free up space in the context window.

The process:

1. Hermes identifies the most important messages (recent + relevant)
2. Older exchanges are summarized by a fast summarization model
3. The summary replaces original messages in the context
4. A new continuation session is automatically created

Session Lineage

When a session is compacted, Hermes creates a child session. If the original has a title, the new one automatically gets a numbered title:

"my project" → "my project #2" → "my project #3"

The child session maintains a link to the parent via the parent_session_id field, allowing full history tracing.

Manual Compaction

You can force compaction at any time:

/compress   # or /compact

Useful when you feel the context is getting heavy and want a fresh start without losing the conversation thread.

Dual Compression System

Hermes Agent uses a dual compression system combined with Anthropic prompt caching to optimize context window usage:

• Standard compaction: conversational summary preserving the essentials
• Context Engine plugin: replaces the built-in compressor with an alternative strategy (lossless compression, etc.)

Multiple Profiles and Session Isolation

Isolated Sessions per User and Channel

On messaging platforms, sessions are automatically isolated:

• DMs: one session per private conversation
• Groups: per user within the group (configurable)
• Channels: per user within the channel

The group_sessions_per_user config (enabled by default) ensures Alice and Bob can talk to Hermes in the same Discord channel without sharing their history.

# ~/.hermes/config.yaml
group_sessions_per_user: true   # per-user isolation (default)
# group_sessions_per_user: false  # shared session for the entire channel

Auto-Reset Policies

Gateway sessions are reset according to configurable policies:

• idle: reset after N minutes of inactivity
• daily: reset at a specific hour each day
• both: reset on whichever comes first
• none: never auto-reset

Important: sessions with active background processes are never auto-reset.

HERMES_HOME Environment Variable

The HERMES_HOME variable defines the root directory for Hermes configuration and data:

# Default: ~/.hermes
export HERMES_HOME=~/.hermes

# For a separate environment
export HERMES_HOME=~/.hermes-work

All data (config, sessions, SQLite database) is stored relative to HERMES_HOME. This is useful for:

• Maintaining separate environments (personal vs professional)
• Testing a new config without touching your main setup
• Isolating sessions from different projects

Best Practices: When to Use /new vs Continuing a Session

When to Continue a Session (-c, --continue)

• Ongoing task: you're working on a bug and want to pick up tomorrow
• Iterative project: development, refactoring, progressive research
• Accumulated context: the agent has already loaded files, understood the architecture
• Continuity: the system prompt and context are relevant for what comes next

When to Use /new

• Radical subject change: switching from development to a general question
• Polluted context: too many unnecessary tool calls weighing down the context
• Fresh start: you want to test something without previous history
• Performance: a lighter context gives faster, more accurate responses

When to Force /compress

• Between two phases of the same long project
• Before starting a complex subtask requiring lots of context
• When you notice the agent losing relevance (sign of saturated context)

Multi-Session Workflow Examples

Workflow 1: Feature Development

# Day 1 — Start
hermes
> /title auth JWT feature
> Implement JWT authentication for the users API

# ... work in progress ...

# Day 2 — Resume
hermes -c "auth JWT feature"
> The tests are failing, fix them

# Day 3 — After compaction
hermes -c "auth JWT feature"  # automatically resumes #2 or #3
> Add refresh token support

Workflow 2: Multi-Source Research

# Session 1: Research
hermes
> /title RAG research
> Research best practices for RAG with LLMs
> /save

# Session 2: Implementation (fresh context)
/new
> /title RAG implementation
> Based on my RAG research, implement a vector pipeline

Workflow 3: Separate Environments with HERMES_HOME

# Terminal 1 — Personal project
HERMES_HOME=~/.hermes-perso hermes
> /title AI blog article

# Terminal 2 — Professional project
HERMES_HOME=~/.hermes-pro hermes
> /title API refactoring

Each environment has its own session database, its own config, and its own search history.

Workflow 4: Searching History with session_search

The agent has a built-in session_search tool that performs full-text search (FTS5) across all past conversations:

hermes
> Have we discussed Docker deployment before?

Hermes automatically uses session_search to find relevant conversations, summarizes them via a fast model, and presents the results with surrounding context.

Supported syntax: simple keywords (docker deployment), exact phrases ("exact phrase"), booleans (docker OR kubernetes), prefixes (deploy*).

Conclusion

Hermes Agent's session system transforms a simple chatbot into a truly persistent assistant. Automatic saving, transparent resumption, and intelligent context management via compaction let you run projects spanning multiple days without information loss.

Key takeaways:

• Every conversation is a session automatically saved in SQLite + JSONL
• hermes -c instantly resumes the last session or a named session
• /new starts a fresh session, /save forces a save
• Automatic compaction manages context when it approaches the limit
• HERMES_HOME lets you isolate work environments
• session_search lets you find any past conversation

In the next article, we'll explore Hermes Agent's advanced features. In the meantime, check out our previous articles to deepen your knowledge.