Stop every process that touches your Hermes profile's store — the gateway, the dashboard, any open CLIs and your cron jobs — then run hermes sessions set-journal-mode delete (or wal) in your terminal, and Hermes converts the profile's state.db to the SQLite journal mode you asked for, checks the file header to confirm the switch took, and hands the store back ready to open cleanly. The command shipped in Hermes Agent v0.21.4, released by Nous Research on 21 September 2026 under the tag v2026.9.21, and it exists for one specific, painful situation: a session database that is stuck in the wrong journal mode and refuses to come quietly. Before this release, per the pull request that introduced it (#117684, merged 21 September 2026), the only way out was hand-typed PRAGMA statements against a live SQLite file — exactly the kind of surgery most Hermes users never want to perform on the database that holds their sessions.
📺 Watch: NEW Hermes Agent Update is ABSOLUTELY WILD!
🔥 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 sessions set-journal-mode Actually Does
The command is an offline journal converter for Hermes stores. According to the v0.21.4 release notes and pull request #117684, hermes sessions set-journal-mode accepts one of two modes: delete, which converts the store to SQLite's classic rollback journal, and wal, which converts it to write-ahead logging. By default it operates on the active profile's state.db — the database where Hermes keeps session state — and an optional db flag lets you point it at any other Hermes store instead, such as the kanban.db board file or cron stores.
The word offline matters. The tool is deliberately built to run only when nothing else has the database open. Per the pull request, Hermes refuses to convert while any other process holds the database file or its wal and shm sidecar files, and when it refuses it prints each offending process ID and command so you know exactly what to shut down. That is the opposite of the old manual approach, where you could issue a PRAGMA against a file another process was still writing and hope for the best.
Why a Hermes Store Gets Stuck in the Wrong Journal Mode
SQLite databases carry their journal mode with them. Write-ahead logging is the high-concurrency option and the sensible default for a busy agent, but there are environments where WAL is actively dangerous — and, per pull request #117684, Hermes deliberately refuses to downgrade a live WAL database automatically while other processes may hold uncommitted WAL commits. The result, before v0.21.4, was an escape-hatch gap: a store configured into WAL mode could not be walked back to a rollback journal through Hermes itself, even when you had a good reason to want that, such as moving the profile onto a filesystem where WAL misbehaves.
The release notes describe the new command as the sanctioned way out of that trap. You take the database offline, run the conversion, and the tool verifies the result by reading bytes 18 and 19 of the SQLite file header — the values 1 and 1 confirm a rollback journal, 2 and 2 confirm WAL, per the pull request. If the header does not report the mode you asked for, you find out immediately rather than on the next failed session write. If session data itself has been damaged rather than merely mis-moded, that is a different problem — the September releases also shipped separate corruption recovery work, covered in the v0.21.2 notes of 11 September 2026 — but for a healthy file in the wrong mode, this one command is the fix.
How to Run the Command Step by Step
The safe sequence, following the behaviour documented in the pull request, looks like this:
- Stop everything that uses the profile's store: the Hermes gateway, the desktop dashboard, any terminal sessions running the CLI, and any cron jobs that wake the agent on a schedule.
- Run hermes sessions set-journal-mode delete to convert to a rollback journal, or hermes sessions set-journal-mode wal to convert to write-ahead logging.
- If Hermes refuses and lists processes still holding the file, close those processes and run the command again — the refusal is the safety system working, not a bug.
- Watch for the header verification. The command confirms the file now reports the new mode before it exits.
- Update the database journal mode setting in your config if the command tells you it now disagrees — more on that below.
- Restart the gateway and dashboard and open a session to confirm normal operation.
If you have never touched your Hermes install beyond the defaults and nothing is broken, you do not need this command at all — it is a repair tool, not routine maintenance. The Hermes agent setup guide covers the configuration most people should actually be running day to day.
If you want a Hermes agent that runs your business instead of breaking down mid-week, the AI Profit Boardroom is where Julian shares the full battle-tested stack — join in and get the complete Hermes playbook. Prefer to talk it through 1-on-1 first? Book a free SEO strategy session and map out your setup live.
The Safety Checks Built Into the Command
Pull request #117684 documents an unusually defensive design for a one-shot CLI command, and the details are worth knowing before you rely on it:
- Holder detection. The command scans for any foreign process holding the database or its wal and shm sidecars and refuses to proceed while one exists, printing each process ID and command line.
- No racing. During the actual flip it sets the SQLite busy timeout to zero, so a process that grabs the file mid-conversion turns into a clean SQLite refusal instead of a race, per the pull request.
- Header verification. After converting, it re-reads the file header and confirms bytes 18 and 19 report the requested mode before declaring success.
- Network filesystem protection. It refuses to enable WAL on virtiofs or 9p filesystems — the shared-VM mounts where, per the pull request, WAL's shared memory silently corrupts data.
- Config drift warning. It reminds you when the configured journal mode disagrees with the mode you just set, because the next open re-applies whatever the config says.
That last two points are easy to underestimate: the command will actively stop you from putting a store into a mode that is known to corrupt on your filesystem, and it will not let a successful conversion be silently undone by a stale config line.
Fixing Other Hermes Stores with the db Flag
The default target is the profile's state.db, but Hermes keeps more than one SQLite store. Per the pull request, the db flag redirects the conversion at any other store path — the documented example converts the kanban board database, and cron stores are called out as valid targets too. The syntax pattern is the same command with the db flag pointing at the file you want converted. Everything else behaves identically: same holder detection, same header verification, same refusal to work on a file something else has open. If you are not sure which store is misbehaving, the Hermes memory system guide maps out what the agent keeps where, and which files hold what kind of state.
Keep database.journal_mode in Sync with Your Config
The conversion command changes the file; it does not change your configuration. Hermes has a database journal mode key in config.yaml that accepts the same two values, delete and wal, and — per pull request #117684 — whenever the actual file mode differs from the configured mode, the next open re-applies the configured one. Convert a store to a rollback journal while your config still says wal, and Hermes will politely flip it straight back the next time the gateway starts. This is why the command explicitly warns you when the two disagree. Treat the warning as a required step: change the config value to match the mode you converted to, then restart. Operators running Hermes across several machines — the pattern in the Hermes workspace guide — should check the config on every host that opens the same profile.
Windows, Virtual Machines and Network Filesystems
Two environments get special treatment, according to the pull request. On Windows, Hermes cannot scan for foreign processes holding the database, so the command refuses outright unless you add the force flag — which shifts the burden of making sure nothing has the file open entirely onto you. Inside virtual machines using virtiofs or 9p shared folders, the command refuses to enable WAL at all, with no override for good reason: SQLite's write-ahead log depends on shared memory that those filesystems do not implement correctly, and the failure mode is silent corruption rather than an error. If your Hermes install lives on a mount like that, run it in rollback journal mode or move the profile to a native disk — the Hermes desktop installation guide covers sensible install locations per platform.
Where This Fits in the v0.21.4 Update
The journal-mode command is one of nine notable additions in v0.21.4, alongside stream-json CLI output, a skills auto-load setting, bounded session search and a set of gateway hardening changes — the full rundown is in the Hermes Agent v0.21.4 update breakdown. It is the least glamorous feature in the release and arguably the most important one to know exists, because you will only go looking for it on a bad day. It also fits a wider pattern across the September 2026 releases: v0.21.2 shipped extensive database corruption prevention and recovery work, per its 11 September release notes, and v0.21.4 adds the sanctioned escape hatch for mode problems specifically. If you are building serious systems on top of Hermes, pair this knowledge with the Agent OS resource for structuring agent work, and the Goldie Bench write-up for how the different agent brains compare in hands-on tests before you commit a stack.
The honest summary: hermes sessions set-journal-mode is a command you should hope never to need, learn in five minutes, and be very glad exists the day state.db locks itself into the wrong mode. Stop the processes, run the conversion, sync the config, restart — and you are back to work.
If you want working Hermes systems handed to you — the Agent OS zip, prompt libraries, daily tutorials and five live coaching calls a week — check out the AI Profit Boardroom and get inside today. And if you would rather have Julian look at your setup first, book a free SEO strategy session and get a plan built around your business.
