The Supermemory memory provider for Hermes Agent, maintained by Supermemory. It was previously bundled inside Hermes core. See MAINTAINERS.md.

Supermemory Memory Provider

Semantic long-term memory with profile recall, semantic search, explicit memory tools, and per-turn conversation capture into one document per session per 4-hour window for richer profiles.

Requirements

pip install supermemory
Hosted: API key from console.supermemory.ai/keys
Self-hosted: a running Supermemory local server and the API key it prints on first boot

Setup

hermes plugins install supermemoryai/hermes-supermemory
hermes plugins enable supermemory
hermes memory setup    # select "supermemory"

Or manually:

hermes config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env

For a fully self-hosted setup, start Supermemory local and note the API key it prints on first boot:

npx supermemory local

Before running hermes memory setup, add the local endpoint to $HERMES_HOME/supermemory.json:

{
  "base_url": "http://localhost:6767"
}

Then run hermes memory setup and enter the local server's API key. Configuring the endpoint first ensures the setup connection probe also stays local.

Config

Config file: $HERMES_HOME/supermemory.json

Key	Default	Description
`base_url`	`https://api.supermemory.ai`	API endpoint for hosted or self-hosted Supermemory. Takes priority over `SUPERMEMORY_BASE_URL`.
`container_tag`	`hermes`	Container tag used for search and writes. Supports `{identity}` template for profile-scoped tags (e.g. `hermes-{identity}` → `hermes-coder`).
`auto_recall`	`true`	Inject relevant memory context before turns
`auto_capture`	`true`	Store cleaned user-assistant turns after each response
`max_recall_results`	`10`	Max recalled items to format into context
`profile_frequency`	`50`	Include profile facts on first turn and every N turns
`capture_mode`	`all`	Skip tiny or trivial turns by default
`search_mode`	`hybrid`	Search mode: `hybrid` (profile + memories), `memories` (memories only), `documents` (documents only)
`entity_context`	built-in default	Extraction guidance passed to Supermemory
`api_timeout`	`5.0`	Timeout for SDK requests

Environment Variables

Variable	Description
`SUPERMEMORY_API_KEY`	API key (required)
`SUPERMEMORY_BASE_URL`	Compatibility fallback for the API endpoint when `base_url` is not configured
`SUPERMEMORY_CONTAINER_TAG`	Override container tag (takes priority over config file)

Base URL precedence is supermemory.json → SUPERMEMORY_BASE_URL → https://api.supermemory.ai. Hermes resolves it once and uses the same endpoint for SDK operations and setup/status probes.

Tools

Kebab-case names are registered for the agent; snake_case aliases remain supported.

Tool	Alias	Description
`supermemory-save`	`supermemory_store`	Store an explicit memory
`supermemory-search`	`supermemory_search`	Search memories by semantic similarity
`supermemory-forget`	`supermemory_forget`	Forget a memory by ID or best-match query
`supermemory-profile`	`supermemory_profile`	Retrieve persistent profile and recent context

Source attribution

All Supermemory API calls send x-sm-source: hermes, and document writes stamp metadata.sm_source: hermes. This is a functional routing key, not telemetry: it groups Hermes-written memories into a dedicated "Hermes" Space in the Supermemory app, so you can filter, browse, and bulk-manage them per source agent (alongside Codex, Claude Code, etc.) from the Supermemory UI.

Behavior

When enabled, Hermes can:

prefetch relevant memory context before each turn
write each completed user/assistant turn to one document per session per 4-hour window (customId = <session>_<date>_b<0-5>, so the API appends deltas), matching the capture shape of the other Supermemory agent integrations
retry failed turn writes on the next turn, session end, /reset, or shutdown (at-least-once: if the API accepted a write but the response was lost, the same turn is appended again)
route every SDK and probe request through the configured hosted or self-hosted endpoint
expose explicit tools for search, store, forget, and profile access

Profile-Scoped Containers

Use {identity} in the container_tag to scope memories per Hermes profile:

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

For a profile named coder, this resolves to hermes-coder. The default profile resolves to hermes-default. Without {identity}, all profiles share the same container.

Multi-Container Mode

For advanced setups (e.g. OpenClaw-style multi-workspace), you can enable custom container tags so the agent can read/write across multiple named containers:

{
  "container_tag": "hermes",
  "enable_custom_container_tags": true,
  "custom_containers": ["project-alpha", "project-beta", "shared-knowledge"],
  "custom_container_instructions": "Use project-alpha for coding tasks, project-beta for research, and shared-knowledge for team-wide facts."
}

When enabled:

supermemory-search, supermemory-save, supermemory-forget, and supermemory-profile accept an optional container_tag parameter
The tag must be in the whitelist: primary container + custom_containers
Automatic operations (turn capture, prefetch, memory write mirroring) always use the primary container only
Custom container instructions are injected into the system prompt

supermemory

What it adds

Environment variables it needs 1

README