Field notes · AI agents, Hermes & Claude Code By Julian Goldie

Hermes Agent SQLite: What state.db Stores, the Commands That Read It and How to Back It Up Without Breaking It

Operator notes on state.db: tables, WAL, resume and search commands, clean-up, safe backups, SQLite memory providers and the v0.23.3 persistence split.

Get The AI Profit Stack Join AIPB →
  • 01 1,000+ done-for-you AI agent workflows
  • 02 5 live coaching calls / week with me
  • 03 7-day refund, cancel anytime
  • 04 3,400+ AI operators inside

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.

Get the Backlink Gameplan →

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_at and ended_at timestamps
  • 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.

Get the Backlink Gameplan →

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-storage or set-journal-mode.
  • --dry-run previews 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 repair and 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.

§ Member reviews

What members say about the AI Profit Boardroom

Read the member reviews on Skool →
Ahmad Bukhari: Julian doesn't gatekeep. That's why I'd recommend this group. He's extremely active here, sharing what's working right now and jumping in to help anyone who's stuck. If he can give it away, he does. He keeps the vibe positive and pushes everyone to help each other. His challenges reward members for getting people unstuck, so the whole room shares knowledge, not just him. Want a generous, positive place to learn AI and actually use it? This is it. Thanks Julian!
Ahmad Bukhari
Julian doesn't gatekeep. That's why I'd recommend this group. He's extremely active here, sharing what's working right now and jumping in to help anyone who's stuck. If he can give it away, he does. He keeps the vibe positive and pushes everyone to help each other. His challenges reward members for getting people unstuck, so the whole room shares knowledge, not just him. Want a generous, positive place to learn AI and actually use it? This is it. Thanks Julian!

Still a paying member after 1 month

Jay Parsons: There are so many helpful members in this amazing community ready to help out with suggestions and solutions whenever someone asks a question. I am amazed at the progress I have made in learning AI. I came here to learn how to use AI better and apply what I learned to my business. I am learning so much more than I even dreamed of. I have built an Agentic OS and use it every day, and I have no background in coding. There are an incredible amount of useful tutorials on everything AI.
Jay Parsons
There are so many helpful members in this amazing community ready to help out with suggestions and solutions whenever someone asks a question. I am amazed at the progress I have made in learning AI. I came here to learn how to use AI better and apply what I learned to my business. I am learning so much more than I even dreamed of. I have built an Agentic OS and use it every day, and I have no background in coding. There are an incredible amount of useful tutorials on everything AI.

Still a paying member after 11 months

Brian O'Connor: At 47, with 30 years in sales and finance, embracing AI was exciting but overwhelming. While building a business to help others adopt AI, I found myself chasing tools and fearing I was falling behind. Julian and the AI Profit Boardroom helped me refocus through practical, personalized advice and a supportive community. I now feel more confident adapting to change while staying focused on my goals. Thank you, Julian, for bringing this community together!
Brian O'Connor
At 47, with 30 years in sales and finance, embracing AI was exciting but overwhelming. While building a business to help others adopt AI, I found myself chasing tools and fearing I was falling behind. Julian and the AI Profit Boardroom helped me refocus through practical, personalized advice and a supportive community. I now feel more confident adapting to change while staying focused on my goals. Thank you, Julian, for bringing this community together!

Still a paying member after 2 months

Neil Martin: This is a truly amazing community, thanks in no small part to Julian's prodigious output and tireless efforts to provide value to his subscribers. Nothing is too much trouble for him. If you ask a question it gets answered in short order usually with a custom video. I have been in quite a few groups and this level of service is unparalleled. If you are serious about getting an AI education, you need to be in this group!
Neil Martin
This is a truly amazing community, thanks in no small part to Julian's prodigious output and tireless efforts to provide value to his subscribers. Nothing is too much trouble for him. If you ask a question it gets answered in short order usually with a custom video. I have been in quite a few groups and this level of service is unparalleled. If you are serious about getting an AI education, you need to be in this group!

Still a paying member after 7 months

Crystal Hill: AIPB has inspired me to go beyond learning AI as individual tools, skills, and prompts, and start thinking in terms of larger systems. What I really appreciate is how responsive Julian is and how quickly the material evolves with the technology. You’re being exposed to the right tools and ideas as they emerge. AIPB has given me the confidence to learn, experiment, build, and think much bigger about what’s really possible with AI.
Crystal Hill
AIPB has inspired me to go beyond learning AI as individual tools, skills, and prompts, and start thinking in terms of larger systems. What I really appreciate is how responsive Julian is and how quickly the material evolves with the technology. You’re being exposed to the right tools and ideas as they emerge. AIPB has given me the confidence to learn, experiment, build, and think much bigger about what’s really possible with AI.

Still a paying member after 5 months

Maurice Morrison: AI Profit Board Room has been a game-changer. The insights are practical, timely, and focused on turning AI into real business results—not just theory or hype. The community is supportive, the guidance is clear, and I leave every session with ideas I can actually apply. If you’re serious about using AI to grow smarter and move faster, this is absolutely worth joining.
Maurice Morrison
AI Profit Board Room has been a game-changer. The insights are practical, timely, and focused on turning AI into real business results—not just theory or hype. The community is supportive, the guidance is clear, and I leave every session with ideas I can actually apply. If you’re serious about using AI to grow smarter and move faster, this is absolutely worth joining.

Still a paying member after 2 months

Jeremy Murdock: I have truly enjoyed my experience here. The group of folks on the calls is quite diverse and I find it comforting to know that I am not the only one going through the changes that are happening at a faster and faster pace. I have chosen to embrace the change and go full force into integrating AI and what I have learned form the group and Julian. I am also impressed and appreciative that he actually takes the time to help with challenges I have along the way and get involved personally!
Jeremy Murdock
I have truly enjoyed my experience here. The group of folks on the calls is quite diverse and I find it comforting to know that I am not the only one going through the changes that are happening at a faster and faster pace. I have chosen to embrace the change and go full force into integrating AI and what I have learned form the group and Julian. I am also impressed and appreciative that he actually takes the time to help with challenges I have along the way and get involved personally!

Still a paying member after 10 months

Michael Lovitch: I have been a part of a million ai groups in Skool for years now. They are all okay and have helped, but usually they get out of date and don't offer real service to help you through especially at the beginning. This group is different, Julian actually answers questions which is crazy! And although ai marketing moves at the speed of light, they stay current and actually help you keep up… Highly recommended!
Michael Lovitch
I have been a part of a million ai groups in Skool for years now. They are all okay and have helped, but usually they get out of date and don't offer real service to help you through especially at the beginning. This group is different, Julian actually answers questions which is crazy! And although ai marketing moves at the speed of light, they stay current and actually help you keep up… Highly recommended!

Still a paying member after 3 months

Hoebing Lo: I don't know of any other community that is as active and sharing. Julian is a star and he answers so many questions in lightning speed. If you want a great place to start with AI here it is. No question too simple. No workflow too complicated. The community is about action and results not education so if you are looking to win at AI then come for the ride of a lifetime!
Hoebing Lo
I don't know of any other community that is as active and sharing. Julian is a star and he answers so many questions in lightning speed. If you want a great place to start with AI here it is. No question too simple. No workflow too complicated. The community is about action and results not education so if you are looking to win at AI then come for the ride of a lifetime!

Still a paying member after 5 months

Darren Wagstaff: Very responsive... great personal support (not an ai chat bot). Very clear straight forward trainings in easy to understand actionable language. I'm in numerous Skool groups but this one has the most human and real community by far. No question gets ignored. You never fell like just another number. It's great to see so many members getting great results with Ai.
Darren Wagstaff
Very responsive... great personal support (not an ai chat bot). Very clear straight forward trainings in easy to understand actionable language. I'm in numerous Skool groups but this one has the most human and real community by far. No question gets ignored. You never fell like just another number. It's great to see so many members getting great results with Ai.

Still a paying member after 2 months

Rod Martin: Julian is brilliant, and more prolific than I can keep up with (which is a great thing). His AgentOS is remarkable, and he is THE go-to guy for what you can really do (and not do) with the ever-increasing deluge of new AI upgrades and tools. HIGHLY recommend.
Rod Martin
Julian is brilliant, and more prolific than I can keep up with (which is a great thing). His AgentOS is remarkable, and he is THE go-to guy for what you can really do (and not do) with the ever-increasing deluge of new AI upgrades and tools. HIGHLY recommend.

Still a paying member after 5 months

Yosuke Sato: The best Skool course you get for AI! I have attended a few Skool courses before, but AI Profit Boardroom is the most active community and has great support from the management team, including Julian! You can get the most up-to-date information and practical implementations in this community. I highly recommend this!
Yosuke Sato
The best Skool course you get for AI! I have attended a few Skool courses before, but AI Profit Boardroom is the most active community and has great support from the management team, including Julian! You can get the most up-to-date information and practical implementations in this community. I highly recommend this!

Still a paying member after 19 months

⚑ Next step

Ready to run AI agents that actually do the work?

Join 3,400+ operators inside the AI Profit Boardroom. Get 1,000+ plug-and-play AI agent workflows, 5 coaching calls a week, and a community that holds you accountable.

Join The AI Agent Community →

7-day no-questions refund · Cancel anytime

Found this useful? Get more of this site in your Google.

One tap adds us as a preferred source — Google then shows you our posts more often in Search, Top Stories, and AI Overviews.

← Back to all posts