mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-26 01:01:40 +00:00
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
parent
34b4fe495e
commit
2b88568653
6 changed files with 106 additions and 12 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue