Wiki · Features in depth
Sessions and recovery
Closing the terminal loses nothing: conversations are saved automatically, can be found, resumed and handed over elsewhere. Hermes also looks after them.
What a session is
One conversation = one session. It is stored in a single database, so it can be searched and resumed weeks later:
| Where it lives | What is in it |
|---|---|
~/.hermes/state.db | All conversations and their state: messages, tool calls, results, timestamps, token counts, the session title |
Memory (memories/) | Only short notes that apply forever — see Agent memory |
The database runs in a mode that allows readers and one writer at the same time — which is why several parts of Hermes (interfaces, the messaging gateway, scheduled jobs) can look into it without locking each other out.
Resuming a conversation
| With several terminals open | What happens |
|---|---|
You run hermes -c in each of them | Each window resumes its own conversation, not the globally most recent one |
| The conversation was deleted or the breadcrumb is over 30 days old | It falls back to the latest existing conversation |
| You want this off | session.terminal_continue: false in the settings |
Give your conversations names
After the first exchange Hermes invents a short title (three to seven words) so you do not get lost in the list. For your own, use the slash command right in the conversation:
A title must be unique and at most 100 characters; accents and emoji are fine. An automatic title is added once and only if you have not set one yourself.
Overview and housekeeping
| What you want | Command |
|---|---|
| See recent conversations | hermes sessions list (20 by default), … --limit 50 |
| Only from one platform or folder | hermes sessions list --source telegram, … --workspace ~/code/project |
| Summary numbers | hermes sessions stats |
| Pin the important ones | hermes sessions pin <id>, list them with hermes sessions pinned |
| Export a conversation (Markdown, HTML, JSON…) | hermes sessions export --format md --session-id <id> |
| Clean up old conversations | hermes sessions prune --older-than 30 --dry-run (show first) |
| Bring history in from another tool | hermes sessions import --from claude / --from codex |
--dry-run on a cleanup means "just show me what you would delete".
Nothing is removed until you run it without that flag.
How the agent searches past conversations
The agent has a tool that searches the whole history. It makes no model calls — it queries the database full-text, so it is fast and invents nothing:
The practical difference: memory is what the agent always carries with it (and is therefore short), while history search goes deep — and finds what never fit into memory.
Long conversations and their continuations
Every model has a limited context window. When a conversation overflows, Hermes compresses it and continues in a new session in the same lineage — visible in the list as my project, my project #2, #3. Resuming by title always picks the latest continuation.
| Situation | What to do |
|---|---|
| I want to compress it myself | The /compress command inside the conversation |
| I want a clean start | /new — memory is re-read, history stays searchable |
| I want to continue where I left off | hermes -c "project name" — it picks the newest continuation |
Conversations across platforms
A conversation is not tied to one interface. You can start it in the terminal and send it to chat on your phone:
On messaging platforms every chat has its own session (direct message, group, thread). When you ask in a group, the agent remembers that group's context — not your private conversations.
Automatic housekeeping
Without maintenance the database would only grow — on running bots and scheduled jobs it reaches gigabytes within weeks. Hermes therefore cleans up old sessions by itself:
| Setting | Default | What it does |
|---|---|---|
sessions.auto_prune | on | Old sessions are pruned at startup (interface, messaging gateway, scheduled jobs) |
sessions.retention_days | 90 days | How long idle conversations are kept |
sessions.min_interval_hours | 24 hours | How often the sweep may run at all |
The database file only shrinks when there is something to reclaim — that is by design, not a bug. If the setting gets a nonsensical value (negative days, for example), Hermes skips the sweep and logs a warning instead of deleting everything.
Pitfalls from our systems
| What happened | What to do |
|---|---|
| After long work, details disappeared from a conversation | The conversation gets compressed when context fills up — that is normal. Details stay in history: just ask ("search our history for…") |
| We assumed the agent remembered something from a month ago | It was never in memory (which is short). It can be found by searching conversations — but be explicit: "look in the history for how we set up…" |
| The state database grew to hundreds of megabytes | Pruning off plus many platform conversations and scheduled jobs. hermes sessions stats, pin the important ones, then prune with --dry-run |
| Two terminal panes kept resuming the same conversation | -c is terminal-aware, so each pane keeps its own — but only once it has run at least once inside. A brand-new pane starts a new conversation |
Our tips
| Tip | Why |
|---|---|
| Pin or name an important conversation | In a list full of automatic titles you then find the right one in seconds |
A new task gets a new conversation (/new) | The agent starts with clean context and re-reads what it knows about you |
| Export before cleaning up | hermes sessions export gives you a backup to come back to |
| Search history instead of trying to remember | The agent does it full-text and invents nothing — just say what you are looking for |