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.

Get the Backlink Gameplan →

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 -c and hermes --resume reload any past chat with full context.
  • hermes sessions export turns history into JSONL, Markdown, HTML or trace files.
  • hermes sessions stats reports 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 deployment matches both words.
  • A quoted phrase matches those words in order.
  • docker OR kubernetes and python NOT java work 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:

KeyDefaultMeaning
db_pathmemory_store.db in the Hermes homeWhere facts are saved
auto_extractfalsePull facts out at session end
default_trust0.5Starting 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

OptionWhat it doesWhat it needsBest for
state.dbStores every session and messageNothing, built inResume, audit, history
session_searchFull-text search across stored chatsNothing, built inFinding past work
HolographicFact store with trust scores and algebraic recallCatalog plugin installDurable facts about people and projects
hermes-local-memoryCommunity memory with cards, facts, consolidationCommunity install, alphaTinkerers migrating from Honcho
Your own SQLiteYour business tablesA script or your own toolLeads, 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:

Get the Backlink Gameplan →

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

CommandDeletes dataWhat it changesUse when
hermes sessions pruneYes, ended sessions onlyRemoves rows matching filtersYou want history gone
hermes sessions archiveNoHides from lists and resumeYou want a clean list but keep search
hermes sessions optimizeNoMerges FTS5 segments, runs VACUUMThe file is large after deletes
sessions.auto_prune: trueYes, past retention_daysRuns at startup, max once per 24hYou 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

MethodSafe while runningIncludesVerdict
hermes backupYes, uses SQLite's backup APIConfig, skills, sessions, dataDefault choice
hermes backup --quickYesConfig, state.db, .env, auth, cronBefore every update
hermes sessions exportYesSessions as JSONL, Markdown or HTMLReadable archives
Copying state.db by handNoOne of three linked filesAvoid

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.json as the session list; it is a legacy routing mirror.
  • Deleting the -wal or -shm file to save space.
  • Running optimize under 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

  1. Do you only need to get back to old chats? The built-in store already does it.
  2. Should the agent find a past conversation on its own? Session search is already on.
  3. Should it remember stable facts about people and projects across hundreds of chats? Test a memory provider.
  4. Do you want every row inspectable and are you fine with alpha software? Look at the community provider.
  5. 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.