Hermes Agent SQLite is the storage layer behind every Hermes conversation: one SQLite file called state.db, per profile, that keeps your sessions, full message history, model settings and a full-text search index. It lives at ~/.hermes/state.db by default. When you resume a chat or ask Hermes to search past work, it reads from that file. This guide shows what the database holds, the commands that work with it, how to back it up safely, and where SQLite shows up in Hermes memory plugins.
📺 Watch: Hermes Just Fixed AI’s Biggest Memory Problem
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
What Hermes Uses SQLite For
Older Hermes builds wrote each session to its own JSONL file. One SQLite database per profile replaced that.
According to the Hermes Sessions docs, each session record stores:
- The session ID, the platform it came from and the user ID
- A unique session title
- The model name and its configuration
- A snapshot of the system prompt
- The full message history: role, content, tool calls and tool results
- Token counts plus start and end timestamps
- A parent session ID, used when a long chat is compressed and split
Inside the file, the main tables are sessions, messages and messages_fts. That last one is an FTS5 virtual table, which is SQLite's built-in full-text search. Gateway routing data also sits in state.db, in a gateway_routing table. The old ~/.hermes/sessions/sessions.json file still exists, but the docs describe it as a legacy mirror, not the real session list.
If you run several Hermes profiles, each one gets its own database at ~/.hermes/profiles/<name>/state.db. Cloning a profile with --clone does not copy its sessions.
Want a Hermes setup that keeps months of client work searchable? Inside the AI Profit Boardroom we share our own Hermes configs and walk members through them on live calls every week.
Where state.db Lives and How It Writes
Hermes runs SQLite in WAL mode by default. WAL stands for write-ahead log. It lets many readers look at the database while one writer saves new data. You will see two extra files next to the database: state.db-wal and state.db-shm. Those belong to the database. Leave them alone.
The developer guide says the gateway is the only process that writes canonical sessions. You can tune the behaviour under the database section of config.yaml with four keys: journal_mode (wal by default, or delete), synchronous (OFF, NORMAL, FULL or EXTRA, with FULL as the floor on macOS), wal_autocheckpoint and journal_size_limit.
One trap matters for Docker users. Shared folders on Docker Desktop, Podman on macOS and OrbStack use virtiofs or 9p, and the docs warn those can silently corrupt a WAL database. Hermes detects this and creates new databases in delete mode. For an existing database, stop every Hermes process first, then run hermes sessions set-journal-mode delete.
📺 Watch: Hermes Agent OS Can Automate EVERYTHING?! 🤯
Hermes Agent SQLite Commands You Will Use
You never need to open state.db with a SQL tool. Hermes gives you commands for every common job.
Resume a conversation
- hermes -c (or --continue) picks up your most recent chat. Add a name, like hermes -c "my project", to match a title.
- hermes -r <id> (or --resume) opens a session by ID or by title, for example hermes --resume "refactoring auth".
- hermes --resume latest --in ./my-project resumes the newest session for that folder. Use --no-restore-cwd to stay where you are.
The docs put it simply: resuming restores the full conversation history from SQLite. Session IDs look like a date, a time and a short hex code. CLI sessions get six hex characters and gateway sessions get eight.
Manage and tidy sessions
| Command | What it does |
|---|---|
| hermes sessions list | Shows sessions, with --source, --limit and --workspace filters |
| hermes sessions browse | Opens an interactive picker |
| hermes sessions export | Saves a session as jsonl, md, html or trace, with --redact available |
| hermes sessions rename / delete | Renames a session, or removes one by ID |
| hermes sessions prune | Removes old sessions; try --older-than 30 --dry-run first |
| hermes sessions stats | Reports counts and database size |
| hermes sessions optimize | Merges FTS5 segments and runs VACUUM without deleting anything |
| hermes sessions recover | Offline, non-destructive recovery, with an --inspect-only mode |
There are also archive, pin and unpin, repair and several repair-* commands for routing, profiles and prompts.
How Session Search Reads the Database
The session_search tool lets the agent look through old chats without calling a model. It queries the FTS5 index and returns real messages. The Memory docs give the speed as roughly 20ms for a search and about 1ms to scroll around a message.
It works in four shapes: discovery (you pass a query), scroll (a session ID plus a message ID), read (one whole session) and browse (no arguments). Search syntax follows FTS5: plain keywords are joined with AND, quotes match an exact phrase, OR and NOT work, and a trailing star such as deploy* matches prefixes.
One point for teams: search covers the whole profile store, which includes chats from every allowed user on that profile. Keep separate clients on separate profiles.
We track which models handle long-context recall well on Goldie Bench, and the free Agent OS guide shows how we run Hermes next to other agents every day.
📺 Watch: Stop Finding Leads Manually! Use Hermes Agent
Keep the Database Small and Fast
Auto-prune is off by default. That means state.db grows forever unless you act. The docs warn that gateway and cron installs can reach multi-GB files within weeks, and they give an example of a 384 MB database with about 1,000 sessions that slowed FTS5 inserts and the /resume list.
To switch pruning on, set sessions.auto_prune in config.yaml. The defaults keep 90 days, can vacuum after a prune (at most every 30 days), and check no more than once every 24 hours. In a chat you can also type /autoprune on, off or later. Hermes will prompt you when free disk drops under 2 GB, or under 10% on drives smaller than 20 GB.
Running Hermes for lead gen or client SEO? Pair it with a site that ranks. Get your Backlink Gameplan to find out which links your competitors have that you don't, or try Polar Rank for 3 days and let AI agents handle the SEO work.
Back Up and Recover state.db Safely
The safest backup is the built-in one: hermes backup. It writes a zip using SQLite's backup API, so it is safe even while Hermes is running. Add --quick to save only config.yaml, state.db, .env, auth and cron. Options include --label, -o for the output path and --keep.
The docs disagree in one spot. The Sessions page suggests a quick cp of state.db before running repair-routing. The storage recovery page says not to copy state.db on its own. Go with hermes backup. If you must copy the file by hand, stop every Hermes process first.
Three more rules from the recovery docs:
- Never delete state.db-wal or state.db-shm.
- Don't ask the agent to fix its own database. Use hermes sessions recover.
- Maintenance commands such as optimize and prune refuse to run while another process holds the file. A --dry-run is never blocked.
Rolling back to an older Hermes after a newer gateway has written to state.db is not supported. Restore a snapshot, or use hermes update --backup and later hermes import with that zip. For moving everything to a new computer, see our guide to migrating Hermes Agent to a new machine.
SQLite Memory Providers for Hermes
Session storage is not the same as long-term memory. For memory, Hermes supports providers you set with hermes memory setup or the memory.provider key.
Holographic is a catalog plugin, maintained by itpartypattaya, that keeps facts in a local SQLite file. It adds FTS5 search, trust scores and HRR on top. Install it with hermes plugins install holographic, then pick it in hermes memory setup. It stores facts in memory_store.db in your Hermes home and gives the agent a fact_store tool with nine actions plus a fact_feedback tool that nudges trust up or down.
hermes-local-memory by smarzola is a community project in alpha. It is a local-first SQLite memory provider with FTS5 search and no memory server. It is not an official Nous Research plugin. Our Hermes memory management guide covers how to keep memory lean.
Want this set up for your business step by step? Join the AI Profit Boardroom for Hermes training, the Agent OS and four coaching calls a week.
The New Persistence Interface and the SQL Tool Question
The v0.23.3 release notes say the storage layer was split behind a persistence interface with its SQLite backend. Nous lists it as undocumented on purpose for now, with full notes promised for v0.24.0. SQLite is the only backend named.
People also ask whether the agent gets its own SQL database to query. GitHub issue #485 requested a per-agent SQLite database tool. It was closed as completed, but no linked code appears and the docs list no such tool. The cron docs add that state.db is an internal schema that changes between releases, so build your own database for app data and reach it from a script or an MCP server.
Your agents can run the work, and your site can bring the customers. Get your Backlink Gameplan for the links you need, or start a Polar Rank 3-day trial to put AI search on autopilot.
FAQ
Where is the Hermes Agent SQLite database?
At ~/.hermes/state.db for the default profile. Named profiles keep their own file at ~/.hermes/profiles/<name>/state.db.
Can I query state.db directly?
The docs advise against it. The schema changes between releases. Use hermes sessions commands, session_search, or your own separate database.
How do I back up Hermes sessions?
Run hermes backup. It uses SQLite's backup API, so it is safe while Hermes runs, and it skips the WAL side files.
Does Hermes delete old sessions on its own?
No. Auto-prune is off by default. Turn it on with sessions.auto_prune or the /autoprune command.











