Originally published on Remote OpenClaw.
Hermes Agent persists memory across restarts through three built-in mechanisms — bounded markdown files (MEMORY.md and USER.md), a SQLite session database with FTS5 full-text search, and 8 pluggable external memory providers introduced in v0.7.0. Every method writes to disk or cloud, so nothing is lost when the process stops. The right configuration depends on whether you need simple recall, semantic search, or deep user modeling.
Key Takeaways
- MEMORY.md (~2,200 chars) and USER.md (~1,375 chars) persist as files in ~/.hermes and survive restarts, updates, and reinstalls.
- All sessions are stored in SQLite (~/.hermes/state.db) with FTS5 indexing — the agent can search its own conversation history on demand.
- 8 external providers (Honcho, Mem0, Holographic, OpenViking, Hindsight, RetainDB, ByteRover, Supermemory) add semantic or graph-based long-term memory.
- Holographic is the only provider that works fully offline with zero dependencies — pure SQLite, no pip installs.
- Only one external provider can be active at a time, but built-in MEMORY.md and session storage always run alongside it.
In this guide
- Built-In File Memory (MEMORY.md and USER.md)
- SQLite Session Storage and FTS5 Search
- All 8 External Memory Providers Compared
- Honcho Setup: AI-Native User Modeling
- Holographic: Offline-First Vector Memory
- Which Method to Use — Decision Guide
- Limitations and Tradeoffs
- FAQ
Built-In File Memory (MEMORY.md and USER.md)
Hermes Agent ships with two persistent markdown files that the agent curates automatically across every session. These files live in the ~/.hermes directory and are injected into the system prompt at session start — the agent knows everything in them before the first message.
MEMORY.md holds agent-curated notes: environment facts, project conventions, discovered workarounds, and lessons learned. The file is bounded at approximately 2,200 characters (~800 tokens). The agent decides what to write here based on conversation patterns, not explicit user commands. When the file approaches its limit, the agent summarizes and compresses older entries to make room for new information.
USER.md stores a profile of who you are: your role, technical stack, communication preferences, and goals. This file is bounded at approximately 1,375 characters (~500 tokens) and updates as the agent learns more about you.
Both files survive restarts, updates, and reinstalls as long as the ~/.hermes directory is preserved. For Docker deployments, mount ~/.hermes as a volume to ensure persistence across container rebuilds. For a general overview of how this memory system works, see Hermes Agent Memory System Explained.
SQLite Session Storage and FTS5 Search
Every CLI and messaging session is automatically stored in a SQLite database at ~/.hermes/state.db, using WAL mode for concurrent read access. This database stores full message history, tool calls, results, token counts, and session metadata.
The agent has a built-in session_search tool that performs full-text search across all past conversations using SQLite's FTS5 engine. When the agent needs to recall something from a previous session, it searches the FTS5 index, ranks results by relevance, loads the top matching sessions, truncates them to approximately 100K characters centered on the matches, and sends them to a fast summarization model for focused summaries.
This session search is always available regardless of which external memory provider is active. It provides episodic recall — the ability to remember specific conversations and outcomes from days or weeks ago — without any additional configuration.
The database schema includes four tables: sessions (metadata and billing), messages (full message history), messages_fts (FTS5 virtual table), and schema_version (migration tracking). Back up ~/.hermes/state.db to preserve your entire conversation history.
All 8 External Memory Providers Compared
Hermes Agent v0.7.0 introduced pluggable memory backends that extend persistence beyond the built-in files and session database. As of April 2026, 8 providers are available. Only one can be active at a time.
Provider
Storage Type
Self-Hosted
Free Tier
Best For
Honcho
Cloud user modeling
No
Yes
Deep user understanding over time
Holographic
Local SQLite + HRR vectors
Yes
N/A (free)
Air-gapped / offline deployments
Mem0
Cloud vector store
No
Yes
Fast setup, automatic capture
OpenViking
Cloud semantic search
No
Yes
General-purpose semantic memory
Hindsight
Cloud episodic store
No
Yes
Structured episodic recall
RetainDB
Cloud hybrid (vector + BM25)
No
No
High-precision retrieval
ByteRover
Markdown knowledge tree
Yes
N/A (free)
Human-readable memory inspection
Supermemory
Cloud knowledge base
No
Yes
Cross-agent shared memory
To switch providers, run hermes memory setup and follow the interactive wizard. Check the current active provider with hermes memory status.
Marketplace
Free skills and AI personas for OpenClaw — browse the marketplace.
Honcho Setup: AI-Native User Modeling
Honcho is an AI-native memory backend developed by Plastic Labs that adds dialectic reasoning to Hermes Agent. Unlike simple vector stores that retrieve similar text, Honcho analyzes conversations after they happen and derives structured conclusions about the user's preferences, habits, and goals.
After each conversation, Honcho runs a question-and-answer process against the transcript. It asks itself: "What did I learn about this user? What preferences were expressed or implied? What goals are they working toward?" The resulting conclusions accumulate over time, giving the agent a deepening understanding that goes beyond what the user explicitly states.
Configuration is stored in $HERMES_HOME/honcho.json (profile-local) or ~/.honcho/config.json (global). To set up Honcho, run hermes memory setup and select "honcho" — the wizard detects your existing configuration. You will need a Honcho API key from honcho.dev, which offers a free tier for individual use.
Honcho works best for long-running personal agents where understanding the user deeply over weeks and months matters more than recalling specific facts from yesterday.
Holographic: Offline-First Vector Memory
Holographic is the most technically distinctive provider, using HRR (Holographic Reduced Representations) — a mathematical framework where memories are stored as superposed complex-valued vectors. Recall is algebraic rather than similarity-based, which means the system can compose and decompose memories mathematically instead of just finding the closest match.
The practical appeal is simpler: Holographic requires zero additional dependencies. It runs on pure SQLite with no pip installs, no API keys, and no network access. It works out of the box in air-gapped environments, on restricted VPS instances, and on machines where you cannot install additional packages.
Holographic also includes trust scoring — facts that are confirmed multiple times gain higher trust weight, while contradicted facts are demoted. FTS5 full-text search is available alongside the vector queries for keyword-based retrieval. To enable it, run hermes memory setup and select "holographic."
Which Method to Use — Decision Guide
The right persistence method depends on your deployment constraints and the type of recall you need.
Default (no configuration needed): MEMORY.md, USER.md, and SQLite session search run automatically. This covers most individual users who want the agent to remember projects, preferences, and past conversations. No setup required.
Air-gapped or offline: Add Holographic. It extends the default with semantic vector recall using only local SQLite — no network, no API keys, no dependencies.
Personal assistant over months: Add Honcho. Its dialectic reasoning builds a genuine user model over time, surfacing patterns the user may not explicitly state. Requires a free Honcho account.
Fast automatic capture: Add Mem0. It watches conversations, extracts facts automatically, and retrieves them by semantic similarity. Fastest setup at approximately 30 seconds with a free tier. Good for users who want memory that "just works" without curating files.
High-precision enterprise: Add RetainDB. Its hybrid vector + BM25 + reranking pipeline delivers the most precise retrieval, but it is the only paid-only provider with no free tier and no self-hosted option.
For persistent memory methods on the OpenClaw side, see our OpenClaw Persistent Memory Methods guide.
Limitations and Tradeoffs
Only one external memory provider can run at a time. You cannot stack Honcho and Mem0 simultaneously — you must choose one. The built-in MEMORY.md, USER.md, and session search always run regardless of which provider is active.
MEMORY.md and USER.md have hard character limits (2,200 and 1,375 respectively). When these fill up, the agent must compress or drop older information to make room. There is no overflow mechanism — if you need unbounded memory, an external provider is mandatory.
Session search via FTS5 is keyword-based, not semantic. It finds exact and fuzzy text matches but cannot find conceptually similar conversations the way a vector store can. If you ask the agent to recall "that time we discussed database optimization" but the actual conversation used the phrase "query performance tuning," FTS5 may not find it.
Holographic and ByteRover store data locally, which means backups are your responsibility. Cloud providers (Honcho, Mem0, RetainDB) handle durability but introduce a dependency on external services and their uptime.
When not to use external providers: if your agent handles sensitive data under compliance constraints, a cloud memory provider may not be acceptable. Use the built-in file memory plus Holographic for a fully local, auditable memory stack.
Related Guides
- Hermes Agent Memory System Explained
- OpenClaw Persistent Memory Methods
- Hermes Agent Setup Guide
- AI Agent Memory Explained
FAQ
Does Hermes Agent memory survive restarts and reinstalls?
Yes. MEMORY.md, USER.md, and the SQLite session database are stored as files in the ~/.hermes directory. They persist through restarts, updates, and reinstalls as long as this directory is not deleted. For Docker, mount ~/.hermes as a volume.
How do I switch between memory providers in Hermes Agent?
Run hermes memory setup to launch the interactive wizard. Select your preferred provider and enter any required credentials. Check the active provider at any time with hermes memory status. Switching providers does not erase data from the previous provider.
Which Hermes Agent memory provider works offline?
Holographic is the only external provider that works fully offline. It uses pure SQLite with HRR vectors and requires no API keys, no network access, and no additional pip installs. The built-in MEMORY.md and session search also work offline by default.
Can I use multiple memory providers at the same time in Hermes Agent?
No. Hermes Agent supports only one external memory provider active at a time. However, the built-in MEMORY.md, USER.md, and SQLite session search always run alongside whichever external provider is active.
What is the difference between Honcho and Mem0 for Hermes Agent?
Honcho uses dialectic reasoning to build a deep user model over time — it derives conclusions about preferences, habits, and goals through post-conversation analysis. Mem0 uses automatic fact extraction and vector similarity for retrieval. Honcho is better for long-running personal agents; Mem0 is better for fast, low-maintenance memory that captures facts without curation.
Top comments (0)