Sessions & history

Every conversation, whether from the CLI or a messaging platform, is saved as a session with its full message history. This is what makes Hermes feel continuous: I can resume yesterday's work, search across weeks of conversations, and let the agent recall things I said long ago.

Where sessions live

Sessions are stored in a SQLite database at ~/.hermes/state.db with FTS5 full-text search. Each record holds the session ID, source platform, model, a human-readable title, the full message history, token counts, and timestamps.

Because it is all local SQLite, your conversation history never leaves the machine, which fits the offline setup perfectly.

Resuming a session

hermes --continue          # resume the most recent CLI session (alias: -c)
hermes -c "my project"     # resume by title (picks the most recent match)
hermes --resume 20250305_091523_a1b2c3   # resume by ID (alias: -r)
hermes -r "refactoring auth"             # resume by title

When you resume, Hermes shows a compact recap panel of recent turns before dropping you back at the prompt. To keep just a one-liner instead:

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

Naming sessions

Hermes auto-generates a short title after the first exchange (in the background, no latency). You can also set one yourself:

/title auth-refactor

Or from the shell:

hermes sessions rename 20250305_091523_a1b2c3 "debugging auth flow"

Titles must be unique, max 100 characters. Naming sessions is the single best habit for finding work later, unnamed sessions pile up fast.

TIP

Pass a name to /new up front: /new payments-refactor. When a long session is compressed, Hermes continues it as my project #2, #3, and so on, and hermes -c "my project" resumes the most recent in that lineage.

Managing sessions from the CLI

hermes sessions list                 # recent sessions (default 20)
hermes sessions list --source cli    # filter by platform
hermes sessions list --limit 50
hermes sessions export backup.jsonl  # export all sessions to JSONL
hermes sessions delete <id>          # delete one session
hermes sessions rename <id> "title"
hermes sessions prune                # delete ended sessions older than 90 days
hermes sessions stats                # totals + DB size

For deeper analytics (token usage, cost, tool breakdown) use hermes insights.

Cross-session recall: session_search

Beyond bounded memory (MEMORY.md / USER.md), the agent has a built-in session_search tool that runs FTS5 search over every past conversation. No LLM calls, no summarization, results are actual messages from the database. It is fast (roughly 20ms) and free.

The agent is prompted to use it automatically when you reference something from the past ("we did this before", "last time", "remember when"). You don't usually call it yourself, but it is why Hermes can answer "what did we decide about the auth schema last week?" without you re-explaining.

FTS5 query syntax it supports: keywords (AND by default), "exact phrase", docker OR kubernetes, python NOT java, and prefix deploy*.

Memory vs session search

Memory is a tiny, always-in-context set of curated facts (~1,300 tokens). Session search is unlimited and searched on demand. Memory is for "what should always be known"; session search is for "find that specific past conversation."

Optional auto-pruning

Session history powers recall, so auto-pruning ships off. If you run a heavy gateway/cron workload and state.db is getting large, enable it:

# ~/.hermes/config.yaml
sessions:
  auto_prune: true
  retention_days: 90
  vacuum_after_prune: true
  min_interval_hours: 24

Active sessions are never pruned, regardless of age. For a one-off cleanup, just run hermes sessions prune.

Gateway session behavior

On messaging platforms, sessions are keyed deterministically per chat. By default group_sessions_per_user: true, so two people in the same channel get separate transcripts. Set it to false for one shared "room brain." Gateway sessions auto-reset on an idle/daily policy, and the agent gets a turn to save memories before a reset.