From 33a3cf5322dc49cdcf45976dbf0175048e45c6f0 Mon Sep 17 00:00:00 2001 From: yoniebans Date: Wed, 20 May 2026 09:30:05 +0200 Subject: [PATCH] docs(sessions): state.db is canonical for gateway messages --- website/docs/user-guide/sessions.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md index e412eefec8f..25dac72aaec 100644 --- a/website/docs/user-guide/sessions.md +++ b/website/docs/user-guide/sessions.md @@ -10,10 +10,9 @@ Hermes Agent automatically saves every conversation as a session. Sessions enabl ## 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 -2. **JSONL transcripts** (`~/.hermes/sessions/`) — raw conversation transcripts including tool calls (gateway) +1. **SQLite database** (`~/.hermes/state.db`) — structured session metadata with FTS5 full-text search, plus full message history The SQLite database stores: - Session ID, source platform, user ID @@ -488,11 +487,18 @@ Sessions with **active background processes** are never auto-reset, regardless o | What | Path | Description | |------|------|-------------| | SQLite database | `~/.hermes/state.db` | All session metadata + messages with FTS5 | -| Gateway transcripts | `~/.hermes/sessions/` | JSONL transcripts per session + sessions.json index | -| Gateway index | `~/.hermes/sessions/sessions.json` | Maps session keys to active session IDs | +| Gateway messages | `~/.hermes/state.db` | SQLite — canonical store for all session messages | +| 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. +:::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 Key tables in `state.db`: