Does Hermes Agent remember everything I say?

No. It remembers what it explicitly writes to MEMORY.md or USER.md, and it can search past sessions via FTS5 keyword search. It does not automatically persist everything from every conversation. For reliable long-term memory, tell it explicitly to remember something, or use the Honcho semantic memory layer which does more aggressive cross-session fact extraction.

Can I read my own memory files?

Yes. SOUL.md, MEMORY.md, and USER.md are plain text Markdown files in ~/.hermes/. You can read and edit them with any text editor. The session database (state.db) is SQLite — readable with any SQLite client. Nothing is encrypted by default.

What is the difference between MEMORY.md and SOUL.md?

SOUL.md defines who the agent is — personality, communication style, what to avoid. MEMORY.md defines what the agent knows — facts about you, your preferences, your context. SOUL.md is loaded first in every system prompt and shapes how the agent speaks. MEMORY.md is loaded as factual context.

Does Hermes Agent use vector search for memory?

For local session history: no. It uses SQLite FTS5 full-text keyword search. For the optional Honcho integration: yes — Honcho uses semantic (vector) search and can find relevant memories even when exact keywords don't match. The other external providers (Mem0, RetainDB, Hindsight) also use semantic retrieval.

What happens to memory if I lose my VPS?

Everything in ~/.hermes/ is lost unless you had backups. Run: tar czf hermes-backup-$(date +%Y%m%d).tgz ~/.hermes/ and store the archive somewhere safe. On Hermes OS, automated nightly backups handle this without any manual setup.

How many memory providers does Hermes support?

Eight external providers in total: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, and a custom API mode. All are optional — local SQLite session storage works without any external provider. Select a provider with: hermes memory setup

Hermes Agent memory explained: SOUL.md, MEMORY.md, sessions, and Honcho

The four memory layers

Hermes Agent keeps memory in four distinct places: SOUL.md (identity/personality), MEMORY.md (explicit facts), a SQLite session database with FTS5 full-text search (conversation history), and optionally an external semantic memory provider like Honcho. Each layer serves a different purpose and operates on a different timescale.

The distinction matters because 'I told my AI agent something last week — why did it forget?' is almost always a question about which layer that information was supposed to live in, and whether it was actually written there. Hermes doesn't automatically remember everything — it writes to memory when it decides to, not when you speak.

SOUL.md — who the agent is

SOUL.md lives at ~/.hermes/SOUL.md. It defines the agent's identity and personality: tone, communication style, what to avoid, how to handle ambiguity. It is injected verbatim as the first slot in the system prompt — before any task context, before memory, before tools.

The format is free-form Markdown with no fixed schema. An example from the official docs:

# Personality
You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler

## What to avoid
- Sycophancy
- Hype language

Changes to SOUL.md take effect from the next session. If SOUL.md is empty or missing, Hermes falls back to the built-in default: 'You are Hermes Agent, an intelligent AI assistant created by Nous Research.'

SOUL.md answers the question 'who is the agent?' MEMORY.md answers 'what does the agent know?' They do not overlap. Editing SOUL.md does not affect what the agent remembers about you — it changes how it speaks and reasons. Keep it stable across contexts, broad enough to apply to many conversations, and specific enough to actually change the behavior.

MEMORY.md — what the agent knows

MEMORY.md lives at ~/.hermes/MEMORY.md. The agent writes to it when it decides something is worth remembering permanently — your name, your tech stack, standing preferences, recurring context that would be wasteful to re-explain every session.

You can read and edit it directly — it is plain text Markdown. There is no encryption. If you share your Hermes backup with someone, they can read your MEMORY.md.

nano ~/.hermes/MEMORY.md

The agent does not write to MEMORY.md automatically for everything it learns in a conversation. It writes when it judges something as durable and worth persisting. You can prompt it explicitly: 'Remember that I prefer TypeScript over JavaScript for all projects.' You can also delete mistaken memories by editing the file directly.

USER.md at ~/.hermes/USER.md is a related file that stores inferred information about the user — preferences, working style, background context the agent has built up over time. The agent updates it based on observed patterns in your behaviour, not explicit instructions. Think of MEMORY.md as 'facts you told it' and USER.md as 'conclusions it drew about you'.

Session memory — SQLite FTS5 search

All conversations are stored in ~/.hermes/state.db — a SQLite database running in WAL mode. It has four tables: sessions (metadata and token counts), messages (full message history per session), messages_fts (FTS5 virtual table for full-text search), and schema_version (migration state, currently version 6).

The search technology is SQLite's FTS5 full-text search — keyword-based, not vector-based. The agent calls the session_search tool when it decides past context is relevant to the current task. It does not automatically prefetch every past conversation — you can ask it to search explicitly:

'What did I tell you about the auth service last month?'

FTS5 query syntax:

docker deployment          # implicit AND
"exact phrase"             # quoted phrase
docker OR kubernetes       # OR
python NOT java            # NOT
deploy*                    # prefix match

The key limitation of FTS5 search: it matches keywords, not meaning. If you told the agent your CI system was 'the pipeline thing' and later search for 'CI/CD configuration', it may not connect them. This is the gap that Honcho's semantic layer fills.

Session files are stored indefinitely unless you configure pruning. Check storage usage with hermes sessions stats. Sessions can be exported with hermes sessions export for backup or migration.

Honcho — semantic memory over the full history

Honcho (from Plastic Labs) is an optional external memory layer that adds semantic search on top of the local SQLite history. It runs as a separate service, stores a 'user peer' and 'AI peer' — representations built from observed messages — and injects relevant context into the system prompt before each turn.

The difference from FTS5: Honcho can find relevant memories even when the keywords don't match. It answers questions like 'what were we working on last month?' without requiring the exact words used.

Honcho adds four tools the agent can call:

honcho_profile — fast peer card retrieval (no LLM), returns curated key facts about the user
honcho_search — semantic search over memory, returns raw excerpts ranked by relevance
honcho_context — Q&A powered by Honcho's LLM, synthesizes answers from full history
honcho_conclude — writes durable facts to Honcho when the user states something important

Some providers (Hindsight, Honcho) auto-prefetch relevant memories before each turn. Others (FTS5 session search) wait for the agent to decide to call them.

Setting up Honcho requires running it as a separate Docker service:

git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp .env.template .env && cp docker-compose.yml.example docker-compose.yml
# Edit .env with your API keys and DB_CONNECTION_URI
docker compose up -d

Then configure Hermes to use it:

hermes memory setup  # interactive provider selection
# or:
hermes config set memory.provider honcho

Memory mode options: hybrid (local session history + Honcho, recommended), honcho (Honcho only), local (no external provider). Switch with hermes honcho mode.

Beyond Honcho, Hermes supports seven other external memory providers: OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, and a custom API mode for building your own provider.

What Hermes actually remembers vs forgets

What persists reliably: your name (if you told it); your tech stack (if you mentioned it and it wrote it to MEMORY.md or USER.md); explicit standing instructions ('always format code examples with TypeScript'); facts you told it and then confirmed it remembered; sessions in the SQLite database (indefinitely).

What is unreliable: anything you mentioned once casually that the agent didn't judge worth persisting; things mentioned in a long conversation after the context window filled; anything expressed in a way that FTS5 keyword search won't surface later.

What doesn't persist at all: anything kept only in the in-context window of a session that ended and wasn't explicitly written to MEMORY.md, USER.md, or Honcho. The context window clears at session end. If you want something remembered, say 'remember this' explicitly — or edit MEMORY.md directly.

One practical pattern: at the end of a productive session, ask the agent 'What should I add to your memory from today's conversation?' It will identify facts worth keeping and write them to MEMORY.md. This is faster than manually editing the file and catches things you might not think to record.

Backing up and restoring memory

All memory files are in ~/.hermes/. Backup the entire directory:

tar czf hermes-backup-$(date +%Y%m%d).tgz ~/.hermes/

This captures SOUL.md, MEMORY.md, USER.md, the SQLite session database, config files, and installed skills. It does not capture API keys unless they are stored in ~/.hermes/.env (they usually are — encrypt the backup before storing it anywhere):

gpg --symmetric --cipher-algo AES256 hermes-backup-*.tgz

Restoring on a new server:

tar xzf hermes-backup-YYYYMMDD.tgz -C ~/
# Hermes will pick up the restored ~/.hermes/ directory on next start

For migration to Hermes OS managed hosting: export your profile with hermes profile export default, then import it in your Hermes OS instance. The migration preserves config, skills, and memory structure.

Memory on Hermes OS

Every Hermes OS instance runs with persistent memory enabled by default. SOUL.md, MEMORY.md, USER.md, and the session database are all stored on persistent volumes that survive container restarts and redeployments. You do not need to configure backup procedures — Hermes OS handles nightly automated backups.

The session database persists across the full life of your subscription. Cancelling and reactivating restores all memory files to the state at cancellation, within the backup retention window.