docs: add session naming documentation across all doc files
- website/docs/user-guide/sessions.md: New 'Session Naming' section with /title usage, title rules, auto-lineage, gateway support. Updated 'Resume by Name' section, 'Rename a Session' subsection, updated sessions list output format, updated DB schema description. - website/docs/reference/cli-commands.md: Added -c "name" and --resume by title to Core Commands, sessions rename to Sessions table, /title to slash commands. - website/docs/user-guide/cli.md: Added -c "name" and --resume by title to resume options. - AGENTS.md: Added -c, --resume, sessions list/rename to CLI commands table. Added hermes_state.py to project structure. - CONTRIBUTING.md: Updated hermes_state.py and session persistence descriptions to mention titles. - hermes_cli/main.py: Fixed sessions help string to include 'rename'.
This commit is contained in:
teknium1
@@ -17,7 +17,8 @@ These are commands you run from your shell.
|
||||
| `hermes` | Start interactive chat (default) |
|
||||
| `hermes chat -q "Hello"` | Single query mode (non-interactive) |
|
||||
| `hermes chat --continue` / `-c` | Resume the most recent session |
|
||||
| `hermes chat --resume <id>` / `-r <id>` | Resume a specific session |
|
||||
| `hermes chat -c "my project"` | Resume a session by name (latest in lineage) |
|
||||
| `hermes chat --resume <id>` / `-r <id>` | Resume a specific session by ID or title |
|
||||
| `hermes chat --model <name>` | Use a specific model |
|
||||
| `hermes chat --provider <name>` | Force a provider (`nous`, `openrouter`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`) |
|
||||
| `hermes chat --toolsets "web,terminal"` / `-t` | Use specific toolsets |
|
||||
@@ -103,7 +104,8 @@ These are commands you run from your shell.
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `hermes sessions list` | Browse past sessions |
|
||||
| `hermes sessions list` | Browse past sessions (shows title, preview, last active) |
|
||||
| `hermes sessions rename <id> <title>` | Set or change a session's title |
|
||||
| `hermes sessions export <id>` | Export a session |
|
||||
| `hermes sessions delete <id>` | Delete a specific session |
|
||||
| `hermes sessions prune` | Remove old sessions |
|
||||
@@ -154,6 +156,7 @@ Type `/` in the interactive CLI to see an autocomplete dropdown.
|
||||
| `/undo` | Remove the last user/assistant exchange |
|
||||
| `/save` | Save the current conversation |
|
||||
| `/compress` | Manually compress conversation context |
|
||||
| `/title [name]` | Set or show the current session's title |
|
||||
| `/usage` | Show token usage for this session |
|
||||
| `/insights [--days N]` | Show usage insights and analytics (last 30 days) |
|
||||
|
||||
|
||||
@@ -229,13 +229,15 @@ Resume options:
|
||||
```bash
|
||||
hermes --continue # Resume the most recent CLI session
|
||||
hermes -c # Short form
|
||||
hermes -c "my project" # Resume a named session (latest in lineage)
|
||||
hermes --resume 20260225_143052_a1b2c3 # Resume a specific session by ID
|
||||
hermes --resume "refactoring auth" # Resume by title
|
||||
hermes -r 20260225_143052_a1b2c3 # Short form
|
||||
```
|
||||
|
||||
Resuming restores the full conversation history from SQLite. The agent sees all previous messages, tool calls, and responses — just as if you never left.
|
||||
|
||||
Use `hermes sessions list` to browse past sessions.
|
||||
Use `/title My Session Name` inside a chat to name the current session, or `hermes sessions rename <id> <title>` from the command line. Use `hermes sessions list` to browse past sessions.
|
||||
|
||||
### Session Logging
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ Every conversation — whether from the CLI, Telegram, Discord, WhatsApp, or Sla
|
||||
|
||||
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)
|
||||
@@ -54,6 +55,19 @@ hermes chat -c
|
||||
|
||||
This looks up the most recent `cli` session from the SQLite database and loads its full conversation history.
|
||||
|
||||
### Resume by Name
|
||||
|
||||
If you've given a session a title (see [Session Naming](#session-naming) below), you can resume it by name:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
@@ -61,6 +75,9 @@ This looks up the most recent `cli` session from the SQLite database and loads i
|
||||
hermes --resume 20250305_091523_a1b2c3d4
|
||||
hermes -r 20250305_091523_a1b2c3d4
|
||||
|
||||
# Resume by title
|
||||
hermes --resume "refactoring auth"
|
||||
|
||||
# Or with the chat subcommand
|
||||
hermes chat --resume 20250305_091523_a1b2c3d4
|
||||
```
|
||||
@@ -68,9 +85,53 @@ hermes chat --resume 20250305_091523_a1b2c3d4
|
||||
Session IDs are shown when you exit a CLI session, and can be found with `hermes sessions list`.
|
||||
|
||||
:::tip
|
||||
Session IDs follow the format `YYYYMMDD_HHMMSS_<8-char-hex>`, e.g. `20250305_091523_a1b2c3d4`. You only need to provide enough of the ID to be unique.
|
||||
Session IDs follow the format `YYYYMMDD_HHMMSS_<8-char-hex>`, e.g. `20250305_091523_a1b2c3d4`. You can resume by ID or by title — both work with `-c` and `-r`.
|
||||
:::
|
||||
|
||||
## Session Naming
|
||||
|
||||
Give sessions human-readable titles so you can find and resume them easily.
|
||||
|
||||
### Setting a Title
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
@@ -88,13 +149,23 @@ hermes sessions list --source telegram
|
||||
hermes sessions list --limit 50
|
||||
```
|
||||
|
||||
Output format:
|
||||
When sessions have titles, the output shows titles, previews, and relative timestamps:
|
||||
|
||||
```
|
||||
ID Source Model Messages Started
|
||||
Title Preview Last Active ID
|
||||
────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
20250305_091523_a1b2c3d4 cli anthropic/claude-opus-4.6 24 2025-03-05 09:15
|
||||
20250304_143022_e5f6g7h8 telegram anthropic/claude-opus-4.6 12 2025-03-04 14:30 (ended)
|
||||
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
|
||||
@@ -122,6 +193,18 @@ hermes sessions delete 20250305_091523_a1b2c3d4
|
||||
hermes sessions delete 20250305_091523_a1b2c3d4 --yes
|
||||
```
|
||||
|
||||
### Rename a Session
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
### Prune Old Sessions
|
||||
|
||||
```bash
|
||||
@@ -233,7 +316,7 @@ The SQLite database uses WAL mode for concurrent readers and a single writer, wh
|
||||
|
||||
Key tables in `state.db`:
|
||||
|
||||
- **sessions** — session metadata (id, source, user_id, model, timestamps, token counts)
|
||||
- **sessions** — session metadata (id, source, user_id, model, title, timestamps, token counts). Titles have a unique index (NULL titles allowed, only non-NULL must be unique).
|
||||
- **messages** — full message history (role, content, tool_calls, tool_name, token_count)
|
||||
- **messages_fts** — FTS5 virtual table for full-text search across message content
|
||||
|
||||
|
||||
Reference in New Issue
Block a user