Sessions

Hermes Agent automatically saves every conversation as a session. Sessions enable conversation resume, cross-session search, and full conversation history management.

How Sessions Work

Every conversation — whether from the CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, or any other messaging platform — is stored as a session with full message history. Sessions are tracked in:

1. SQLite database (~/.hermes/state.db) — structured session metadata with FTS5 full-text search, plus full message history

The SQLite database stores:

• Session ID, source platform, user ID
• Session title (unique, human-readable name)
• Model name and configuration
• System prompt snapshot
• Full message history (role, content, tool calls, tool results)
• Token counts (input/output)
• Timestamps (started_at, ended_at)
• Parent session ID (for compression-triggered session splitting)

What Counts Toward Context

Hermes stores session history so it can resume conversations, but it does not keep re-sending every byte it has ever handled. On each turn, the model sees the selected system prompt, the current conversation window, and any content Hermes explicitly injects for that turn.

Media attachments are handled as turn-scoped inputs:

• Images may be attached natively to the next model call, or pre-analyzed into a text description when the active model does not support native vision.
• Audio is transcribed into text when speech-to-text is configured.
• Text documents can have their extracted text included; other document types are usually represented by a saved local path and a short note.
• Attachment paths and extracted/derived text can appear in the transcript, but the raw image, audio, or binary file bytes are not repeatedly copied into future prompts.

For example, if a user sends an image and asks Hermes to make a meme from it, Hermes may inspect that image once with vision and run an image-processing script. Future turns do not automatically carry the original JPEG in context. They carry only whatever was written into the conversation, such as the user's request, a short image description, a local cache path, or the final assistant response.

The most common cause of context growth is not the media file itself. It is verbose text: pasted transcripts, full logs, large tool outputs, long diffs, repeated status reports, and detailed proof dumps. Prefer summaries, file paths, focused excerpts, and tool-backed lookups over copying large artifacts into chat.

tip

Use /compress when a session gets long, /new for a fresh thread, and hermes sessions prune only when you want to delete old ended sessions from storage. If state.db has simply grown large, start with the non-destructive option first: hermes sessions optimize merges FTS5 index segments and VACUUMs the database without touching any session data. Compression reduces the active context; it is not a privacy delete. Pass a name to /new (e.g. /new payments-refactor) to set the new session's initial title up front — useful for finding it later with /resume <name> or in the /sessions picker.

Session Sources

Each session is tagged with its source platform:

Source	Description
cli	Interactive CLI (hermes or hermes chat)
telegram	Telegram messenger
discord	Discord server/DM
slack	Slack workspace
whatsapp	WhatsApp messenger
signal	Signal messenger
matrix	Matrix rooms and DMs
mattermost	Mattermost channels
email	Email (IMAP/SMTP)
sms	SMS via Twilio
dingtalk	DingTalk messenger
feishu	Feishu/Lark messenger
wecom	WeCom (WeChat Work)
weixin	Weixin (personal WeChat)
bluebubbles	Apple iMessage via BlueBubbles macOS server
qqbot	QQ Bot (Tencent QQ) via Official API v2
homeassistant	Home Assistant conversation
webhook	Incoming webhooks
api-server	API server requests
acp	ACP editor integration
cron	Scheduled cron jobs
batch	Batch processing runs

CLI Session Resume

Resume previous conversations from the CLI using --continue or --resume:

Continue Last Session

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

# Or with the chat subcommand
hermes chat --continue
hermes chat -c

This looks up the most recent cli session from the SQLite database and loads its full conversation history.

Per-Terminal Continue

A bare -c is terminal-aware: each CLI session drops a small breadcrumb file under ~/.hermes/terminal-sessions/ keyed by the terminal it runs in (tty device, tmux pane, kitty window, wezterm pane, Zellij pane, Windows Terminal session, ...). When you run hermes -c again in the same terminal, Hermes resumes that terminal's own session — so two panes side by side each continue their own conversation instead of both grabbing the globally most-recent one. If there's no breadcrumb for the terminal (first use, deleted session, or a stale breadcrumb older than 30 days), -c falls back to the most-recent-session behavior. -c "name" and --resume are unaffected. Disable with session.terminal_continue: false in config.yaml.

Resume by Name

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

# Resume a named session
hermes -c "my project"

# If there are lineage variants (my project, my project #2, my project #3),
# this automatically resumes the most recent one
hermes -c "my project"   # → resumes "my project #3"

Resume Specific Session

# Resume a specific session by ID
hermes --resume 20250305_091523_a1b2c3d4
hermes -r 20250305_091523_a1b2c3d4

# Resume by title
hermes --resume "refactoring auth"

# Resume the most recent session — same lookup as -c
hermes --resume latest

# Or with the chat subcommand
hermes chat --resume 20250305_091523_a1b2c3d4

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

note

latest is a reserved keyword for --resume. A session literally titled "latest" is still reachable by its ID or via -c latest (title match).

Resume in a Specific Directory

Pass --in <dir> to change into a directory before starting or resuming. Combined with --resume latest (or -c), the most recent session for that directory's workspace is picked — no need to cd first or remember session IDs:

# Resume the latest session that belongs to ./my-project
hermes --resume latest --in ./my-project

# Works with the TUI too
hermes --tui --resume latest --in ./my-project

--in also pins the session to that directory: the resumed session's recorded working directory is not restored (as if --no-restore-cwd were passed).

Resume Restores the Working Directory

Resuming a CLI session also cds back into the session's recorded working directory (its git repo root or project dir), so the conversation picks up in the workspace it belonged to. If you'd rather stay where you are, pass --no-restore-cwd:

hermes --resume 20250305_091523_a1b2c3 --no-restore-cwd

A ↪ restored workspace dir: … line confirms the switch. Restore failures never break the resume itself.

Filtering Sessions by Workspace

hermes sessions list accepts --workspace <needle> to show only sessions whose workspace key (git repo root, else cwd) matches — by path substring or exact directory basename:

hermes sessions list --workspace my-project
hermes sessions list --workspace ~/code/hermes-agent

Conversation Recap on Resume

When you resume a session, Hermes displays a compact recap of the previous conversation in a styled panel before the input prompt:

Resume mode shows a compact recap panel with recent user and assistant turns before returning you to the live prompt.

The recap:

• Shows user messages (gold ●) and assistant responses (green ◆)
• Truncates long messages (300 chars for user, 200 chars / 3 lines for assistant)
• Collapses tool calls to a count with tool names (e.g., [3 tool calls: terminal, web_search])
• Hides system messages, tool results, and internal reasoning
• Caps at the last 10 exchanges with a "... N earlier messages ..." indicator
• Uses dim styling to distinguish from the active conversation

To disable the recap and keep the minimal one-liner behavior, set in ~/.hermes/config.yaml:

display:
  resume_display: minimal   # default: full

tip

Session IDs follow the format YYYYMMDD_HHMMSS_<hex> — CLI/TUI sessions use a 6-char hex suffix (e.g. 20250305_091523_a1b2c3), gateway sessions use an 8-char suffix (e.g. 20250305_091523_a1b2c3d4). You can resume by ID (full or unique prefix) or by title — both work with -c and -r.

Cross-Platform Handoff

Use /handoff <platform> from a CLI session to transfer the live conversation to a messaging platform's home channel. The agent picks up exactly where the CLI left off — same session id, full role-aware transcript, tool calls and all.

# Inside a CLI session
/handoff telegram

What happens:

1. The CLI validates that <platform> is enabled and has a home channel set (run /sethome from the destination chat once to configure it).

2. The CLI marks the session pending and block-polls the gateway. It refuses if the agent is mid-turn — wait for the current response to finish first.

3. The gateway watcher claims the handoff and asks the destination adapter for a fresh thread:

   • Telegram — opens a new forum topic (DM topics if Bot API 9.4+ Topics mode is enabled in the chat, or a forum supergroup topic).
   • Discord — creates a 1440-min auto-archive thread under the home text channel.
   • Slack — posts a seed message and uses its ts as the thread anchor.
   • WhatsApp / Signal / Matrix / SMS — no native threads, falls back to the home channel directly.

4. The gateway re-binds the destination key to your existing CLI session id, then forges a synthetic user turn asking the agent to confirm and summarize. The reply lands in the new thread.

5. When the gateway acknowledges success, the CLI prints a /resume hint and exits cleanly:

   ↻ Handoff complete. The session is now active on telegram.
     Resume it on this CLI later with: /resume my-session-title

6. From that point, the conversation lives on the platform. Reply in the new thread — anyone authorized in that channel shares the same session, and any later real user message in the thread joins seamlessly because thread sessions key without user_id.

Resume back to CLI: when you want to come back to a desktop, just run /resume <title> (or hermes -r "<title>" from the shell) and pick up where the platform left off.

Failure modes:

• No home channel configured → CLI refuses with a /sethome hint.
• Platform not enabled / gateway not running → CLI times out at 60s with a clear message and your CLI session stays intact.
• Thread creation fails (permissions, topics-mode off) → falls back to the home channel directly and still completes; no thread isolation but the handoff itself works.
• adapter.send fails (rate limit, transient API error) → handoff marked failed with the reason; the row clears so you can retry.

Limitation worth knowing: for non-thread-capable platforms with multi-user group home channels, the synthetic turn keys as a DM-style session. This works for self-DM home channels (the typical setup) but isn't ideal for genuinely shared group chats. Threading covers Telegram / Discord / Slack — by far the common case — so most setups never hit this.

Session Naming

Give sessions human-readable titles so you can find and resume them easily.

Auto-Generated Titles

Hermes automatically generates a short descriptive title (3–7 words) for each session after the first exchange. This runs in a background thread using a fast auxiliary model, so it adds no latency. You'll see auto-generated titles when browsing sessions with hermes sessions list or hermes sessions browse.

Auto-titling only fires once per session and is skipped if you've already set a title manually.

Setting a Title Manually

Use the /title slash command inside any chat session (CLI or gateway):

/title my research project

The title is applied immediately. If the session hasn't been created in the database yet (e.g., you run /title before sending your first message), it's queued and applied once the session starts.

You can also rename existing sessions from the command line:

hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"

Title Rules

• Unique — no two sessions can share the same title
• Max 100 characters — keeps listing output clean
• Sanitized — control characters, zero-width chars, and RTL overrides are stripped automatically
• Normal Unicode is fine — emoji, CJK, accented characters all work

Auto-Lineage on Compression

When a session's context is compressed (manually via /compress or automatically), Hermes creates a new continuation session. If the original had a title, the new session automatically gets a numbered title:

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

When you resume by name (hermes -c "my project"), it automatically picks the most recent session in the lineage.

/title in Messaging Platforms

The /title command works in all gateway platforms (Telegram, Discord, Slack, WhatsApp):

• /title My Research — set the session title
• /title — show the current title

Session Management Commands

Hermes provides a full set of session management commands via hermes sessions:

List Sessions

# List recent sessions (default: last 20)
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 titles, previews, and relative timestamps:

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

When no sessions have titles, a simpler format is used:

Preview                                            Last Active   Src    ID
──────────────────────────────────────────────────────────────────────────────────────
Help me refactor the auth module please             2h ago        cli    20250305_091523_a
What's the weather in Las Vegas?                    3d ago        tele   20250303_101500_f

Export Sessions

hermes sessions export is one surface for every export format, selected with --format:

Format	Output	Use it for
jsonl (default)	one JSON object per session	backups, machine round-trip
md / qmd	one Markdown/Quarto file per session + manifest	readable archives, notes
html	single self-contained page (sidebar for multi-session)	sharing, browsing
trace	Claude Code JSONL	HF Agent Trace Viewer, --upload

Plus --only user-prompts for a prompts-only view (jsonl or md).

All formats share the same selection knobs: --session-id for one session, or the full prune/archive filter set for bulk — --older-than / --newer-than / --before / --after (durations like 5h/2d/1w, bare days, or ISO timestamps), --source, --title, --model, --provider, --cwd, --min/--max-messages, --min/--max-tokens, --min/--max-cost, --min/--max-tool-calls, --user, --chat-id, --chat-type, --branch, --end-reason. --dry-run previews the match set without writing. --redact scrubs secrets (API keys, tokens, credentials) from exported content on any format — recommended for anything you plan to share. Note: bulk filters match ended sessions; unfiltered export dumps everything, including active ones.

JSONL (default)

# Export all sessions to a JSONL file
hermes sessions export backup.jsonl

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

# Export a single session
hermes sessions export session.jsonl --session-id 20250305_091523_a1b2c3d4

# Redact API keys/tokens/credentials from the exported content
hermes sessions export backup.jsonl --redact

Exported files contain one JSON object per line with full session metadata and all messages.

HTML

--format html writes a single self-contained HTML file — no remote dependencies — with styled message bubbles, collapsible tool output, and (for multi-session exports) a sidebar to switch between sessions:

# One session as a standalone HTML page
hermes sessions export --format html --session-id 20250305_091523_a1b2c3d4 transcript.html

# All Telegram sessions from the last week in one file, secrets redacted
hermes sessions export --format html --newer-than 1w --source telegram --redact archive.html

Prompts Only

--only user-prompts exports just the prompts you wrote — no assistant replies, tool output, or system context. Useful for building prompt libraries or reviewing what you asked:

# One JSONL record per prompt (session id, index, timestamp, text)
hermes sessions export prompts.jsonl --session-id 20250305_091523_a1b2c3d4 --only user-prompts

# Markdown, straight to stdout
hermes sessions export - --session-id 20250305_091523_a1b2c3d4 --only user-prompts --format md

Works with --format jsonl (default) or md, honors the same filters for bulk export, and combines with --redact.

Traces (HF Agent Trace Viewer)

--format trace emits Claude Code JSONL — the transcript shape the Hugging Face Hub auto-detects for its Agent Trace Viewer. Write it locally, or add --upload to push it to your own private hermes-traces dataset (reads HF_TOKEN):

# Trace of the most recent session, to stdout
hermes sessions export --format trace

# One session to a local trace file
hermes sessions export --format trace --session-id 20250305_091523_a1b2c3d4 trace.jsonl

# Upload straight to your private HF traces dataset
hermes sessions export --format trace --session-id 20250305_091523_a1b2c3d4 --upload

Trace exports are secret-redacted by default (they're meant to leave the machine); --no-redact opts out after manual review. --upload is private unless --public. Bulk trace export with filters writes one <id>.trace.jsonl per session.

Markdown / QMD

Pass --format md or --format qmd when you want a readable, file-based archive before hiding or deleting old sessions. Markdown/QMD exports write one file per session into a directory (default: ~/.hermes/session-exports).

# Export one session to Markdown
hermes sessions export --format md --session-id 20250305_091523_a1b2c3d4

# Export a compression lineage as one logical document
hermes sessions export --format md --session-id 20250305_091523_a1b2c3d4 --lineage logical

# Preview ended sessions older than 90 days without writing files
hermes sessions export --format md --older-than 90 --dry-run

# Export ended Telegram sessions older than 2 weeks to QMD files
hermes sessions export --format qmd --older-than 2w --source telegram

# Export long Claude sessions, secrets redacted
hermes sessions export --format md --model sonnet --min-messages 50 --redact

# Only after verification, export and delete one explicitly named session
hermes sessions export --format md --session-id 20250305_091523_a1b2c3d4 --delete-after-verified --yes

Markdown/QMD export writes one .md or .qmd file per exported session plus a manifest.jsonl with the file path, message count, lineage ids, and SHA-256. Bulk export requires at least one filter; a bare bulk export is refused. --delete-after-verified is intentionally limited to --session-id and requires --yes. Because deleting a parent session also removes its delegate/subagent sessions, this mode exports and verifies each delegate in a separate file before deleting anything. If the delegate set changes during export, deletion is refused. --redact scrubs secrets (API keys, tokens, credentials) from message content and tool output before writing — recommended for any export you plan to share.

Delete a Session

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

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

Rename a Session

# Set or change a session's title
hermes sessions rename 20250305_091523_a1b2c3d4 "debugging auth flow"

# Multi-word titles don't need quotes in the CLI
hermes sessions rename 20250305_091523_a1b2c3d4 debugging auth flow

If the title is already in use by another session, an error is shown.

Pin a Session

Pinning sets a durable "keep" flag: pinned sessions are exempt from the sessions.auto_archive stale sweep and always appear in listings. It is the same flag the Desktop sidebar's Pinned section uses — pin from either surface and both see it.

# Pin one or more sessions (unique ID prefixes work)
hermes sessions pin 20250305_091523_a1b2c3d4
hermes sessions pin 20250305 20250306

# Remove the pin
hermes sessions unpin 20250305_091523_a1b2c3d4

# List pinned sessions
hermes sessions pinned

# Machine-readable output, e.g. for a nightly backup of your pin set
hermes sessions pinned --json > pinned-sessions.json

Prune Old Sessions

# Delete ended sessions inactive for 90 days (default)
hermes sessions prune

# Custom age threshold — bare numbers are days
hermes sessions prune --older-than 30

# Durations work too: 5h, 30m, 2d, 1w
hermes sessions prune --older-than 12h

# Delete only a specific time window (e.g. a batch of test sessions
# created in the last 5 hours)
hermes sessions prune --newer-than 5h

# Explicit window with absolute timestamps
hermes sessions prune --after "2026-07-05 09:00" --before "2026-07-05 14:30"

# Only prune sessions from a specific platform (all ages — any filter
# disables the implicit 90-day default)
hermes sessions prune --source telegram
hermes sessions prune --source cron --older-than 60   # add a time flag to narrow

# More filters — all AND together
hermes sessions prune --newer-than 5h --title "smoke test"   # title substring
hermes sessions prune --older-than 30 --max-messages 3        # tiny sessions
hermes sessions prune --cwd ~/scratch --end-reason done       # by cwd / end reason
hermes sessions prune --model gpt-5 --older-than 1w           # by model (substring)
hermes sessions prune --provider openrouter --older-than 60   # by billing provider
hermes sessions prune --branch feature/old-experiment         # by git branch
hermes sessions prune --user 12345678 --chat-type group       # by messaging origin
hermes sessions prune --max-tokens 500 --older-than 7         # by token usage
hermes sessions prune --max-cost 0.01 --max-tool-calls 0      # cheap, tool-less runs

# Preview what would be deleted, without deleting anything
hermes sessions prune --newer-than 5h --dry-run

# Skip confirmation
hermes sessions prune --older-than 30 --yes

Time values (--older-than, --newer-than, --before, --after) accept a duration (5h, 30m, 2d, 1w), a bare number of days, or an ISO timestamp (2026-07-05, 2026-07-05 14:30). --older-than/--before set the upper bound; --newer-than/--after set the lower bound. The --older-than/--newer-than pair uses latest message activity (falling back to session start for empty sessions); --before/--after explicitly uses session start time. Combine either pair for a window.

Attribute filters: --source (platform, exact), --title / --model / --branch (case-insensitive substring), --provider (billing provider, exact), --end-reason, --user, --chat-id, --chat-type (exact), --cwd (path prefix), plus numeric bounds --min/--max-messages, --min/--max-tokens (input+output), --min/--max-cost (USD, actual falling back to estimated), and --min/--max-tool-calls. Using any filter disables the implicit 90-day default, so hermes sessions prune --source cron or --model gpt-4o matches all ages — add a time flag to narrow it. Only a completely bare hermes sessions prune keeps the 90-day cutoff. Every non---yes run shows the match count plus the oldest and newest matching session before asking for confirmation.

Archived sessions are skipped by default; pass --include-archived to delete them too.

info

Pruning only deletes ended sessions (sessions that have been explicitly ended or auto-reset). Active sessions are never pruned.

Bulk-Archive Sessions

If you want sessions out of your listings without deleting anything, hermes sessions archive takes the same filters as prune but soft-hides matching sessions instead (sets the same archived flag as archiving a single session from the Desktop/Dashboard UI — messages and search stay intact):

# Archive everything from the last 5 hours (e.g. 75 CI smoke-test sessions)
hermes sessions archive --newer-than 5h

# Archive by title substring, preview first
hermes sessions archive --title "dry run" --dry-run
hermes sessions archive --title "dry run" --yes

At least one filter is required — a bare hermes sessions archive refuses to archive your entire history. Archived sessions are hidden from hermes sessions list and