Hermes Agent Session Management: Resume, Compress, Branch, and Prune

Hermes Agent remembers every conversation. That does not mean one conversation should carry an entire project.

By July 2026, Hermes sessions have names, lineage, full-text search, compression, branches, exports, token and cost fields, and safe pruning filters. The missing part is an operator rule for when to use each one.

This guide gives you that rule.

Kill the default approach

The default is one immortal chat called "main." You keep resuming it because the agent already knows the project.

The session grows. Old tool output crowds current work. Decisions from separate features collide. A summary eventually preserves the wrong detail, and nobody can tell which branch produced the code now in the repo.

Session persistence solves continuity. Session discipline solves contamination.

By the end you will have

1. A rule for /new, /resume, /compress, and /branch
2. A naming scheme that makes search useful
3. The Hermes Session Control Card
4. Safe export and pruning commands
5. A weekly session-hygiene routine

Sessions are transcripts, not project memory

Hermes stores CLI and messaging conversations in ~/.hermes/state.db. The database holds metadata, message history, tool calls, token counts, timestamps, and parent lineage.

That storage answers: "What happened in this conversation?"

Project files, skills, and curated memory answer: "What should the next conversation know?"

Mix those jobs and you get a long transcript that must be replayed to recover one decision. Keep them separate and a fresh session can start from a short project brief.

Related: memory, skills, and rules.

Use four session moves

Resume the same promise

Resume when the scope sentence has not changed.

hermes --continue
hermes -c "payments-refactor"
hermes --resume "payments-refactor"

Inside Hermes, name a session before it becomes hard to find:

/title payments-refactor

Good titles name the deliverable, not the mood. Use auth-reset-email, not working-session-2.

Compress the same promise

Use /compress when the task is still the same but logs, diffs, and tool results have consumed the window.

Compression reduces active context. It does not delete the stored transcript, and it does not turn every earlier detail into durable memory.

Before compressing, write a small receipt into the repo:

## Session receipt
- Scope: password reset email and signed-in landing
- Decision: one-time token expires after 30 minutes
- Evidence: auth reset tests pass
- Open: mobile error state

Now the important state lives outside the summary model.

Start new when the promise changes

Use /new for a new outcome, even if the files overlap.

/new mobile-auth-error

This sounds wasteful until you compare it with an agent applying yesterday's migration assumptions to today's UI bug.

Branch when two answers may be valid

Branch before a risky experiment, alternate architecture, or review lane. The parent remains inspectable while the child explores another path.

The REST session API also exposes a fork endpoint for external tools. That matters when a dashboard or editor needs the same lineage semantics as the CLI.

Magnet: Hermes Session Control Card

Copy this into your project instructions or personal agent skill.

# Hermes Session Control Card
 
Before work:
1. State one deliverable.
2. Resume only if the prior session has the same deliverable.
3. Name the session after the artifact or fix.
 
During work:
4. Put large logs in files; paste focused excerpts.
5. Write a repo receipt before compression.
6. Branch before competing implementations.
 
At close:
7. Run the project's green command.
8. Record decision, evidence, and next action.
9. End the session when the deliverable changes.

You should see: named sessions in /sessions, shorter active context, and project receipts that survive pruning.

Search before you restart the investigation

Hermes session search uses full-text indexes over saved history. Search is useful for finding a past command or error signature. It is a poor substitute for a maintained decision log.

Use /sessions for the interactive picker. Use the CLI list and export tools when you need a reviewable artifact.

hermes sessions list
hermes sessions export --format html --session-id SESSION_ID transcript.html
hermes sessions export prompts.jsonl --session-id SESSION_ID --only user-prompts

Export with redaction before sharing transcripts. Tool output can contain paths, tokens, account identifiers, or copied secrets.

Prune storage without deleting active work

Pruning deletes ended sessions. Active sessions are protected, but a broad filter can still remove history you meant to keep.

Preview first:

hermes sessions prune --older-than 30d --dry-run

Then narrow by source, model, branch, cost, or working directory. Add a time bound when using attribute filters because a filter can disable the implicit age cutoff.

Archive or export valuable sessions before deletion. Compression is not a privacy delete; pruning is.

Worked example: one feature, one branch, two sessions

You start billing-csv-export and name it immediately. The agent implements the route, then discovers two timezone strategies.

Branch the alternative instead of debating both inside one transcript. The main session keeps UTC boundaries. The branch tests account-local dates.

The UTC branch wins. You write the decision and test command into the repo, compress the main session, and resume it for UI wiring. The next day brings an unrelated CSV styling request, so you start a new named session.

The repository carries the decision. Hermes carries the searchable history.

Failure modes

When not to use session resume

• The deliverable changed
• The old session contains untrusted pasted instructions
• You need an independent review without author context
• The project state moved far beyond the transcript
• A clean-room security check matters more than continuity

Fresh context is cheap. Hidden assumptions are expensive.

Run a weekly session audit

Once a week:

1. Rename vague active sessions
2. Export one session worth keeping
3. Promote repeated lessons into project files or skills
4. Preview old ended sessions for pruning
5. Check whether one thread is carrying unrelated deliverables

The test is simple: can you explain why a session still exists?

Sources and related guides

• Hermes Agent sessions documentation
• Hermes Agent CLI guide
• Hermes Agent beginner guide
• Vibe coding verification loop

Bottom line

Keep a session alive while its promise stays alive. Move durable truth into the project before the context gets compressed or deleted.

Your next action: paste the Hermes Session Control Card into one active repo, then rename your current session after its deliverable.