File size: 1,702 Bytes
9aa5185 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | ---
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)
|