Hermes Agent memory providers don't replace MEMORY.md: what an external provider does, and how to add one

Disclosure: I work on MemorySync (I'm Mohammed, the founder). I drafted this article with AI assistance and checked it against the official Hermes Agent and MemorySync docs. Code status: on Oct 27, 2026 I ran the Step 4 installer (npx -y memorysync-hermes@1.1.0 install --target <scratch folder>, Node 20) and it copied the provider files. I then imported the installed provider in plain Python 3.13 with no API key set and checked its name, the "key not set" message, its four tools and its seven config fields. I did not install or run Hermes itself, so the hermes commands, the model and every MemorySync request were not run. Those parts are adapted from the docs.

The MemorySync Hermes Agent guide covers installing MemorySync as a Hermes memory provider. This article covers the part that confuses people first: a provider doesn't replace MEMORY.md.

Hermes Agent has a plug-in slot for an external memory provider. It's easy to assume that picking one swaps out Hermes' own memory. It doesn't. NousResearch/hermes-agent#25527 asks for exactly that, a mode where the external provider becomes the authoritative store for the built-in memory tool. Today the built-in files stay the canonical state and the provider adds to them or mirrors them. On Oct 27, 2026 that issue was still open.

Below: what the built-in memory is, what an external provider actually adds, how to decide what lives where, and how to add a provider, with MemorySync as the worked example. Hermes behaviour comes from the Hermes memory docs and the Memory Providers guide. I'm building MemorySync, and the MemorySync parts come from the MemorySync Hermes Agent guide.

Step 1: Know what the built-in memory is

Hermes' own memory is two files in ~/.hermes/memories/:

• MEMORY.md: the agent's notes (environment facts, conventions, things it learned). The docs give it a 2,200-character limit.
• USER.md: your profile and preferences, with a 1,375-character limit.

The agent edits both through its memory tool (add, patch or remove entries). Both are injected into the system prompt as a frozen snapshot at session start. A fact saved mid-session is written to disk right away, but it shows up in the prompt only from the next session. When a write would go over the limit, the tool returns an error and the agent has to make room itself.

So if Hermes "forgot" something, check these three things first (all from the Hermes docs):

1. Did the write happen? Open the file: cat ~/.hermes/memories/MEMORY.md. Saying "I've saved that" isn't the same as calling the tool.
2. Was it saved this session? Start a new session (/new) and look again.
3. Is the file full? Near the limit, new entries get rejected until old ones are consolidated.

Step 2: Know what an external provider adds

Per the Memory Providers guide, only one external provider can be active at a time, and the built-in memory stays active alongside it. When a provider is active, Hermes:

1. injects the provider's context into the system prompt,
2. prefetches relevant memories before each turn,
3. syncs conversation turns to the provider after each response,
4. extracts memories at session end (for providers that support it),
5. mirrors built-in memory writes to the provider,
6. adds the provider's own tools so the agent can search, store and manage memories.

The guide's own words: "The built-in memory (MEMORY.md / USER.md) continues to work exactly as before. The external provider is additive."

That's what #25527 is about. The built-in memory tool still writes to the local files first, and the provider only sees a mirrored copy. The issue proposes an opt-in "authoritative" mode where add/replace/remove go to the provider instead. Until something like that ships, plan for two stores.

Step 3: Decide what lives where

This split is my suggestion, not a Hermes rule:

• Keep in MEMORY.md / USER.md: a small set of curated, always-in-prompt facts (your name and role, how you like answers, the few project conventions every session needs). They're bounded and you can read them with cat.
• Put in the external provider: everything that won't fit or doesn't need to be in every prompt: decisions from past sessions, details you want recalled only when relevant, and memory you want shared.
• Sharing between agents: the Hermes docs say not to point two agent processes at one Hermes home. Give each agent its own profile, and if they need shared memory, use an external provider.

Step 4: Install a provider (MemorySync as the example)

Hermes looks for user-installed providers in $HERMES_HOME/plugins/<name>/ (the provider plugin guide lists this as the "User" source, per profile). Per the MemorySync Hermes Agent guide, you need Hermes Agent, Node.js 18+ for the one-time installer, and a MemorySync API key from the dashboard.

# 1. Copy the provider into your Hermes profile (default ~/.hermes)
npx -y memorysync-hermes install

# Non-default profile? Point it at that profile's plugins folder:
npx -y memorysync-hermes install --target /path/to/hermes-home/plugins/memorysync

# 2. Select it and paste your key when asked
hermes memory setup        # choose "memorysync"

# 3. Confirm it's the active provider
hermes memory status

When I ran the installer against a scratch folder, it copied five files (__init__.py, _client.py, _worker.py, plugin.yaml, README.md) and printed the same three next steps. The installed plugin.yaml declares pip_dependencies: [], so the provider doesn't add Python packages to the Hermes environment.

If you'd rather not use the wizard, the guide's manual route is:

hermes config set memory.provider memorysync
echo "MEMORYSYNC_API_KEY=ms_..." >> ~/.hermes/.env

The key goes in ~/.hermes/.env. The other settings go in ~/.hermes/memorysync.json.

Step 5: Set the user_id and the mode

Two settings decide whether recall works the way you expect.

user_id is whose memories these are. The provider takes the value Hermes passes for the session first, then user_id in memorysync.json, then your OS username. If you use MemorySync anywhere else (Claude Code, Cursor and so on), set the same user_id there to share one memory pool. Writes are also labelled per Hermes identity (hermes::<identity>), so you can still tell the sources apart.

memory_mode decides which half is on:

{
  "user_id": "alice",
  "memory_mode": "hybrid",
  "top_k": 8,
  "prefetch_enabled": true,
  "api_timeout": 5.0
}

With tools on, the model gets memorysync-search, memorysync-save, memorysync-profile and memorysync-forget (one memory by id; there's deliberately no delete-all). Those four names are what the installed provider reported in my keyless check.

Step 6: Know what this provider does with the built-in files

This is the part #25527 is about, so it's worth being exact. Per the MemorySync guide:

• MEMORY.md / USER.md keep working. Selecting MemorySync replaces Hermes' built-in provider slot (memory-core), not the files. Writes the agent makes to them are mirrored into MemorySync as durable facts tagged hermes-builtin.
• From each turn, only your message is sent, and only the durable facts extracted from it are stored. The message text and the assistant's replies aren't stored.
• Cron, subagent and flush contexts are passive: no reads and no writes. For a delegated subagent, the parent sends the delegated task for extraction; the subagent's result isn't stored.
• Failures don't stop the agent. With no key, no network or an exhausted monthly quota, the provider skips quietly. After repeated failures it pauses and the agent keeps answering without memory.

So MemorySync is additive too. It doesn't make itself the authoritative store for the built-in memory tool, and it can't until Hermes offers a mode like the one #25527 proposes.

Troubleshooting

• "memorysync" isn't offered in hermes memory setup. The installer copied it into a different profile than the one Hermes runs. Re-run it with --target <hermes-home>/plugins/memorysync.
• "MEMORYSYNC_API_KEY is not set". The provider reports itself unavailable without a key. That's the exact message I got from the installed provider with no key set. Run hermes memory setup to write the key to ~/.hermes/.env.
• Memories never appear. Check memory_mode (tools turns off injection and capture), check that user_id is the same across sessions, and remember that cron and subagent contexts don't read or write.
• The model can't see the memory tools. memory_mode: "context" removes them on purpose. Switch to hybrid or tools and restart Hermes.
• You want the built-in-only setup back. Hermes documents hermes memory off to turn off the external provider; the MemorySync guide also says you can re-run hermes memory setup and pick memory-core.

Common questions

Does a Hermes Agent memory provider replace MEMORY.md and USER.md? No. The Memory Providers guide says the built-in memory keeps working exactly as before and the external provider is additive. A mode where a provider becomes the authoritative store is requested in hermes-agent#25527, which was still open on Oct 27, 2026.

Can I run two external memory providers at once? No. Only one external provider is active at a time, alongside the built-in memory. You pick it with hermes memory setup or memory.provider in ~/.hermes/config.yaml.

Why doesn't something the agent saved show up until the next session? MEMORY.md and USER.md are injected as a frozen snapshot at session start. The write is on disk right away, but the prompt picks it up in the next session (Hermes memory docs).

Does the MemorySync provider store the assistant's replies? No. Per the MemorySync Hermes Agent guide, only your message from each turn is sent for fact extraction, and only the durable facts found are stored. Built-in MEMORY.md / USER.md writes are mirrored as facts tagged hermes-builtin.

Sources

• GitHub issue NousResearch/hermes-agent#25527 (open on 2026-10-27)
• Hermes Agent docs: hermes-agent.nousresearch.com/docs/user-guide/features/memory, /user-guide/features/memory-providers, /developer-guide/memory-provider-plugin
• npm package memorysync-hermes 1.1.0 (installer run and installed files read on 2026-10-27)
• MemorySync Hermes Agent guide: docs.memorysync.io/guides/hermes-agent

Try it

Minimal Python, TypeScript and cURL examples: memorysync-first-memory.

If you want to see a memory survive a full page reload before touching your Hermes setup, the MemorySync playground runs the save, reload and recall loop in your browser: memorysync.io/try.