Hermes Agent SQLite is the storage layer behind every conversation you have with the agent: one file, ~/.hermes/state.db, holds your sessions, messages and search index.
This guide maps what is in that file, the exact commands that read and maintain it, and the mistakes that cost people their history.
Everything here comes from the official Sessions docs, the Session Storage developer guide and the v0.23.3 release notes.
If you run Hermes for SEO work and want to know which links your pages are missing, a Backlink Gameplan shows you the gap in 48 hours.
Where state.db lives on disk
Each profile owns exactly one SQLite file.
The default profile writes to ~/.hermes/state.db on macOS and Linux.
On Windows the root is %LOCALAPPDATA%/hermes instead.
A named profile such as coder gets its own copy at ~/.hermes/profiles/coder/state.db, per the profiles docs.
The real resolver is get_hermes_home(), which checks a context override, then the HERMES_HOME environment variable, then the platform default.
So if a script spawns Hermes without passing HERMES_HOME, it can land in the default profile's database by mistake.
Next to the main file you will see two sidecars: state.db-wal (the write-ahead log) and state.db-shm (shared memory).
Treat the three files as one unit.
The gateway, Desktop app, dashboard, cron and CLI commands can all share it safely, because every write goes through SQLite's own locking.
What breaks it is a second process rewriting the store, such as a VACUUM, while another one is still writing.
What the database holds, table by table
The Sessions page lists what every row carries:
- Session ID, source platform and user ID
- A unique, human-readable title
- Model name and configuration
- A snapshot of the system prompt
- Full message history: role, content, tool calls and tool results
- Input and output token counts
started_atandended_attimestamps- A parent session ID, used when compression splits a long chat
The schema behind it has three key tables: sessions, messages and messages_fts, the FTS5 virtual table that makes full-text search fast.
Gateway routing sits in a fourth table, gateway_routing, which maps chat keys to active session IDs.
The file ~/.hermes/sessions/sessions.json is only a legacy mirror of that routing index, so a short list there does not mean your CLI sessions are missing.
Rank in AI Search or It's FREE →
WAL mode and the database: block
Hermes opens state.db in WAL mode by default, which gives many readers and a single writer.
The configuration docs expose four keys:
database:
journal_mode: wal # or delete
# synchronous: FULL # OFF, NORMAL, FULL, EXTRA (or 0-3)
# wal_autocheckpoint: 1000
# journal_size_limit: 67108864
On macOS, synchronous is a floor: anything below FULL is refused.
Switching an existing WAL file to delete never happens live.
Stop every process that touches it, then run the converter:
hermes sessions set-journal-mode delete
hermes sessions set-journal-mode wal
The command names each process still holding the file and refuses until they are gone.
Resume any session straight from SQLite
Resuming loads the full transcript from the database, tool calls included.
hermes -c # most recent CLI session
hermes -c "my project" # latest in that title's lineage
hermes --resume 20250305_091523_a1b2c3d4 # by ID or unique prefix
hermes --resume "refactoring auth" # by title
hermes --resume latest --in ./my-project # latest for one workspace
Session IDs follow YYYYMMDD_HHMMSS_<hex>, with a 6-character suffix for CLI and TUI sessions and 8 characters for gateway sessions.
Resuming also changes directory back to the recorded workspace; add --no-restore-cwd to stay put.
Give sessions names with /title so you never hunt for IDs.
🔥 Want Hermes set up so it never loses a conversation? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members running the same agents. → Join the AI Profit Boardroom
Titles and compression lineage
Hermes writes a short title of three to seven words after the first exchange, using a fast auxiliary model in a background thread.
Titles are unique, capped at 100 characters and stripped of control characters.
Rename from the shell with hermes sessions rename <id> <title>; multi-word titles need no quotes.
When /compress runs, or the context fills up, Hermes starts a continuation session and links it through parent_session_id.
A titled chat becomes "my project #2", then "my project #3", and hermes -c "my project" always picks the newest one in that chain.
That chain matters for clean-up too: a conversation split by compression is pruned as one unit, so its older segments stay while any later segment is still inside the window.
Join the AI Profit Boardroom →
In-place compaction keeps old rows with active=0 and writes the retained context as active=1 rows, so the same message can appear twice on purpose.
Do not dedupe those rows by hand.
Repair commands for a store that misbehaves
The sessions CLI has a repair command for each failure the docs have seen:
hermes sessions repair # malformed schema, hidden sessions
hermes sessions repair-routing # dry run; add --apply with the gateway stopped
hermes sessions repair-profiles # rows that landed in another profile's store
hermes sessions recover --source "$HOME/.hermes/state.db" --inspect-only
hermes doctor # lists any process still holding an old WAL
Routing and profile repairs report first and only write with --apply.
If every turn starts answering that another process holds an old copy of the write-ahead log, quit every Hermes process on that profile, run hermes doctor until no holder is listed, then start one process again.
Nothing is lost in that state; the refusal exists to protect the file.
List, browse, stats and export
These read the same store the dashboard reads:
hermes sessions list --limit 50
hermes sessions list --source telegram
hermes sessions list --workspace my-project
hermes sessions browse
hermes sessions stats
hermes sessions export backup.jsonl --redact
stats prints session and message totals per platform plus the database size; the docs sample shows 12.4 MB.
Export supports jsonl, md, qmd, html and trace formats through --format.
How session_search uses FTS5
The agent has a built-in session_search tool that queries messages_fts directly.
It makes no model calls and returns real stored messages, not summaries.
There are four calling shapes, chosen by which arguments you pass: discovery with query, scroll with session_id plus around_message_id, read with session_id alone, and browse with no arguments.
Queries accept standard FTS5 syntax: plain keywords are ANDed, quotes match an exact phrase, OR and NOT work, and deploy* is a prefix match.
The memory docs put a discovery query at around 20 ms and a scroll at around 1 ms.
One operator warning: the tool reads the whole profile store, so on a shared bot anyone allowed to talk to it can ask for anyone else's chats.
Give each audience its own profile if that matters.
Keep state.db small: prune, archive, optimize
Auto-prune is off by default.
Without it the docs report multi-GB files within weeks on gateway plus cron installs, and one case of a 384 MB file with about 1,000 sessions slowing FTS5 inserts and the resume list.
Turn it on in config.yaml:
sessions:
auto_prune: true
retention_days: 90
vacuum_after_prune: true
min_vacuum_interval_days: 30
min_interval_hours: 24
Or answer /autoprune on inside a chat.
For one-off clean-ups:
hermes sessions prune --older-than 30 --dry-run
hermes sessions archive --title "smoke test" --yes
hermes sessions optimize
Prune only deletes ended sessions, archive hides without deleting, and optimize merges FTS5 segments and runs VACUUM without changing any data.
📈 Running Hermes on SEO tasks? Get your Backlink Gameplan and my team maps the links behind the pages outranking you, how many you need and which sites to target, within 48 hours, with a call with an SEO expert. → Get my Backlink Gameplan
Back up without corrupting the store
Use the built-in command:
hermes backup --quick --label "pre-upgrade"
hermes backup -o ~/backups/hermes.zip
It copies through SQLite's own backup() API, so it is safe while Hermes is running, and it leaves the live -wal and -shm sidecars out of the zip on purpose.
The recovery guide is blunt about three things: never delete state.db-wal or state.db-shm, never copy state.db on its own, and never ask the agent to repair a store it is writing to.
One docs conflict to know: the routing repair section still suggests cp ~/.hermes/state.db ~/.hermes/state.db.bak as a backup.
Only do that with every Hermes process stopped; otherwise use hermes backup.
For a damaged file, hermes sessions recover copies rows into a separate clean database without touching the original.
Docker and network mounts
In the container image the file sits at /opt/data/state.db.
WAL needs coherent shared memory, and bind mounts that cross a VM boundary (virtiofs on Docker Desktop for macOS, Podman on macOS, OrbStack, 9p on Windows) do not give it.
Rank in AI Search or It's FREE →
Hermes detects those mounts and starts fresh databases in delete mode.
An existing WAL file there needs the offline conversion plus database.journal_mode: delete in config so it sticks.
SQLite memory providers: Holographic and a community one
Session history is not the same as long-term memory.
The Memory Providers page lists Holographic as a local SQLite fact store with FTS5 search, trust scoring and HRR for compositional queries.
It now lives in the plugin catalog, maintained by itpartypattaya:
hermes plugins install holographic
hermes memory setup # pick "holographic"
hermes memory status
Its facts go to memory_store.db in your Hermes home unless you change db_path under plugins.hermes-memory-store.
A separate community project, hermes-local-memory by smarzola, is a SQLite memory provider marked alpha by its author; trial-import before trusting it with a live profile.
What the v0.23.3 persistence interface changed
The v0.23.3 notes list "the storage layer split behind a persistence interface with its SQLite backend".
The developer guide names the parts: contracts in persistence/, the entry point persistence_assembly.py, and the SQLite code in persistence/sqlite/.
Nothing changes in your file or commands.
The point is that the gateway is now the only writer of canonical sessions; other surfaces send input to it instead of opening the database for transcript writes.
Is there a per-agent SQLite database tool?
Not as a documented built-in.
Issue #485 proposed a private SQLite database per agent, modelled on Gobii, with tables the agent could create and query across sessions.
The proposal described a restore, operate and persist cycle, zstd compression of the file between sessions, a wipe for databases over 100 MB, and guardrails that block ATTACH, load_extension and readfile.
It was closed in May 2026 as completed, yet no linked pull request appears on it and the current docs list no SQL tool.
If you need structured data today, keep your own SQLite file and reach it from a script; the cron docs show a sqlite3 gate that wakes the agent only when new rows arrive.
Never point that kind of script at state.db itself: the docs call its schema internal and say it changes between releases.
Operator gotchas checklist
- Stop the gateway, Desktop app, dashboard and cron before
optimize,optimize-storageorset-journal-mode. --dry-runpreviews are never blocked, so preview first.- Rolling back to a release older than the gateway runtime is refused once the new gateway has written
state.db; restore a snapshot instead. - A cloned profile starts with an empty
state.db; sessions never travel with--clone. - If CLI chats vanish from the list, run
hermes sessions repairand watch for the store-unavailable warning at startup.
🔥 Get the Agent OS that runs Hermes for you Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members comparing setups. → Join the AI Profit Boardroom
Join the AI Profit Boardroom →
FAQ: Hermes Agent SQLite
Where is the Hermes Agent SQLite file?
At ~/.hermes/state.db for the default profile, and inside each named profile folder for the others.
Can I delete state.db-wal to save space?
No. The recovery docs say the WAL holds committed conversations not yet in the main file, so deleting it loses data.
Does hermes sessions optimize delete anything?
No. It merges FTS5 index segments and runs VACUUM without changing session data.
Is auto-prune on by default?
No. Turn it on with sessions.auto_prune: true or /autoprune on.
Can the agent run SQL on its own database?
There is no documented built-in SQL tool; use your own SQLite file from a script.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Run hermes sessions stats today, then hermes backup --quick before your next update.
Want the full agent stack built step by step? Join the AI Profit Boardroom, or get your Backlink Gameplan for the SEO side, and keep this page as your Hermes Agent SQLite reference.











