Hermes Agent SQLite covers more than one thing: the built-in state.db session store, the search tool on top of it, two SQLite memory plugins, and the database you might bring yourself.
Picking the wrong one for a job is the most common mistake, so this page lines them up by what each does, what it needs and who it is for.
Sources are the official Sessions docs, the Memory Providers page and the GitHub repos linked below.
If your agent's real job is SEO, start with a Backlink Gameplan so you know which links matter before you automate anything.
The short answer
You already have option 1 the moment you install Hermes, and option 2 comes with it.
Options 3 and 4 add long-term memory and are optional.
Option 5 is for structured business data, and it is the only one that should hold your own records.
The rest of this page explains where each line is drawn.
Option 1: the built-in state.db session store
Every Hermes conversation, from the CLI or from any messaging platform, is written to one SQLite file per profile: ~/.hermes/state.db.
It records session metadata, a copy of the system prompt, which model answered, each message along with tool calls and their results, plus token counts and start and end times.
The developer guide on Session Storage says this replaced an older per-session JSONL approach.
It needs nothing from you and runs in WAL mode for concurrent readers.
Its limit is growth: auto-prune is off by default, so the file keeps every ended session until you set a rule.
What you get from it in practice:
hermes -candhermes --resumereload any past chat with full context.hermes sessions exportturns history into JSONL, Markdown, HTML or trace files.hermes sessions statsreports totals per platform and the file size.- Each named profile keeps a separate file, so agents stay isolated.
The docs have seen the downside too: multi-GB files within weeks on installs that run a gateway and cron together.
Option 2: session_search on top of state.db
session_search is a built-in agent tool that queries the FTS5 index inside state.db.
It returns actual stored messages and makes no model calls.
The agent can discover sessions by keyword, scroll around a matching message, read a whole session or browse recent ones.
Rank in AI Search or It's FREE →
The memory docs compare it with built-in memory: built-in memory holds about 1,300 tokens and sits in every prompt, while session search covers all sessions on demand in roughly 20 ms.
Its limit is scope: it searches the entire profile, including every allowed user's chats.
Queries use FTS5 syntax, so the agent can be precise:
docker deploymentmatches both words.- A quoted phrase matches those words in order.
docker OR kubernetesandpython NOT javawork as written.deploy*matches any word starting with deploy.
A sort option of newest or oldest helps with "where did we leave this" and "how did this start" questions.
By default it searches user and assistant messages only; tool output joins in when you pass a role filter that includes tool.
Option 3: Holographic, a SQLite fact store
Holographic is a memory provider that keeps facts in local SQLite, searches them with FTS5, scores trust and supports HRR, short for Holographic Reduced Representations.
It used to ship inside Hermes and now installs from the plugin catalog, maintained by itpartypattaya.
It adds fact_store with nine actions (add, search, probe, related, reason, contradict, update, remove, list) and fact_feedback, which nudges trust up 0.05 for helpful and down 0.10 for unhelpful.
Facts sit in a separate file, memory_store.db, so they never bloat state.db.
NumPy is optional and only needed for the HRR algebra.
Its settings live under plugins.hermes-memory-store in config.yaml:
| Key | Default | Meaning |
|---|---|---|
db_path | memory_store.db in the Hermes home | Where facts are saved |
auto_extract | false | Pull facts out at session end |
default_trust | 0.5 | Starting trust score for new facts |
Existing setups that named Holographic before the move were migrated automatically, with their facts read from the same file.
🔥 Not sure which memory setup fits your agent? 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 testing these setups. → Join the AI Profit Boardroom
Option 4: hermes-local-memory, a community provider
hermes-local-memory by smarzola is a community project, not part of Hermes.
Join the AI Profit Boardroom →
Its README calls it a local-first SQLite memory provider and marks it alpha.
It stores data in ~/.hermes/memory/local_memory.sqlite and exposes tools such as memory_search (FTS5), memory_context and memory_consolidate.
It also imports from Honcho without changing Honcho.
The author's own advice is to run a trial import and inspect the result before switching a production setup.
Option 5: your own SQLite file
If you want the agent to track leads, stock or rankings in tables, keep that data in a database you own.
The cron docs show the pattern: a small Python script opens your file with sqlite3, counts new rows and only wakes the agent when there is work.
The same docs warn not to query state.db that way, since its schema is internal and changes between releases.
A per-agent database tool that would let the agent create its own tables was proposed in issue #485; it is not a documented built-in tool.
The issue was closed as completed in May 2026, but no pull request is linked to it and no SQL tool appears in the current docs, so plan around a script.
The upside of this route is control: you pick the tables, you back the file up on your schedule, and Hermes upgrades never touch it.
The downside is that you write and maintain the script yourself, or have the agent draft it for you in a normal chat.
Side-by-side comparison
| Option | What it does | What it needs | Best for |
|---|---|---|---|
| state.db | Stores every session and message | Nothing, built in | Resume, audit, history |
| session_search | Full-text search across stored chats | Nothing, built in | Finding past work |
| Holographic | Fact store with trust scores and algebraic recall | Catalog plugin install | Durable facts about people and projects |
| hermes-local-memory | Community memory with cards, facts, consolidation | Community install, alpha | Tinkerers migrating from Honcho |
| Your own SQLite | Your business tables | A script or your own tool | Leads, stock, metrics |
How to set up each option
State.db and session search need no setup; check them with:
hermes sessions stats
hermes sessions list --limit 20
Holographic:
hermes plugins install holographic
hermes memory setup # select "holographic"
hermes memory status
The manual route is hermes config set memory.provider holographic.
For hermes-local-memory, follow the install steps in its own README, since it is not in the official docs.
For your own database, start from the cron script example and keep the file outside the Hermes home.
Housekeeping compared: prune, archive or optimize
| Command | Deletes data | What it changes | Use when |
|---|---|---|---|
hermes sessions prune | Yes, ended sessions only | Removes rows matching filters | You want history gone |
hermes sessions archive | No | Hides from lists and resume | You want a clean list but keep search |
hermes sessions optimize | No | Merges FTS5 segments, runs VACUUM | The file is large after deletes |
sessions.auto_prune: true | Yes, past retention_days | Runs at startup, max once per 24h | You want a standing rule |
Preview any prune with --dry-run, and stop the gateway first if no gateway is meant to handle it, since maintenance commands refuse while another process holds the file.
📈 Automating SEO with Hermes? Get your Backlink Gameplan and my team works out the links behind the pages ranking above you, how many you need and which sites to target, within 48 hours, with a call with an SEO expert. → Get my Backlink Gameplan
Backup methods compared
| Method | Safe while running | Includes | Verdict |
|---|---|---|---|
hermes backup | Yes, uses SQLite's backup API | Config, skills, sessions, data | Default choice |
hermes backup --quick | Yes | Config, state.db, .env, auth, cron | Before every update |
hermes sessions export | Yes | Sessions as JSONL, Markdown or HTML | Readable archives |
| Copying state.db by hand | No | One of three linked files | Avoid |
The recovery guide explains why the last row loses: state.db, state.db-wal and state.db-shm form one image, and the WAL can hold commits not yet in the main file.
The Sessions page still shows a cp backup before routing repairs, which only works safely with every Hermes process stopped.
Common mistakes
- Treating
~/.hermes/sessions/sessions.jsonas the session list; it is a legacy routing mirror. - Deleting the
-walor-shmfile to save space. - Running
optimizeunder a live gateway and then wondering why it refuses. - Using one profile for a public bot and a private assistant, so session search can reach both.
- Expecting a memory provider to replace history; providers are additive and history stays in
state.db. - Writing your own data into
state.db. - Assuming Holographic is core Hermes; it is a catalog plugin now.
Rank in AI Search or It's FREE →
Five questions that pick the option for you
- Do you only need to get back to old chats? The built-in store already does it.
- Should the agent find a past conversation on its own? Session search is already on.
- Should it remember stable facts about people and projects across hundreds of chats? Test a memory provider.
- Do you want every row inspectable and are you fine with alpha software? Look at the community provider.
- Is it business data with columns, like leads or orders? Use your own SQLite file and a script.
If you answered yes only to the first two, stop there; extra layers add maintenance without adding value.
Who each option suits
Solo operators running Hermes from the terminal need only options 1 and 2, plus a weekly hermes backup.
Teams running a gateway on Telegram or Slack should add an auto-prune rule and separate profiles per audience.
Anyone who wants the agent to remember facts across hundreds of chats should test Holographic on a spare profile first.
Builders who like inspecting every row and are happy with alpha software can try hermes-local-memory.
Businesses that want structured records should go straight to option 5.
What the v0.23.3 storage split changes for you
The v0.23.3 notes say storage code was split out behind a new persistence interface, and SQLite is the backend it names.
Per the Session Storage guide, only the gateway writes canonical sessions now; the CLI, TUI, Desktop, cron and workers hand their input to it.
For the comparison above, nothing moves: the file, the commands and the plugins work as before.
The interface is internal plumbing, and the release names only a SQLite backend.
🔥 Pick the right agent stack the first time 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 what they run. → Join the AI Profit Boardroom
Join the AI Profit Boardroom →
FAQ: Hermes Agent SQLite Options Compared
Which Hermes Agent SQLite option do I get by default?
The state.db session store and the session_search tool, both built in.
Is Holographic better than hermes-local-memory?
They solve different jobs: Holographic is a catalog fact store with trust scoring, hermes-local-memory is an alpha community provider with cards and consolidation.
Do memory providers replace state.db?
No. The docs call providers additive; session history still lives in state.db.
Can I store my own tables in state.db?
You should not. The docs say its schema is internal and changes between releases.
What is the safest backup method?
hermes backup, which copies through SQLite backup API and is safe while Hermes runs.
📺 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
Start with the built-in store, add one memory provider on a test profile, and keep business data in your own file.
For guided setups join the AI Profit Boardroom, or get your Backlink Gameplan for the SEO work, and use this page to choose your Hermes Agent SQLite setup.











