Hermes Agent Memory with Supermemory

Hermes has built-in memory files and can use Supermemory as a memory provider plugin. The provider adds external recall, profiles and capture through Hermes's lifecycle. Check both capture and recall when setting up continuity for a project.

Start with the provider README for your installed version. The provider used to ship inside the Hermes repository and now lives in its own repository, maintained by supermemory and listed in the Hermes plugin catalog. Provider behavior can change independently of the Supermemory API.

Install and configure

With Hermes installed, run:

hermes plugins install supermemoryai/hermes-supermemory
hermes plugins enable supermemory
hermes memory setup

The install step adds the Python SDK the provider needs to Hermes's own environment, so there's no separate pip install (maintainer notes). Choose Supermemory and supply a key from the console. Keep the key out of source control. For manual configuration, the provider documents memory.provider and the SUPERMEMORY_API_KEY environment variable.

The provider is free on every plan; hosted ingestion and retrieval consume usage under the current rate card. Free plugin access does not mean unlimited free API usage.

Check the capture path

The current provider captures completed user/assistant turns when enabled. It saves each conversation as one document, rewritten in full after every completed turn, so undo, edits and compaction don't store it twice. A failed save is logged, never breaks the turn, and is retried later, for up to 50 conversations.

The retry buffer is bounded, so a long outage can still lose saves. Inspect results rather than assuming automatic capture means nothing can be lost.

Use a synthetic conversation to verify what is stored. Include a rejected suggestion so you can check that a proposed plan is not treated as an accepted decision.

Configure scope explicitly

The documented default container is hermes. If profiles should be separated, set the supported identity template in $HERMES_HOME/supermemory.json:

{
  "container_tag": "hermes-{identity}"
}

Without that template or another explicit separation scheme, different Hermes profiles can use the same container. A profile name alone is not proof that external memory is isolated.

Optional multi-container mode allows named additional containers. Automatic capture and prefetch use the primary container; explicit tool calls can target an allowed additional container. Instructions guide the model's choice but do not guarantee perfect classification of work and personal content.

Verify the destination on an explicit save and the scope on a search. Repeat with an unrelated container as a negative test.

Use the exposed tools

The provider exposes save, search, forget, profile and read-document operations through supermemory-save, supermemory-search, supermemory-forget, supermemory-profile and supermemory-read-document, with documented snake_case aliases. Check the returned record and scope before interpreting the final answer as successful recall.

Forgetting and source deletion are different operations. The memory lifecycle guide explains why hiding an extracted memory from normal retrieval is not a promise to erase every stored document or transcript.

Keep native files and external memory understandable

MEMORY.md and USER.md remain part of Hermes's native behavior. The current provider handles eligible additions through its memory-write hook. That does not establish a complete initial import or bidirectional synchronization of every edit and deletion.

If you change a local note, verify whether the external copy changes too. If you remove a fact, check both stores. A successful write hook does not establish that all existing file contents were imported when the provider was enabled.

Test before relying on a new session

Save a fictional project code name, end the session, and retrieve it from a new session under the intended scope. Then correct it and test the lifecycle. Check errors and pending writes if it is missing.

Compaction reduces active context. Captured source content may help recover details later, but capture and retrieval are separate steps. Include a compacted session in your recall test.

Self-host with an explicit data-flow boundary

The provider supports a base_url for a local or private Supermemory endpoint. Follow the self-hosting documentation and configure that endpoint before connection probes if those probes must remain local.

A local memory endpoint does not make the entire agent offline. Hermes's answering model, the memory service's configured model providers, connectors and other tools can still make external requests. Verify those dependencies for the deployment you intend to run.

Follow the provider's setup steps and start with the cross-session test above. The useful result is a fact you can inspect, retrieve, correct and remove under the right scope.

Frequently asked questions

Does Hermes already have built-in memory?

Yes. Native memory files remain available alongside Supermemory's external provider. Check which source supplies context when testing recall.

Does every Hermes profile automatically get a separate Supermemory container?

No. The documented default is hermes. Use the supported identity template or another explicit configuration when separate containers are required.

Does a local memory endpoint make the whole agent offline?

No. Check the answering model, memory-service model configuration, connectors and tools as well as the memory endpoint.