| --- |
| sidebar_position: 8 |
| title: "Session Storage" |
| description: "How Hermes stores sessions in SQLite, maintains lineage, and exposes recall/search" |
| --- |
| |
| # Session Storage |
|
|
| Hermes uses a SQLite-backed session store as the main source of truth for historical conversation state. |
|
|
| Primary files: |
|
|
| - `hermes_state.py` |
| - `gateway/session.py` |
| - `tools/session_search_tool.py` |
|
|
| ## Main database |
|
|
| The primary store lives at: |
|
|
| ```text |
| ~/.hermes/state.db |
| ``` |
|
|
| It contains: |
|
|
| - sessions |
| - messages |
| - metadata such as token counts and titles |
| - lineage relationships |
| - full-text search indexes |
|
|
| ## What is stored per session |
|
|
| Examples of important session metadata: |
|
|
| - session ID |
| - source/platform |
| - title |
| - created/updated timestamps |
| - token counts |
| - tool call counts |
| - stored system prompt snapshot |
| - parent session ID after compression splits |
|
|
| ## Lineage |
|
|
| When Hermes compresses a conversation, it can continue in a new session ID while preserving ancestry via `parent_session_id`. |
|
|
| This means resuming/searching can follow session families instead of treating each compressed shard as unrelated. |
|
|
| ## Gateway vs CLI persistence |
|
|
| - CLI uses the state DB directly for resume/history/search |
| - gateway keeps active-session mappings and may also maintain additional platform transcript/state files |
| - some legacy JSON/JSONL artifacts still exist for compatibility, but SQLite is the main historical store |
|
|
| ## Session search |
|
|
| The `session_search` tool uses the session DB's search features to retrieve and summarize relevant past work. |
|
|
| ## Related docs |
|
|
| - [Gateway Internals](./gateway-internals.md) |
| - [Prompt Assembly](./prompt-assembly.md) |
| - [Context Compression & Prompt Caching](./context-compression-and-caching.md) |
|
|
