common/hermes
2
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(sessions): state.db is canonical for gateway messages

Browse Source
This commit is contained in:
yoniebans
2026-05-20 09:30:05 +02:00
committed by Teknium
parent b4b118c201
commit 33a3cf5322
1 changed files with 11 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
website/docs/user-guide/sessions.md
View File

@@ -10,10 +10,9 @@ Hermes Agent automatically saves every conversation as a session. Sessions enabl
## How Sessions Work ## How Sessions Work
Every conversation — whether from the CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, or any other messaging platform — is stored as a session with full message history. Sessions are tracked in two complementary systems: Every conversation — whether from the CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, or any other messaging platform — is stored as a session with full message history. Sessions are tracked in:
1. **SQLite database** (`~/.hermes/state.db`) — structured session metadata with FTS5 full-text search 1. **SQLite database** (`~/.hermes/state.db`) — structured session metadata with FTS5 full-text search, plus full message history
2. **JSONL transcripts** (`~/.hermes/sessions/`) — raw conversation transcripts including tool calls (gateway)
The SQLite database stores: The SQLite database stores:
- Session ID, source platform, user ID - Session ID, source platform, user ID
@@ -488,11 +487,18 @@ Sessions with **active background processes** are never auto-reset, regardless o
| What | Path | Description | | What | Path | Description |
|------|------|-------------| |------|------|-------------|
| SQLite database | `~/.hermes/state.db` | All session metadata + messages with FTS5 | | SQLite database | `~/.hermes/state.db` | All session metadata + messages with FTS5 |
| Gateway transcripts | `~/.hermes/sessions/` | JSONL transcripts per session + sessions.json index | | Gateway messages | `~/.hermes/state.db` | SQLite — canonical store for all session messages |
| Gateway index | `~/.hermes/sessions/sessions.json` | Maps session keys to active session IDs | | Gateway routing index | `~/.hermes/sessions/sessions.json` | Maps session keys to active session IDs (origin metadata, expiry flags) |
The SQLite database uses WAL mode for concurrent readers and a single writer, which suits the gateway's multi-platform architecture well. The SQLite database uses WAL mode for concurrent readers and a single writer, which suits the gateway's multi-platform architecture well.
:::note Legacy JSONL transcripts
Sessions created before state.db became canonical may have leftover
`*.jsonl` files in `~/.hermes/sessions/`. They are no longer written or
read by Hermes. Safe to delete after verifying the corresponding session
exists in state.db.
:::
### Database Schema ### Database Schema
Key tables in `state.db`: Key tables in `state.db`: