Tutorial 8: Session Management

This is part of the Hermes Agent official tutorial series. View all tutorials

Think of a session like a bookmark in a video game — you can pause your conversation, walk away, come back days later, and pick up exactly where you left off, with all your progress saved.

Hermes Agent automatically saves every conversation as a “session.” Whether you’re chatting from your terminal, Telegram, Discord, Slack, WhatsApp, or any other platform, Hermes remembers everything. This tutorial shows you how to use that superpower.

---

Step 1: Understand Where Your Conversations Live

Every session is stored in a single file on your computer: a SQLite database at ~/.hermes/state.db. Think of it as a giant filing cabinet with two drawers:

• Session metadata — who you talked to, which platform, the session’s title, which model you used, and timestamps.
• Full message history — every single message, tool call, and result, stored in a searchable format.

The database even supports full-text search (FTS5), so you can find that one conversation about “pizza toppings” from three months ago in milliseconds.

---

Step 2: Know What Goes Into Context (and What Doesn’t)

Here’s the key insight: Hermes saves everything, but it doesn’t re-read everything on every turn. Each time you send a message, the model only sees:

• The system prompt (your custom instructions)
• The current conversation window (recent messages)
• Anything Hermes explicitly injects for that turn

Media files are handled smartly:

• Images — either attached natively (if your model supports vision) or pre-analyzed into a short text description.
• Audio — transcribed into text first.
• Documents — extracted text is included; binary files are saved as paths, not re-sent.

Example: If you send a cat photo and ask Hermes to make a meme, it looks at the image once, runs a script, and writes the result into the conversation. Next turn, it doesn’t carry the original JPEG — just the description and the meme text.

The real context hog is text. Pasted transcripts, full logs, giant tool outputs, long diffs — these bloat your context window fast. The docs give this golden advice:

Prefer summaries, file paths, focused excerpts, and tool-backed lookups over copying large artifacts into chat.

---

Step 3: Use the Three Key Commands

Here are the commands you’ll use daily:

# In a long session, compress it to free up context
/compress

# Start a fresh thread (optionally with a name for easy finding later)
/new payments-refactor

# Resume a previous session by name
/resume payments-refactor

The /sessions picker shows all your past sessions — just scroll and pick.

---

Step 4: Manage Your Database (Without Panic)

If your state.db file grows large, don’t panic and don’t delete things yet. Try the non-destructive option first:

# Merges search index segments and cleans up the database (safe, keeps all data)
hermes sessions optimize

Only when you truly want to delete old, ended sessions from storage:

# Deletes old ended sessions (use with caution)
hermes sessions prune

Important: Compression (/compress) reduces the active context window — it does not delete your history. It’s like summarizing a long meeting, not shredding the notes.

---

Step 5: Know Your Session Sources

Each session is tagged with where it came from:

Source	Description
cli	Interactive terminal (run hermes or hermes chat)
telegram	Telegram messenger
discord	Discord server or DM
slack	Slack workspace
whatsapp	WhatsApp messenger

This helps you search and filter sessions by platform.

---

Summary

Session management is your memory superpower. Hermes saves everything automatically, but it’s smart about what it re-sends. Use /compress for long chats, /new with a name for fresh threads, and hermes sessions optimize when the database gets heavy. You’ll never lose a conversation again.

Next up: Tutorial 9 — we’ll explore how to search your entire conversation history with powerful queries, so you can find that one brilliant idea you had weeks ago.