Hermes Agent memory: what it keeps, where it lives and how to control it

Built-in memory: MEMORY.md and USER.md

Out of the box, Hermes keeps two plain-text files in a memories folder inside its home directory (~/.hermes/memories/ on a default install):

• MEMORY.md holds the agent’s own notes: facts about your environment, project conventions, tool quirks, lessons it learned. The default limit is 2,200 characters, roughly 800 tokens.
• USER.md is the profile of you: your name, role, preferences, how you like answers written. The default limit is 1,375 characters, roughly 500 tokens.

The limits are deliberate. Both files are copied into the system prompt at the start of every session, so they cost tokens on every request; keeping them small keeps them cheap and focused. Entries are separated by a § line, and the prompt shows how full each file is. You can change the limits with memory_char_limit and user_char_limit under the memory section of config.yaml.

The agent writes to it itself. It uses a tool called memory with three actions: add, replace and remove. There is no read action, because the files are already in the prompt. Replace and remove find an entry by a short unique piece of its text. When a write would go over the limit, the tool returns an error rather than quietly dropping something, and the agent is expected to merge or delete older entries first. Exact duplicates are rejected, and entries are scanned for prompt-injection and credential-exfiltration patterns before they are accepted, because they end up inside the system prompt.

Hermes also reviews conversations in the background after a turn and may save a memory or a skill without being asked; the setting memory.nudge_interval (10 by default) controls how often the memory review runs. By default the chat shows a short “Memory updated” line when that happens.

Two things surprise people. First, the prompt copy is a snapshot taken when the session starts. A note saved mid-conversation is on disk straight away, but the prompt normally keeps its snapshot until the next session or until a long conversation is compressed. Second, on messaging platforms a chat is one long session that survives restarts and never resets on its own, so memory pays off at the boundaries you create: send /new when you finish a task or change topic, and the next session starts with the updated files.

If you told the agent to remember something and it forgot, check the file before blaming the model. Memory only persists when the model actually calls the tool; weaker or very small models sometimes reply “noted” without calling it. Also check that you are looking at the right profile, because every Hermes profile has its own memories folder.

Past conversations: session history and search

The two small files cannot hold a month of conversation, so Hermes keeps the rest elsewhere. Every session from the terminal, the desktop app and every chat platform is stored in a SQLite database, ~/.hermes/state.db, with a full-text search index (SQLite FTS5).

The agent reads it through a tool called session_search. It does no summarising with a model: it returns the actual matching messages, and the agent can scroll forward and backward inside a session it finds. It is prompted to use it when you refer to something from before, such as “we did this last week” or “as I mentioned”. The practical split is simple: memory is for the few facts that must always be in front of the agent; session search is for everything you would otherwise have to repeat.

You can browse the same history yourself:

hermes sessions list
hermes sessions list --source telegram
hermes sessions delete <session-id>

Old sessions do not live forever. Automatic pruning is on by default and removes ended sessions that have been inactive for sessions.retention_days, which defaults to 90; set sessions.auto_prune to false to keep everything. Open and pinned sessions are never pruned.

Context files: instructions, not memories

Context files look like memory but behave differently: they supply instructions, and you normally write them yourself. You can also ask the agent to edit them, though protected project instruction files need your approval by default. Hermes loads the ones that apply into the prompt automatically.

• SOUL.md in the Hermes home folder sets the agent’s personality and tone. It is global to that Hermes instance and always loaded.
• Project instructions come from the working directory. Only one type is loaded per session, with this priority: .hermes.md, then AGENTS.md files, then CLAUDE.md and .cursorrules. Inside a git repository, AGENTS.md files are merged from the repository root down to your directory (in each folder, an AGENTS.override.md takes the place of that folder’s AGENTS.md), and ones in subfolders are picked up when the agent starts working there.

Use a context file for rules that should always apply to a project (how to run the tests, naming conventions) and memory for what the agent learns about you along the way. For a procedure the agent should follow only when relevant, a skill is a better home than either; see Hermes Agent skills. Context files get a security scan too, though a different one from memory entries: a match blocks a project context file, while a SOUL.md you wrote in the Hermes home folder only produces a warning and still loads.

Honcho: what it adds and how to turn it on

Honcho is a memory service from Plastic Labs that Hermes supports as a memory provider plugin. Where the built-in files are a short list the agent curates, Honcho keeps a server-side model of the user. It stores the conversation, reasons about it after the fact, and produces conclusions about your preferences, habits and goals. Per the Hermes documentation, it adds:

• automatic user modelling, instead of the agent hand-writing a profile;
• a session summary and a “peer card” of key facts injected into the prompt;
• semantic search over what it has concluded, alongside the plain-text search of your history;
• separate peer profiles when several agents or several people talk to the same setup.

It runs next to the built-in files, never instead of them. Only one external provider can be active at a time.

Enable it. The setup wizard is the simplest route:

hermes memory setup honcho

The wizard asks for your Honcho API key (from app.honcho.dev) or the address of a self-hosted server, and writes the settings. On a machine with no browser it can use a device code instead. By hand, set memory.provider: honcho in ~/.hermes/config.yaml, put HONCHO_API_KEY in ~/.hermes/.env, and for terminal sessions set peerName in honcho.json so Honcho knows who you are. Honcho’s own settings live in honcho.json, either in the Hermes home folder or at ~/.honcho/config.json. Once Honcho is active, a hermes honcho command group appears, with status, mode, strategy, peers and disable. The Python package honcho-ai must be installed.

The settings that matter most in honcho.json:

• recallMode: hybrid (the default: context is injected and the tools are available), context (inject only) or tools (the agent must ask).
• contextCadence, dialecticCadence and dialecticDepth: how often the context is refreshed, how often Honcho’s reasoning runs, and the most reasoning passes (1 to 3) a run may make; it can stop early once it has enough. These are the cost dials; the reasoning runs are model calls on Honcho’s side.
• sessionStrategy: per-session, per-directory (the default), per-repo or global. Messaging chats keep one session per chat whatever you pick.
• saveMessages (on by default), peerName, baseUrl for a self-hosted server, and contextTokens to cap how much Honcho context enters each prompt.

In normal chat sessions with recallMode set to hybrid or tools, Honcho gives the agent five tools: honcho_profile, honcho_search, honcho_context, honcho_reasoning and honcho_conclude. If several people use one chat gateway, read the identity-mapping options (pinUserPeer, userPeerAliases) first, so that one person’s facts are not filed under another’s name.

Is it worth it? For one person using one agent, the built-in files plus session search cover a lot without a separate memory-service subscription, though prompt tokens and background memory reviews still use model calls. Honcho earns its place when you want the agent to infer things you never stated, or when several agents or users share one setup. It also sends your conversations to another service (see the privacy section) and the reasoning adds model calls, so treat it as an upgrade you choose, not a default.

The other memory providers Hermes supports

Six more providers ship inside Hermes 0.21.5, next to Honcho. You pick one with hermes memory setup or by setting memory.provider, and turn it off again with hermes memory off. hermes memory status shows what is active.

• Mem0 (mem0): extracts and stores facts automatically; hosted by Mem0 or self-run.
• Supermemory (supermemory): semantic recall with a user profile; cloud or self-hosted.
• OpenViking (openviking): self-hosted knowledge store with structured browsing.
• Holographic (holographic): local-only, SQLite-based, with no outside service at all.
• ByteRover (byterover): local-first memory driven by its own command-line tool, with optional cloud sync.
• RetainDB (retaindb): a hosted service with an account and API key.

Hindsight, a knowledge-graph provider, is distributed through the plugin catalog instead: run hermes plugins install hindsight first. What a provider injects, captures automatically and offers as tools depends on the provider and its settings. Successful writes to the built-in memory can be mirrored to the active provider, but provider memories are not copied back into the built-in files. Provider settings are per profile, but what is stored remotely depends on the account and namespace you use, so give profiles separate ones if they must not share memories. For what each provider stores, costs and requires, use the upstream Memory Providers page, because those details change.

How to view, edit and reset what Hermes remembers

Built-in memory is plain text, which makes it easy to audit. To see it:

cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

You can edit these files with any editor. Keep entries separated by a line containing only §, stay under the limits, and start a new session afterwards so the change is picked up. Do not run two agents against the same Hermes home folder: their automatic writes pile up in files neither of you wrote. Give a second agent its own profile instead.

You can also just ask the agent to change a note. “Forget that I work in Lisbon” prompts it to call memory with remove. Hermes also has a learning timeline, hermes journey, which lists saved skills and memory entries over time; with hermes journey list, hermes journey edit <node> and hermes journey delete <node> you can open or remove individual items.

Approve writes before they happen. If you do not like the agent saving things unprompted, set memory.write_approval to true. Memory writes are then held for you: in the terminal Hermes asks inline, and everywhere else (chat platforms and the background review) they are staged. In a chat, /memory pending lists them, and /memory approve or /memory reject followed by an id, or all, decides. /memory approval on or off flips the gate.

Reset or switch off. To wipe the built-in memory:

hermes memory reset
hermes memory reset --target user
hermes memory reset --target memory --yes

The target is all by default, or just memory or user. To stop the feature instead, set both memory.memory_enabled and memory.user_profile_enabled to false, which also removes the tool and its prompt guidance. Resetting the built-in files does not touch your session history or an external provider; those have their own controls (hermes sessions delete, hermes memory off and the provider’s own dashboard or API).

Privacy: what stays local and what does not

Separate the layers when you think about privacy:

• Built-in files, session history and context files are ordinary files on the machine running Hermes. With no external memory provider enabled, they are not sent to a memory service. They are, however, part of the prompt or tool results that go to the language model you chose, so your model provider sees whatever the agent loads on a given turn. Turning on an external provider can also send conversation turns and memory writes to it.
• Credentials are not memory. Keys in .env are settings. Do not ask the agent to memorise a password; the memory file is plain text and goes into the prompt.
• External providers send data out. Honcho with saveMessages on stores your conversation turns with its service, in Honcho’s cloud unless you point baseUrl at a server you run. Hosted options from other providers work the same way; local options such as Holographic do not.
• Several users in one chat or gateway. The built-in files belong to the profile, not to a person, so anything saved in a shared chat is visible to that agent in every conversation on the profile. Use separate profiles for separate people.

If privacy is the priority, keep the built-in files, turn on write_approval, skip external providers or self-host one, and prune or delete old sessions.

Hermes Agent memory on ReadyHermes

On ReadyHermes your agent is a full Hermes Agent running on our servers, so the built-in memory is on and works as described above. Your assistant keeps your conversations and what it has learned across restarts, and a restart from the workspace keeps your conversations, memory and connected apps. The workspace’s New chat keeps your last 15 conversations under Past chats, and opening one carries on where you left off. Those are the workspace’s own saved chats; the agent’s own history search described earlier is a separate Hermes feature that works inside the agent.

What you can and cannot do there, as of the version we checked:

• Look at the files. The Files panel browses the Hermes home directory. Download memories/MEMORY.md and memories/USER.md there and open them in a text editor. Asking the assistant to show or change what it remembers also works.
• Honcho is not a switch in the workspace. There is no Honcho or memory-provider setting on ReadyHermes. We install the Honcho client library in the assistant’s environment, so Hermes’ own hermes memory setup wizard can run without installing anything, and the workspace offers an SSH terminal over your own Tailscale network for running commands. Whether you want to connect a third-party memory service to a hosted assistant is your decision, and nothing on our side configures or supports it for you.
• Plugins. The Plugins panel lists plugins from the upstream catalog that can run on a hosted assistant, and installing or removing one restarts the assistant, usually in under a minute. Do not assume any particular memory plugin is on that list; check the panel.
• Your data. The Privacy section of the workspace can download a JSON copy of your account data and saved conversations. Clear history removes the workspace’s current and past chats, but it does not erase the Hermes memory files or the agent’s own history. To remove memories, delete the files under memories/ in Files or ask the assistant to remove entries.

You reach the same agent from Telegram, WhatsApp, Discord, WeChat and Lark, and it uses the same memory in all of them. New assistants are ready in about ten seconds, and the free trial lasts an hour. To compare running it yourself with a managed one, read self-hosting versus managed hosting, or see managed Hermes Agent hosting for what is included.