Hermes Agent SQLite means one file: state.db. Every Hermes profile keeps its chats, tool results, model settings and a full-text search index inside that single SQLite database, so --resume and session search work instantly. In the video below I show Hermes memory in action. Below I’ll break down what sits inside the database, the exact commands to work with it, the backup mistake the docs warn about, and which memory plugins also run on SQLite.
Key takeaways
- Hermes stores sessions in ~/.hermes/state.db, one SQLite file per profile.
- It runs in WAL mode: never delete the
-walor-shmfiles next to it. - Back it up with
hermes backup, which is safe while Hermes is running. - Auto-prune is off by default, so the file keeps growing until you switch it on.
- Want Hermes set up properly in your business? Join the AI Profit Boardroom.
What is inside the Hermes state.db file?
Hermes used to save each session as a separate JSONL file. It now keeps everything in one SQLite database per profile. The Sessions docs list what each session row carries:
- Session ID, source platform and user ID
- A session title, which must be unique
- The model name and its config
- A copy of the system prompt at the time
- Every message: role, content, tool calls and tool results
- Token counts, plus started_at and ended_at times
- A parent session ID when a long chat gets compressed into a new one
The tables that matter
Per the session storage developer guide, the core tables are sessions, messages and messages_fts, an FTS5 full-text index. Gateway routing lives in a gateway_routing table. The file at ~/.hermes/sessions/sessions.json is only a legacy mirror, not the real session list.
Where the database lives on each setup
| Setup | Path to state.db |
|---|---|
| Default profile | ~/.hermes/state.db |
| Named profile | ~/.hermes/profiles/<name>/state.db |
| Windows | Under %LOCALAPPDATA%/hermes |
| Docker | /opt/data/state.db |
A profile made with --clone starts with an empty session history, because cloning skips state.db. The developer guide names the gateway as the only writer of canonical sessions.
WAL mode and the Docker warning
SQLite runs in write-ahead-log mode here, so readers never block while the gateway writes. The database: block in config.yaml controls journal_mode, synchronous, wal_autocheckpoint and journal_size_limit. On Docker Desktop, OrbStack or Podman for macOS, shared volumes can quietly damage WAL files. Hermes spots this and opens new databases in delete mode. To switch an existing one, shut down all Hermes processes and run hermes sessions set-journal-mode delete.
Want Hermes keeping every client conversation searchable? Inside the AI Profit Boardroom you get the Agent OS — Hermes, OpenClaw, OpenCode, Claude and Codex in one place — plus step-by-step Hermes training and four live coaching calls a week.
Want more customers from Google too? Get your Backlink Gameplan: we reverse-engineer why your competitors outrank you and send the exact backlinks to close the gap, within 48 hours, or try Polar Rank free for 3 days.
Join the AI Profit Boardroom →Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
Hermes Agent SQLite commands: resume, list and search
Everything goes through the CLI. You never have to write SQL against the file.
hermes -ccontinues your last chat;hermes -c "my project"matches by title.hermes --resume <id>orhermes -r "refactoring auth"reopens a specific one.hermes --resume latest --in ./my-projectgrabs the newest session for a folder.hermes sessions list --limit 20shows recent sessions;browsegives a picker.hermes sessions export <id>writes jsonl, md, html or trace files, with a--redactoption.hermes sessions statsreports totals, including the database size.
How session_search finds old work
The agent’s session_search tool hits the FTS5 index directly, with no model call. The memory docs time a search at roughly 20ms. You can pass quoted phrases, OR, NOT and prefix terms like deploy*. It searches the whole profile, so give each client their own profile if chats must stay apart.
Stop state.db from getting huge
Pruning does not run unless you enable it. The docs mention gateway and cron installs hitting multi-GB databases within weeks, and a 384 MB file holding around 1,000 sessions that made FTS5 inserts and the /resume list slow.
- Turn on
sessions.auto_prunein config.yaml. Retention defaults to 90 days. - Or type
/autoprune oninside a chat. - Preview a manual cleanup with
hermes sessions prune --older-than 30 --dry-run. - Run
hermes sessions optimizeto merge FTS5 segments and VACUUM. It deletes nothing.
Hermes also warns you when disk space drops under 2 GB free.
How to back up Hermes Agent SQLite safely
Use hermes backup. It builds a zip with SQLite’s own backup API, so it works while the gateway is live. --quick grabs just config.yaml, state.db, .env, auth and cron.
Two Hermes pages clash here. The Sessions page shows a plain cp of state.db before a repair. The storage recovery page says never copy state.db on its own. Follow the backup command. A manual copy is only safe with every Hermes process stopped.
- Never delete
state.db-walorstate.db-shm. - Don’t ask Hermes to repair its own database; run
hermes sessions recover --inspect-onlyfirst. - Rolling back to an older version after a newer gateway touched the file is unsupported. Restore with
hermes importand your backup zip instead.
Want Hermes set up with you, step by step? Join the AI Profit Boardroom → for the Agent OS and Hermes training.
SQLite memory plugins and the per-agent SQL tool
Long-term memory is separate from session storage. The Memory Providers docs list catalog options you enable with hermes memory setup.
- Holographic: a catalog plugin maintained by itpartypattaya. It is a local SQLite fact store with FTS5, trust scoring and HRR. Install with
hermes plugins install holographic. - hermes-local-memory: a community SQLite memory provider by smarzola, still alpha, not official.
The v0.23.3 release also moved storage behind a new persistence interface with its SQLite backend; Nous says full notes arrive with v0.24.0. As for a built-in SQL tool, issue #485 asked for a per-agent SQLite database, but the docs list no such tool. Keep your own app data in your own database and reach it through a script or MCP server.
Bottom line: let Hermes manage state.db, switch on auto-prune, and run hermes backup on a schedule. That is all Hermes Agent SQLite asks of you.
About Julian Goldie
I’m Julian Goldie — founder of Goldie Agency and the AI Profit Boardroom. I test new AI agents almost every day for 428K+ YouTube subscribers and run Hermes, OpenClaw, OpenCode, Claude and Codex side by side in my own Agent OS. Join the AI Profit Boardroom for the daily builds, or Get your Backlink Gameplan if you want your own site to rank, or try Polar Rank free for 3 days.
FAQ: hermes agent sqlite
Where does Hermes Agent store its SQLite database?
In ~/.hermes/state.db for the default profile, or ~/.hermes/profiles/
What does Hermes use SQLite for?
Sessions, full message history, model config, system prompt snapshots, token counts and an FTS5 search index used by session_search.
Is it safe to copy state.db?
Use hermes backup instead. A plain copy is only safe with every Hermes process stopped, and the -wal and -shm files must never be deleted.
Does Hermes prune old sessions automatically?
Not by default. Enable sessions.auto_prune in config.yaml or type /autoprune on.
Can the Hermes agent run SQL queries on its own database?
There is no documented built-in SQL tool, and the docs say state.db’s schema changes between releases. Use a script or an MCP server with your own database.
Which Hermes memory plugin uses SQLite?
Holographic, a catalog plugin with a local SQLite fact store, and the community hermes-local-memory project.
Ready to put Hermes to work in your business? Join the AI Profit Boardroom for the Agent OS, setup training and daily updates.
Want your site to rank too? Get your Backlink Gameplan and see the exact links that close the gap on your competitors, or try Polar Rank free for 3 days and let AI agents do your SEO on autopilot.
Starting from zero? Get the free AI course and community.
Join the AI Profit Boardroom →Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →Get the FREE AI Course + Community →
Related reading
- Migrate Hermes Agent to a New Machine
- Hermes Memory Management
- Hermes Agent Prompt Caching
- Best Hermes Agent Plugins
Last updated November 2026. This page is a living guide to hermes agent sqlite — the facts here move fast and it is updated as they do.
