Memory Providers — Where Memory Lives

Ever feel like your AI assistant forgets everything between conversations? You tell it your coffee order, your project deadlines, your dog’s name — and next session, it’s like you’re strangers again.

That’s where memory providers come in. Think of them as the long-term brain for your Hermes Agent. While the built-in MEMORY.md and USER.md files are like sticky notes on your desk, memory providers are like a full filing cabinet — searchable, organized, and persistent across every session.

The Big Picture

Hermes Agent ships with 2 external memory provider plugins (RetainDB and ByteRover), and more (such as Honcho, Hindsight, Supermemory and Holographic) are available from the plugin catalog. Here’s the key rule: only one external provider can be active at a time, but the built-in memory always stays on alongside it. So you’re never losing your basic setup — you’re just adding superpowers.

Each provider’s data is isolated per profile, so different profiles don’t step on each other’s memories.

Getting Started in 3 Commands

hermes memory setup      # interactive picker + configuration
hermes memory status     # check what's active
hermes memory off        # disable external provider

That’s it. Run hermes memory setup, pick your provider, and you’re rolling. You can also switch providers through hermes plugins → Provider Plugins → Memory Provider, or manually edit ~/.hermes/config.yaml:

memory:
  provider: retaindb  # or byterover,
                      # or honcho / hindsight / supermemory / mem0 / openviking / holographic
                      # (plugin catalog — run `hermes plugins install <name>` first)

What Happens When a Provider Is Active?

Once you’ve got a provider running, Hermes automatically does six things behind the scenes:

1. Injects provider context into the system prompt — so the agent knows what it knows
2. Prefetches relevant memories before each turn (in the background, so no lag)
3. Syncs conversation turns to the provider after each response
4. Extracts memories on session end (for providers that support it)
5. Mirrors built-in memory writes to the external provider
6. Adds provider-specific tools so the agent can search, store, and manage memories

The best part? Your built-in memory keeps working exactly as before. The external provider is purely additive — no breaking changes.

Everything Hermes hands a provider (turns, the transcript including tool output, recall queries, session-end and pre-compression transcripts, mirrored memory writes, delegation results and the arguments of the provider’s own tools) passes through the same secret scrub as chat-platform and cron delivery first, so a key echoed into tool output is masked before the provider can store it. Like that delivery scrub it applies even with security.redact_secrets: false. Credentials with no recognisable shape (an arbitrary password, an opaque token outside a key=value or Bearer context) are not detected; your local transcript keeps the original text.

Spotlight: Honcho

Let’s zoom in on one provider to show you what’s possible. Honcho is an AI-native system for cross-session user modeling. It uses “dialectic reasoning” — basically, it has internal conversations about you to build a richer picture over time.

Honcho is maintained by Plastic Labs and installed from the plugin catalog rather than bundled with Hermes. It’s the same provider that used to ship in-tree: tools, config files and the hermes honcho commands are unchanged.

What Makes Honcho Special?

• Two-layer context injection: a base layer (session summary + user representation + peer card) plus a dialectic supplement (LLM reasoning). The dialectic automatically picks cold-start prompts (general facts) vs. warm prompts (session-specific) based on what it already knows.
• 5 built-in tools: honcho_profile (read/update peer card), honcho_search (semantic search), honcho_context (session context), honcho_reasoning (LLM-synthesized), and honcho_conclude (create/delete conclusions).

Three Knobs to Control Cost and Depth

You get independent control over how much you spend and how deep the reasoning goes:

• contextCadence — how often the base layer refreshes (API call frequency)
• dialecticCadence — how often the dialectic LLM fires (LLM call frequency)
• dialecticDepth — how many reasoning passes per invocation (1–3)

There’s also a query-adaptive reasoning level: longer queries automatically trigger deeper reasoning, capped at a configurable reasoningLevelCap.

Setup Wizard Got a Makeover

The old hermes honcho setup command still works (it redirects to hermes memory setup), but the new wizard is smarter. For headless machines (SSH, remote VMs), just pick device at the auth-method prompt — the CLI prints a short code and verification link, you approve from any browser, done. No API key copy-paste needed. It even auto-detects when there’s no usable local browser and defaults to this option.

Installing Honcho

Honcho needs the plugin plus an API key (or a self-hosted instance):

hermes plugins install honcho   # from the plugin catalog
hermes memory setup             # select "honcho" — runs the Honcho-specific post-setup

Config File Locations

Honcho looks for config in this order:

1. $HERMES_HOME/honcho.json (profile-local)
2. ~/.hermes/honcho.json
3. ~/.honcho/config.json (global)

See the plugin README and the Honcho integration guide.

Upgrading from the Bundled Honcho

Earlier Hermes releases shipped Honcho in-tree. If a profile still has memory.provider: honcho, Hermes installs the catalog plugin automatically the next time it starts or runs hermes update — your ~/.honcho/config.json (or $HERMES_HOME/honcho.json), host blocks, peers and session mappings are read exactly as before, so no memory is lost. To do it by hand, or on a machine without network access at startup, run hermes plugins install honcho.

Hindsight: Now a Plugin

Hindsight used to ship inside the Hermes tree, but it now lives in the plugin catalog — it’s maintained by vectorize-io and installed separately. Setup details live in the upstream docs: hindsight.vectorize.io/sdks/integrations/hermes.

hermes plugins install hindsight   # from the plugin catalog; answer "Use 'hindsight' as the memory provider now?"
hermes memory setup                # select "hindsight"

The plugin lands in ~/.hermes/plugins/hindsight/ (per profile home). A memory provider is activated by memory.provider in config.yaml, not plugins.enabled: accepting the install prompt (or passing --enable) sets it, and declining leaves it unchanged so hermes memory setup can pick it later. hermes plugins enable hindsight does not activate a memory provider. hermes memory setup, hermes memory status, hermes plugins list and the dashboard Memory settings all work with the catalog-installed plugin. In local embedded mode the plugin installs hindsight-all on first use through Hermes’ lazy-install path, which honours security.allow_lazy_installs.

If your config.yaml already has memory.provider: hindsight, there’s usually nothing to do: hermes update installs the catalog plugin into every profile home that names the provider, and if it’s still missing on the first agent start, Hermes installs it and prints a confirmation. When the agent-start install cannot happen, you see why instead of silently running without external memory: with security.allow_lazy_installs: false the warning names the install command for that profile; offline or declined installs show the error and the same command. After a failed attempt, agent starts in the next hour skip the install and only repeat the command; hermes update always retries. Agent start never asks a question (the chat prompt owns the terminal), so a catalog provider that never shipped with Hermes (for example mnemosyne) is not installed on agent start — the warning names hermes plugins install <name> for that profile, or you install it from the dashboard/Desktop Plugins page. Your $HERMES_HOME/hindsight/config.json, HINDSIGHT_API_KEY in .env and your memory bank data are all untouched — verify with hermes memory status and hermes plugins list.

One caveat: Hindsight reads $HERMES_HOME/hindsight/config.json (per profile home), ~/.hindsight/config.json (legacy shared), and the HINDSIGHT_* variables in .env. It does not read a memory.hindsight section of config.yaml — a memory.hindsight.* key there is ignored. Edit the plugin’s own config.json or use hermes memory setup.

Supermemory: Also a Plugin

Supermemory is maintained by Supermemory and installed from the plugin catalog rather than bundled with Hermes. Source and full configuration reference: supermemoryai/hermes-supermemory.

hermes plugins install supermemory   # from the plugin catalog
hermes memory setup                  # select "supermemory"

It needs a cloud API key or a self-hosted server. If your config.yaml already has memory.provider: supermemory, there’s nothing to do for most users: hermes update installs the catalog plugin into every profile home that names the provider (this runs even when security.allow_lazy_installs is false), and if it’s still missing on the first agent start, Hermes installs it and prints a confirmation. With security.allow_lazy_installs: false, the agent-start path instead logs one line telling you to run hermes plugins install supermemory yourself.

What changes on disk: the plugin appears in ~/.hermes/plugins/supermemory/ and config.yaml gains plugins.enabled: [supermemory]. The Supermemory SDK is installed from the plugin’s own package metadata, so the hermes-agent[supermemory] pip extra is no longer needed. Your memory.provider, $HERMES_HOME/supermemory.json and stored data are unchanged.

OpenViking: Now a Plugin

OpenViking is maintained by Volcengine and installed from the plugin catalog rather than bundled with Hermes. Source: volcengine/OpenViking — examples/hermes-plugin.

# Then install and configure the Hermes plugin
hermes plugins install openviking
hermes memory setup   # select "openviking"

OpenViking must be initialized, validated, and running. When the endpoint is local and nothing is listening, the plugin starts openviking-server in the background. At the cataloged version that server inherits the full Hermes process environment (minus PYTHONPATH), including any bot, gateway or relay tokens set there. If that matters to you, start openviking-server yourself before Hermes so the plugin never spawns it. The fix is tracked upstream in volcengine/OpenViking#5553.

Migrating from bundled OpenViking

OpenViking used to ship inside the Hermes tree. If your config.yaml already has memory.provider: openviking, there is nothing to do for most users:

• hermes update installs the catalog plugin into every profile home that names the provider.
• If the plugin is still missing on the first agent start (hermes chat, the gateway, Desktop), Hermes installs it and tells you it did.
• With security.allow_lazy_installs: false the agent-start path does not install anything; it prints the exact hermes plugins install openviking command instead.

memory.provider, memory.openviking.*, the OPENVIKING_* keys in .env, ~/.openviking/ and the memories on your OpenViking server are untouched. Verify with hermes memory status and hermes plugins list.

Mem0: Now a Plugin

Mem0 is maintained by Mem0 and installed from the plugin catalog rather than bundled with Hermes. Source: mem0ai/mem0 — integrations/hermes-plugin-mem0.

hermes plugins install mem0   # from the plugin catalog
hermes memory setup           # select "mem0"

It needs an API key (platform), a running Mem0 server (self-hosted dashboard), or an LLM + vector store (OSS). The mem0ai SDK sends anonymous PostHog usage telemetry unless MEM0_TELEMETRY=false is set in your shell or ~/.hermes/.env.

Migrating from bundled Mem0

Mem0 used to ship inside the Hermes tree (and as the hermes-agent[mem0] pip extra). If your config.yaml already has memory.provider: mem0, there is nothing to do for most users:

• hermes update installs the catalog plugin into every profile home that names the provider.
• If the plugin is still missing on the first agent start (hermes chat, the gateway, Desktop), Hermes installs it and tells you it did.
• With security.allow_lazy_installs: false the agent-start path does not install anything; it prints the exact hermes plugins install mem0 command instead.

memory.provider, $HERMES_HOME/mem0.json, the MEM0_* keys in .env and the memories stored in Mem0 Cloud, your Mem0 server or the local OSS store are untouched. Verify with hermes memory status and hermes plugins list.

Holographic: Also a Plugin

Holographic is maintained by itpartypattaya and installed from the plugin catalog rather than bundled with Hermes.

hermes plugins install holographic   # from the plugin catalog
hermes memory setup                  # select "holographic"

The Takeaway

Memory providers turn Hermes from a chatty assistant into a continuously learning partner. Whether you’re building multi-agent systems, need cross-session context, or just want your agent to remember your preferences without re-explaining them every time — there’s a provider for you.

Start with hermes memory setup, explore the options, and give your agent a memory worth having.