agentos.guide › blog
Hermes Agent SQLite is the session store that sits under every chat your agent runs: a single file per profile, ~/.hermes/state.db, holding messages, titles and a full-text index.
This guide explains how it behaves, then gives you three Agent OS prompts that check it, back it up and search it without risking live data.
Source material: the Sessions guide, the session storage recovery page and the v0.23.3 release.
Using Hermes for search work? A Backlink Gameplan shows which links your pages need, within 48 hours.
Every conversation from the CLI, TUI, Desktop or a messaging platform is saved as a session.
The file keeps the session ID and source, a unique title, the model and its configuration, a system prompt snapshot, every message with tool calls and results, token counts, start and end times, and a parent ID when compression splits a chat.
Three tables do the work: sessions, messages and messages_fts, the FTS5 index used for search.
It runs in WAL mode, so two companion files, state.db-wal and state.db-shm, always travel with it.
Each named profile has its own copy under ~/.hermes/profiles/.
That isolation is deliberate: a support bot, a research agent and a personal assistant never read each other's history, and cloning a profile copies its settings and curated memory but starts the history empty.
Several processes can share one file safely, because SQLite handles the locking for the gateway, Desktop, dashboard, cron and CLI together.
The one thing that is not safe is rewriting the file, for instance with a VACUUM, while another process is still writing to it.
hermes -c # carry on with the last chat
hermes --resume "launch checklist" # resume by title
hermes sessions list --limit 30
hermes sessions browse # interactive picker
hermes sessions stats # totals and file size
Name chats as you go with /title, so resuming by name is easy.
Hermes also writes a three-to-seven-word title for you after the first exchange, and titles must be unique, so two jobs never collide.
Resuming restores the full transcript, tool calls included, and moves you back into the folder the chat was working in; --no-restore-cwd keeps you where you are.
When a long chat is compressed, Hermes continues it as "title #2", "title #3" and so on, and resuming by the base title always opens the newest.
Rank in AI Search or It's FREE →
The agent's session_search tool reads the FTS5 index directly, with no model calls, and returns stored messages rather than summaries.
The memory docs quote roughly 20 ms per search and about 1 ms to scroll within a result.
Phrase searches in quotes, OR, NOT and prefix matches such as invoice* all work.
Remember the scope: it can read every chat in the profile, from every user the bot allows.
🔥 Run Hermes inside your own Agent OS
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.
Auto-prune is switched off by default, and the docs have seen gateway plus cron installs reach several gigabytes within weeks.
Choose your rule:
/autoprune on deletes ended sessions idle beyond retention_days (90 by default).hermes sessions archive hides matching chats but keeps them searchable.hermes sessions optimize merges index segments and runs VACUUM without changing any session.The maintenance commands refuse while another Hermes process holds the file, and --dry-run previews are always allowed.
For a standing rule in config.yaml, these are the keys and their defaults:
sessions:
auto_prune: true # default is false
retention_days: 90
vacuum_after_prune: true
min_vacuum_interval_days: 30
min_interval_hours: 24
Pruning only ever removes ended sessions; anything still open is left alone.
If your disk runs low and you have not set a rule, Hermes asks you once and answers /autoprune later with a reminder in a week.
Use hermes backup; it copies through SQLite's backup API and is safe whilst Hermes runs.
--quick limits the zip to config, state.db, .env, auth and cron jobs.
The recovery page lists the three things never to do: delete the -wal or -shm file, copy state.db by itself, or ask the agent to repair the store it is writing to.
That last rule shapes the prompts below: they read, report and back up, and they never rewrite the database.
Inside the container image the file lives at /opt/data/state.db.
Join the AI Profit Boardroom →
WAL mode relies on shared memory, and bind mounts that cross a virtual machine boundary, such as Docker Desktop or Podman on a Mac, or OrbStack, cannot guarantee it.
Hermes spots those mounts and creates new databases in rollback journal mode instead; the configuration page documents the database.journal_mode key that makes the choice stick.
An existing WAL file needs every process stopped and then hermes sessions set-journal-mode delete.
Long-term memory is separate from session history.
The Memory Providers page describes Holographic as a local SQLite fact store with FTS5, trust scoring and HRR recall; it installs from the plugin catalog and is maintained by itpartypattaya.
A community alternative, hermes-local-memory, is also SQLite-based and marked alpha by its author.
hermes plugins install holographic
hermes memory setup
hermes memory status
The release notes mention that the storage layer now sits behind a persistence interface, with SQLite as its backend.
The developer Session Storage guide adds that the gateway is the only writer of canonical sessions.
Your file, paths and commands are unchanged.
There is still no documented built-in tool for an agent to create its own SQL tables; issue #485 proposed one, and the docs list none.
Paste this into a Hermes chat in your Agent OS:
Run these read-only commands and report back in a short table:
1. hermes sessions stats
2. hermes sessions list --limit 10
3. hermes sessions prune --older-than 90 --dry-run
4. df -h ~/.hermes
Tell me: total sessions, database size, how many sessions a 90-day prune
would remove, and free disk space. Do NOT run prune, optimize, archive or
any repair command. If disk free space is under 10%, say so in bold.
Why it works: every command in it is either read-only or a dry run, so it is safe on a busy gateway.
Schedule it as a weekly cron job in your Agent OS and you will see growth long before it slows search or the resume list.
Make a quick Hermes backup with:
hermes backup --quick --label "pre-update-$(date +%Y%m%d)"
Then show me the backup path the command printed and confirm the exit
status was 0. If it reports
"Backup incomplete", stop and show me the message. Never copy state.db
by hand and never touch the -wal or -shm files.
Run this before every hermes update.
Older releases refuse to run on a database a newer gateway has already written, so a fresh snapshot is your only clean way back.
Keep the full hermes backup for a weekly off-machine copy, since the docs say quick snapshots skip a state.db larger than 1 GiB.
📈 Want your agent's SEO work to rank?
Get your Backlink Gameplan and my team maps the links behind the pages above you, how many you need and which sites to target, within 48 hours, with a call with an SEO expert.
Use session_search to find our past conversation about: <TOPIC>.
Search with sort="newest" first. Show the top 3 sessions with title,
date, source and a two-line summary of what was decided. Then give me
the exact command to resume the best match, e.g. hermes --resume "<title>".
Read only: do not delete, archive or rename anything.
Swap the topic for something real, such as a client name or a campaign.
Asking for the newest match first suits questions like where you left a job; switch to sort="oldest" when you want to know how something started.
If every turn starts refusing with a message about an old copy of the write-ahead log, prompts cannot help, because the agent's own chat lives in that same file.
Stop the gateway, Desktop app, dashboard and cron on that profile, and keep re-running hermes doctor while it still names a holding PID.
Once the list is clear, bring a single process back up and resend your message; your history is intact.
🔥 Get more maintenance routines like these
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 sharing their prompts.
Rank in AI Search or It's FREE →
Yes. They only read, report or call hermes backup, which is safe whilst Hermes runs.
Optimize rewrites the file and refuses while another process holds it, and the agent runs inside one of those processes.
In memory_store.db inside your Hermes home, unless you set db_path.
Yes. Every Hermes profile owns one state.db.
Run Prompt 1 today and Prompt 2 before every update.
For more agent routines join the AI Profit Boardroom, or get your Backlink Gameplan for the SEO side, and bookmark this page as your Hermes Agent SQLite playbook.
About Julian
I'm Julian Goldie, an AI entrepreneur, SEO expert and the founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
My YouTube channel has 400,000+ subscribers, and I run Goldie Agency, a seven-figure SEO agency.
→ The Best Hermes Agent Memory, And How It Becomes The Memory Layer Of Your Agent OS
→ Hermes Agent Backup: The Five-Minute Quick-Start, The Restore Steps And Where It Fits In An Agent OS
→ Hermes Agent Prompt Caching + 3 Agent OS Check Prompts
The installable system behind every guide on this site — dashboard, agents, memory and pipelines — updated as new tools land, with 3,400+ members and four coaching calls a week.
Join the AI Profit Boardroom →📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉