Enhance CLI documentation and functionality for session resumption

- Updated README and CLI documentation to include new commands for resuming sessions: `--continue` for the most recent session and `--resume <id>` for specific sessions. - Added examples in the CLI help output and detailed instructions on resuming sessions in the documentation. - Improved user experience by automatically displaying the resume command upon exiting a session.
2026-02-25 23:04:08 -08:00
parent 3c1e31de3e
commit 76badfed63
4 changed files with 78 additions and 13 deletions
--- a/README.md
+++ b/README.md
@@ -339,6 +339,8 @@ HERMES_TOOL_PROGRESS_MODE=all    # or "new" for only when tool changes
 # Chat
 hermes                    # Interactive chat (default)
 hermes chat -q "Hello"    # Single query mode
+hermes --continue         # Resume the most recent session (-c)
+hermes --resume <id>      # Resume a specific session (-r)

 # Provider & model management
 hermes model              # Switch provider and model interactively
@@ -577,8 +579,22 @@ All CLI and messaging sessions are stored in a SQLite database (`~/.hermes/state
 - **FTS5 search** via the `session_search` tool -- search past conversations with Gemini Flash summarization
 - **Compression-triggered session splitting** -- when context is compressed, a new session is created linked to the parent, giving clean trajectories
 - **Source tagging** -- each session is tagged with its origin (cli, telegram, discord, etc.)
+- **Session resume** -- pick up where you left off with `hermes --continue` (most recent) or `hermes --resume <id>` (specific session)
 - Batch runner and RL trajectories are NOT stored here (separate systems)

+When you exit a CLI session, the resume command is printed automatically:
+
+```
+Resume this session with:
+  hermes --resume 20260225_143052_a1b2c3
+
+Session:        20260225_143052_a1b2c3
+Duration:       12m 34s
+Messages:       28 (5 user, 18 tool calls)
+```
+
+Use `hermes sessions list` to browse past sessions and find IDs to resume.
+
 ### 📝 Session Logging

 Every conversation is logged to `~/.hermes/sessions/` for debugging:
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -6,20 +6,24 @@ The Hermes Agent CLI provides an interactive terminal interface for working with

 ```bash
 # Basic usage
-./hermes
+hermes

 # With specific model
-./hermes --model "anthropic/claude-sonnet-4"
+hermes --model "anthropic/claude-sonnet-4"

 # With specific provider
-./hermes --provider nous        # Use Nous Portal (requires: hermes login)
-./hermes --provider openrouter  # Force OpenRouter
+hermes --provider nous        # Use Nous Portal (requires: hermes login)
+hermes --provider openrouter  # Force OpenRouter

 # With specific toolsets
-./hermes --toolsets "web,terminal,skills"
+hermes --toolsets "web,terminal,skills"
+
+# Resume previous sessions
+hermes --continue             # Resume the most recent CLI session (-c)
+hermes --resume <session_id>  # Resume a specific session by ID (-r)

 # Verbose mode
-./hermes --verbose
+hermes --verbose
 ```

 ## Architecture
@@ -238,6 +242,34 @@ This allows you to have different terminal configs for CLI vs batch processing.
 - **Conversations**: Use `/save` to export conversations
 - **Reset**: Use `/clear` for full reset, `/reset` to just clear history
 - **Session Logs**: Every session automatically logs to `logs/session_{session_id}.json`
+- **Resume**: Pick up any previous session with `--resume` or `--continue`
+
+### Resuming Sessions
+
+When you exit a CLI session, a resume command is printed:
+
+```
+Resume this session with:
+  hermes --resume 20260225_143052_a1b2c3
+
+Session:        20260225_143052_a1b2c3
+Duration:       12m 34s
+Messages:       28 (5 user, 18 tool calls)
+```
+
+To resume:
+
+```bash
+hermes --continue                          # Resume the most recent CLI session
+hermes -c                                  # Short form
+hermes --resume 20260225_143052_a1b2c3     # Resume a specific session by ID
+hermes -r 20260225_143052_a1b2c3           # Short form
+hermes chat --resume 20260225_143052_a1b2c3  # Explicit subcommand form
+```
+
+Resuming restores the full conversation history from SQLite (`~/.hermes/state.db`). The agent sees all previous messages, tool calls, and responses — just as if you never left. New messages append to the same session in the database.
+
+Use `hermes sessions list` to browse past sessions and find IDs.

 ### Session Logging

--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -767,6 +767,8 @@ def main():
 Examples:
    hermes                        Start interactive chat
    hermes chat -q "Hello"        Single query mode
+    hermes --continue             Resume the most recent session
+    hermes --resume <session_id>  Resume a specific session
    hermes setup                  Run setup wizard
    hermes login                  Authenticate with an inference provider
    hermes logout                 Clear stored authentication
@@ -776,6 +778,7 @@ Examples:
    hermes config set model gpt-4 Set a config value
    hermes gateway                Run messaging gateway
    hermes gateway install        Install as system service
+    hermes sessions list          List past sessions
    hermes update                 Update to latest version

 For more help on a command:
--- a/skills/autonomous-ai-agents/hermes-agent/SKILL.md
+++ b/skills/autonomous-ai-agents/hermes-agent/SKILL.md
@@ -42,6 +42,20 @@ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scri

 This installs uv, Python 3.11, clones the repo, sets up the venv, and launches an interactive setup wizard to configure your API provider and model. See the [GitHub repo](https://github.com/NousResearch/hermes-agent) for details.

+## Resuming Previous Sessions
+
+Resume a prior CLI session instead of starting fresh. Useful for continuing long tasks across process restarts:
+
+```
+# Resume the most recent CLI session
+terminal(command="hermes --continue", background=true, pty=true)
+
+# Resume a specific session by ID (shown on exit)
+terminal(command="hermes --resume 20260225_143052_a1b2c3", background=true, pty=true)
+```
+
+The full conversation history (messages, tool calls, responses) is restored from SQLite. The agent sees everything from the previous session.
+
 ## Mode 1: One-Shot Query (-q flag)

 Run a single query non-interactively. The agent executes, does its work, and exits:
@@ -145,13 +159,13 @@ For scheduled autonomous tasks, use the `schedule_cronjob` tool instead of spawn

 ## Key Differences Between Modes

-| | `-q` (one-shot) | Interactive (PTY) |
-|---|---|---|
-| User interaction | None | Full back-and-forth |
-| PTY required | No | Yes (`pty=true`) |
-| Multi-turn | Single query | Unlimited turns |
-| Best for | Fire-and-forget tasks | Iterative work, reviews, steering |
-| Exit | Automatic after completion | Send `/exit` or kill |
+| | `-q` (one-shot) | Interactive (PTY) | `--continue` / `--resume` |
+|---|---|---|---|
+| User interaction | None | Full back-and-forth | Full back-and-forth |
+| PTY required | No | Yes (`pty=true`) | Yes (`pty=true`) |
+| Multi-turn | Single query | Unlimited turns | Continues previous turns |
+| Best for | Fire-and-forget tasks | Iterative work, steering | Picking up where you left off |
+| Exit | Automatic after completion | Send `/exit` or kill | Send `/exit` or kill |

 ## Known Issues