Hermes Agent memory: where it lives and how to clear it

Hermes Agent memory is two small Markdown files per profile, MEMORY.md for the agent's notes and USER.md for what it knows about you, kept in ~/.hermes/memories/ and capped at 2,200 and 1,375 characters. Both are read once when a session starts and pasted into the system prompt. Everything else it can recall comes from a separate store: every conversation sits in a local SQLite database, state.db, which the agent searches with a full-text session_search tool. Memory files and limits; Session search.

This page goes further than the memory section of our Hermes Agent review. It's a source reading of the same pinned revision, 0b89435e7e4f7fab88a34eb69f13bf339eb2fd00: we read the documentation and the Python that implements it, and we didn't run Hermes. Where the docs and the code disagree, we say so.

• The files are plain text. Entries are separated by a line holding only §, so you can open, edit or empty them yourself.
• A fact saved mid-session doesn't reach the prompt until the next session, or until context compression or /undo rebuilds the prompt, neither of which the user guide mentions.
• A background review runs every 10 user turns by default. It can add entries, but it can't delete or rewrite them on its own; those changes wait for your approval.
• Session search returns stored messages, not model summaries, and deleting the Markdown files leaves state.db untouched.

What Hermes Agent memory stores, and where

There are three places Hermes keeps things about you, and they behave differently. The table is the short version; the sections below give the evidence.

The home folder is ~/.hermes on macOS and Linux, and %LOCALAPPDATA%\hermes on Windows unless HERMES_HOME says otherwise. The memories folder is computed from it on every call, which is why profiles get separate memory: hermes -p work reads ~/.hermes/profiles/work/memories/, not the default folder. Home resolution; Memory directory; Profiles.

The database path follows the same home, and its messages table keeps role, content, tool calls and reasoning fields for each message. state.db path; Messages table.

How the Hermes Agent memory tool writes entries

Hermes only remembers something when the model calls its memory tool. A reply saying "I'll remember that" is just text, and the official troubleshooting page says small or weak tool-calling models often produce the sentence without the call. Write check.

The tool has three actions, add, replace and remove, and two targets, memory and user. There's no read action, because the contents are already in the prompt. replace and remove find an entry by a short unique substring, and replace overwrites the whole entry rather than splicing text inside it. Tool actions; Schema enum.

The source adds a few things worth knowing:

• An add is stripped, scanned for prompt-injection and exfiltration patterns, skipped with a "no duplicate added" message if an identical entry exists, and refused if the joined file would pass the limit. Add path.
• Every write takes a lock, re-reads the file from disk, then saves through a temporary file and a rename, so a reader never sees half a file. Locked write; Atomic save.
• When memory is full, the tool asks for one batch that frees space and adds the new entry, checking the limit only on the final result. On the fourth consecutive failure in the same turn it tells the model to stop and answer you instead; a successful write resets the count. Batch guidance; Retry cap; Reset on success.

Nothing is auto-compacted. Hermes never drops an entry to make room; the model has to choose what to cut. No auto-compaction.

When Hermes Agent memory reaches the prompt

At load, Hermes reads both files, removes exact duplicates and renders a block with a header, a usage line giving the percentage and characters used, and the entries. That rendered text is the frozen snapshot. Writes during the session go to disk straight away, but the prompt keeps the old snapshot so the model provider's prefix cache stays valid. Snapshot at load; Frozen block.

The user guide says that snapshot "never changes mid-session". The code has two exceptions. After context compression, invalidate_system_prompt clears the cached prompt and calls load_from_disk() again, so a long chat that compresses picks up the session's own saves before it ends. /undo calls the same function, in the CLI and in the TUI, so rewinding a turn also reloads memory. The developer guide on prompt assembly mentions a compression-triggered rebuild; the user guide mentions neither. Our Hermes Agent architecture page covers how the rest of the prompt is assembled. User guide claim; Reload after compression; Developer guide; CLI undo, which calls it; TUI undo; Function binding.

Two load-time details matter if you edit the files by hand. An entry matching a threat pattern is replaced in the prompt with a [BLOCKED: …] note, while the raw text stays in the file so you can see and remove it. And a file over its limit isn't truncated: it all loads, a warning is logged, and every later add fails until you trim it. Load sanitising and over-limit warning.

On Telegram or Discord a chat is one continuous session, even across restarts, so new facts can stay out of the prompt for weeks. The docs suggest /new at natural boundaries. Session boundaries.

Hermes Agent memory you didn't ask it to save

Hermes saves without being asked. The guide says the agent stores preferences, corrections and environment facts proactively, and a background review runs after turns to catch what the main conversation missed. Proactive saving; Background review.

In the source, the memory nudge interval defaults to 10, and a counter of user turns fires the review when it reaches that number, provided the memory tool is available. Default interval; Turn counter.

The review is limited in what it can do alone. An unattended review may add, but any replace or remove, single or inside a batch, is staged for you to approve with /memory pending instead of being applied. If staging fails, the change is denied. That means a background pass can grow your profile but can't quietly rewrite or erase an entry you wrote. Background delete gate.

If you want every save checked, set memory.write_approval: true. The interactive CLI then prompts inline, and writes from messaging platforms, scripts and the review are staged. To stop the review entirely, set auxiliary.background_review.enabled: false. Write approval; Disabling reviews.

Hermes Agent session search, the other memory

The two Markdown files hold roughly 1,300 tokens between them. Anything bigger lives in state.db. Messages are indexed in an SQLite FTS5 table on content, tool name and tool calls, kept in sync by triggers. FTS5 table; Memory vs search.

The session_search tool infers its mode from the arguments: a query searches, a session id plus a message id scrolls around that message, a session id alone reads the session, and no arguments browses. Its header says there are no model calls; every shape returns stored messages. Tool modes.

Two ranking choices shape what the agent can find. Sessions from integrations, subagents and kanban workers are hidden from search. Cron sessions stay searchable but rank below your own conversations, because their repeated vocabulary was crowding them out. Hidden and demoted sources.

Compression doesn't delete any of this. It starts a continuation session, numbered #2, #3 and so on, and the sessions guide says plainly that compression "is not a privacy delete". Lineage on compression; Not a privacy delete.

External Hermes Agent memory providers

A provider plugin adds memory beyond the two files. Only one can be active at a time, chosen with memory.provider, and the built-in files keep working beside it. At this revision the repository ships RetainDB and ByteRover; Honcho, Hindsight, Mem0, OpenViking, Supermemory and Holographic come from the plugin catalog. Provider overview; One provider at a time.

Turning one on changes where your data goes. The docs list what the provider receives: injected context, prefetch before each turn, synced turns after each response, session-end extraction, and a mirror of every built-in memory write. Hermes runs a secret scrub over that traffic first, and the docs warn it misses credentials with no recognisable shape. In the source, the mirror only fires from the live memory tool, and only for a write that actually landed; a staged write is skipped. We found no mirror call on the /memory approve path either, so a write you approve later appears not to reach the provider. Committed-write check; Only caller; Approve path. What providers receive.

To choose one, run hermes memory setup for the picker, hermes memory status to see what's active, and hermes memory off to go back to the built-in files only. Where the data ends up differs by provider. Holographic is a local SQLite file, and ByteRover is local by default with optional cloud sync. Hindsight can run in the cloud, as local embedded PostgreSQL, or against your own local server. Honcho, Mem0 and Supermemory offer a cloud service or self-hosting, and RetainDB is cloud only. Setup commands; Holographic; ByteRover; Hindsight; Honcho; Mem0; Supermemory; RetainDB.

The source interface backs the mirror claim. on_memory_write receives each add, replace or remove with the target, the content and, for a replace or remove, the full previous entry. A separate on_pre_compress hook hands the provider the messages about to be compressed. Mirror hook; Pre-compress hook.

Hand edits never go through the tool, so a fact you delete from USER.md by hand is never sent to the provider as a removal, and it may still exist there. Removing it is the provider's job, and we didn't test any provider's deletion.

Check Hermes Agent memory on your own install

These commands and paths come from the pinned docs. Run them against your own setup; we haven't.

• cat ~/.hermes/memories/MEMORY.md and cat ~/.hermes/memories/USER.md show what will load next session. For a named profile, look in ~/.hermes/profiles/<name>/memories/, and use hermes profile list if you're unsure which profile you're on. File checks.
• /memory pending lists staged writes, including review changes tagged [auto]; /memory approve and /memory reject take an id or all. Staged writes.
• hermes journey list prints memory node ids, and hermes journey delete <node> removes a memory chunk. Journey commands.
• hermes memory status shows whether an external provider is active, and hermes memory off disables it. Provider commands.
• hermes sessions list browses history, and hermes sessions delete <id> removes one session. Close the chat first: a session still open will be recreated on its next save. Session deletion.

Hand edits are safe if you keep the format. The store splits entries on a newline, §, newline. It refuses to write, and saves a .bak copy, when a single entry is longer than the whole file's limit, which is what free text without separators looks like. It also refuses to write over a file it can't read, such as one with invalid UTF-8, rather than saving over it from an empty view. Separator; Drift guard; Unreadable file, refused before writing.

To switch memory off, set both memory.memory_enabled and memory.user_profile_enabled to false; the tool and its prompt guidance disappear. Listing memory under agent.disabled_toolsets also hides external provider tools. In the source, both flags default to true. Disabling memory; Flag defaults.

Where the Hermes Agent memory docs and source disagree

Most of the documentation matches the code. Three places don't, and one is only half true.

1. Frozen snapshot. The user guide says it never changes mid-session; compression and /undo both reload it, as shown above.
2. Folder path. The prompt-assembly guide names ~/.hermes/MEMORY.md and ~/.hermes/USER.md. The code and the user guide use the memories/ subfolder. Developer guide path.
3. Completed work. The user guide lists "Completed work" as something to save to memory. The tool description the model actually sees says to skip "completed-work logs" and use session_search for them, and to put task lessons in a skill. Expect the model to follow the tool description. Guide example; Tool description.
4. Providers "never replacing" built-in memory. True by default, but the same page explains how to turn the built-in stores off and run a provider instead. Additive claim.

Hermes Agent memory compared with OpenClaw

Both projects keep memory as Markdown you can open. OpenClaw promotes records into a workspace MEMORY.md and keeps a SQLite-backed index beside it, and deleting the file isn't verified to clear that index. Hermes is similar in shape: the Markdown files are what the prompt sees, and state.db is the searchable history that outlives them. Our OpenClaw security review covers its stores, and the Hermes Agent vs OpenClaw comparison puts the two side by side.

Hermes caps prompt memory at a few thousand characters and pushes everything else into search or skills. That makes it cheap to inspect: two short files and a database.

FAQ

Where is Hermes Agent memory stored? In ~/.hermes/memories/MEMORY.md and USER.md for the default profile, or ~/.hermes/profiles/<name>/memories/ for a named one. Conversation history is in ~/.hermes/state.db.

How big can Hermes Agent memory get? 2,200 characters for MEMORY.md and 1,375 for USER.md by default, set by memory_char_limit and user_char_limit. Session history in state.db has no such cap.

Why doesn't Hermes remember what I told it a minute ago? Either the tool was never called, so check the file, or the save happened after the session's snapshot was taken. Start a new session with /new.

Can I edit MEMORY.md by hand? Yes. Keep each entry separated by a line containing only §, and stay under the limit, or later saves will fail until you trim it.

How do I delete everything Hermes remembers? Empty or remove both memory files, delete sessions with hermes sessions delete or prune, and clear any external provider through its own tools. We haven't verified that this removes every copy, such as backups.

Does Hermes send my memory anywhere? The built-in files stay local, but they reach your model provider inside the system prompt. An external memory provider also receives synced turns and mirrored memory writes.