From 2b8856865339d23c575d1a72c9308f9123c727a5 Mon Sep 17 00:00:00 2001 From: teknium1 Date: Sun, 8 Mar 2026 16:09:31 -0700 Subject: [PATCH] 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'. --- AGENTS.md | 6 ++ CONTRIBUTING.md | 4 +- hermes_cli/main.py | 2 +- website/docs/reference/cli-commands.md | 7 +- website/docs/user-guide/cli.md | 4 +- website/docs/user-guide/sessions.md | 95 ++++++++++++++++++++++++-- 6 files changed, 106 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cc66a5c7..a7318fd3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,7 @@ hermes-agent/ ├── skills/ # Bundled skill sources ├── optional-skills/ # Official optional skills (not activated by default) ├── cli.py # Interactive CLI orchestrator (HermesCLI class) +├── hermes_state.py # SessionDB — SQLite session store (schema, titles, FTS5 search) ├── run_agent.py # AIAgent class (core conversation loop) ├── model_tools.py # Tool orchestration (thin layer over tools/registry.py) ├── toolsets.py # Tool groupings @@ -226,6 +227,9 @@ The unified `hermes` command provides all functionality: |---------|-------------| | `hermes` | Interactive chat (default) | | `hermes chat -q "..."` | Single query mode | +| `hermes -c` / `hermes --continue` | Resume the most recent session | +| `hermes -c "my project"` | Resume a session by name (latest in lineage) | +| `hermes --resume ` | Resume a specific session by ID or title | | `hermes -w` / `hermes --worktree` | Start in isolated git worktree (for parallel agents) | | `hermes setup` | Configure API keys and settings | | `hermes config` | View current configuration | @@ -240,6 +244,8 @@ The unified `hermes` command provides all functionality: | `hermes gateway` | Start gateway (messaging + cron scheduler) | | `hermes gateway setup` | Configure messaging platforms interactively | | `hermes gateway install` | Install gateway as system service | +| `hermes sessions list` | List past sessions (title, preview, last active) | +| `hermes sessions rename ` | Rename/title a session | | `hermes cron list` | View scheduled jobs | | `hermes cron status` | Check if cron scheduler is running | | `hermes version` | Show version info | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9679d79d..6ed6c833 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,7 +118,7 @@ hermes-agent/ ├── cli.py # HermesCLI class — interactive TUI, prompt_toolkit integration ├── model_tools.py # Tool orchestration (thin layer over tools/registry.py) ├── toolsets.py # Tool groupings and presets (hermes-cli, hermes-telegram, etc.) -├── hermes_state.py # SQLite session database with FTS5 full-text search +├── hermes_state.py # SQLite session database with FTS5 full-text search, session titles ├── batch_runner.py # Parallel batch processing for trajectory generation │ ├── agent/ # Agent internals (extracted modules) @@ -218,7 +218,7 @@ User message → AIAgent._run_agent_loop() - **Self-registering tools**: Each tool file calls `registry.register()` at import time. `model_tools.py` triggers discovery by importing all tool modules. - **Toolset grouping**: Tools are grouped into toolsets (`web`, `terminal`, `file`, `browser`, etc.) that can be enabled/disabled per platform. -- **Session persistence**: All conversations are stored in SQLite (`hermes_state.py`) with full-text search. JSON logs go to `~/.hermes/sessions/`. +- **Session persistence**: All conversations are stored in SQLite (`hermes_state.py`) with full-text search and unique session titles. JSON logs go to `~/.hermes/sessions/`. - **Ephemeral injection**: System prompts and prefill messages are injected at API call time, never persisted to the database or logs. - **Provider abstraction**: The agent works with any OpenAI-compatible API. Provider resolution happens at init time (Nous Portal OAuth, OpenRouter API key, or custom endpoint). - **Provider routing**: When using OpenRouter, `provider_routing` in config.yaml controls provider selection (sort by throughput/latency/price, allow/ignore specific providers, data retention policies). These are injected as `extra_body.provider` in API requests. diff --git a/hermes_cli/main.py b/hermes_cli/main.py index 5ba09c35..49f271f7 100644 --- a/hermes_cli/main.py +++ b/hermes_cli/main.py @@ -1724,7 +1724,7 @@ For more help on a command: # ========================================================================= sessions_parser = subparsers.add_parser( "sessions", - help="Manage session history (list, export, prune, delete)", + help="Manage session history (list, rename, export, prune, delete)", description="View and manage the SQLite session store" ) sessions_subparsers = sessions_parser.add_subparsers(dest="sessions_action") diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index 55fd8504..7f03f50a 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -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) | diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md index d80b178b..314fc326 100644 --- a/website/docs/user-guide/cli.md +++ b/website/docs/user-guide/cli.md @@ -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 diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md index 92f6e121..e99a725d 100644 --- a/website/docs/user-guide/sessions.md +++ b/website/docs/user-guide/sessions.md @@ -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