Hermes Agent Memory with Supermemory

Hermes has built-in memory files and can use Supermemory as a native memory provider. 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 upstream provider documentation for your installed Hermes version. Provider behavior can change independently of the Supermemory API.

Install and configure

With Hermes installed, run:

pip install supermemory
hermes memory setup

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 coding plugin is free to use; 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 upstream implementation captures completed user/assistant turns when enabled. It groups writes by session and a four-hour window and retries pending writes on later lifecycle events. Session-end handling retries pending work.

Retries are at-least-once: if a write succeeds but its response is lost, resubmission can append the turn again. A prolonged outage can also exceed the bounded retry buffer. Inspect results rather than assuming automatic capture means nothing can be lost or duplicated.

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 and profile operations through supermemory-save, supermemory-search, supermemory-forget and supermemory-profile, 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 Hermes integration guide 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.