Hermes

The hermes-supermemory plugin is the supermemory memory provider for Hermes agent: semantic long-term memory, profile recall, search, explicit memory tools, and per-turn conversation capture — not a bolt-on script the model might skip. It previously shipped inside Hermes core and is now maintained by Supermemory as a Hermes plugin. Hermes runs across Telegram, Discord, Slack, WhatsApp, Signal, and the CLI from one gateway. Hermes also ships with built-in MEMORY.md and USER.md files. Supermemory adds structure and isolation (profile-scoped and optional multi-container tags), plus retrieval that goes beyond a single flat file.

Get your API key

Create a supermemory API key from the API Keys page in the console. During hermes memory setup you can paste it when prompted, or persist it in your environment:

Install the memory provider

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

Hermes installs the plugin’s dependency, the supermemory Python SDK (>=5.0.0,<6), into its own environment. Select supermemory when prompted and paste your API key. Or set the provider and key manually:

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

(Adjust the path if your Hermes home directory differs.)

How it works

Once configured, the provider runs through Hermes’s normal memory lifecycle:

Prefetch — Relevant memory context can be loaded before each turn.
Turn capture — After each completed turn, the conversation is saved as one document per conversation, rewritten in full, so edits and context compaction never store it twice. Remaining turns are flushed at session end.
Explicit tools — Search, store, forget, profile, and read-document tools are available to the model when appropriate.
Built-in file memory — This does not replace MEMORY.md / USER.md; mirroring behavior depends on Hermes version and config (see upstream README).

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 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.
`supermemory-read-document`	`supermemory_read_document`	Read a stored document, such as a past conversation, by the `document_id` from search results.

Commands

Interactive setup: pick supermemory and enter your API key.

hermes memory setup

Environment variables

These variables configure the supermemory provider (for example in your shell or Hermes env file):

SUPERMEMORY_API_KEY=sm_...                   # Required
SUPERMEMORY_CONTAINER_TAG=hermes-work        # Optional: overrides container tag from config
SUPERMEMORY_BASE_URL=http://localhost:6767   # Optional: API endpoint when base_url is not set in config

Multi-container tags

By default, recall and capture use a single primary container_tag (optionally profile-scoped with {identity}). Multi-container mode adds extra named tags so the model can read and write specific namespaces — for example work vs personal, or one bucket per project. How to enable — In $HERMES_HOME/supermemory.json, set:

enable_custom_container_tags to true
custom_containers to an array of allowed tag strings (e.g. work, personal, project-alpha)
custom_container_instructions (recommended) — short guidance the provider injects into the system prompt so Hermes knows when to use which tag

Your primary container_tag stays the default namespace; listed custom tags are additional allowlisted namespaces. How it works

supermemory_search, supermemory_store, supermemory_forget, and supermemory_profile accept an optional container_tag argument. The tag must be either the primary container_tag (after template resolution) or one of custom_containers.
Automatic behavior (turn sync, prefetch, mirroring built-in memory writes, session-end ingest) always uses the primary container only — it does not pick a custom tag for you.
Instructions in custom_container_instructions steer the model toward passing the right container_tag on tool calls when the user’s intent matches a namespace (e.g. “check my personal notes” → personal).

Example:

{
  "container_tag": "hermes",
  "enable_custom_container_tags": true,
  "custom_containers": ["work", "personal", "shared-knowledge"],
  "custom_container_instructions": "Use work for job and coding context, personal for life and hobbies, shared-knowledge for facts that apply across both."
}

See the plugin README for the exact schema and any newer options.

Config file

Create or edit $HERMES_HOME/supermemory.json. Common keys:

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`	Tag for search/writes; use `{identity}` for profile-scoped tags (e.g. `hermes-{identity}` → `hermes-coder`).
`auto_recall`	`true`	Inject memory context before turns.
`auto_capture`	`true`	Store turns after each response.
`max_recall_results`	`10`	Max items merged into context.
`profile_frequency`	`50`	Profile on first turn and every N turns.
`capture_mode`	`all`	How aggressively turns are captured.
`search_mode`	`hybrid`	`hybrid`, `memories`, or `chunks` (`documents` is still accepted as an alias for `chunks`).
`entity_context`	built-in	Extraction guidance passed to Supermemory.
`dreaming`	`dynamic`	`dynamic` groups related conversations before forming memories; `instant` processes each one right away (billed as one extra operation).
`api_timeout`	`5.0`	SDK / ingest timeout (seconds).
`enable_custom_container_tags`	`false`	Set `true` to allow extra namespaces; see Multi-container tags above.
`custom_containers`	—	Allowlisted tags beyond the primary `container_tag`.
`custom_container_instructions`	—	Prompt text that explains when to pass `container_tag` on tools.

Example profile-scoped container:

{
  "container_tag": "hermes-{identity}",
  "search_mode": "hybrid",
  "auto_recall": true,
  "auto_capture": true
}

Self-hosted API

If you run your own supermemory API, start it with npx supermemory local and note the API key it prints on first boot. Before running hermes memory setup, set base_url in $HERMES_HOME/supermemory.json so the setup connection probe also stays local:

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

Then run hermes memory setup and enter the local server’s API key.

Next steps

Hermes plugin README

Full config table, env vars, and multi-container details.

OpenClaw plugin

Multi-platform memory for Telegram, WhatsApp, Discord, and more.

Questions about the API or product? Discord · support@supermemory.com · Developer docs

Supermemory MCP

Plugins

Get your API key

Install the memory provider

How it works

Tools

Commands

Environment variables

Multi-container tags

Config file

Self-hosted API

Next steps

Hermes plugin README

OpenClaw plugin

​Get your API key

​Install the memory provider

​How it works

​Tools

​Commands

​Environment variables

​Multi-container tags

​Config file

​Self-hosted API

​Next steps

Hermes plugin README

OpenClaw plugin

Get your API key

Install the memory provider

How it works

Tools

Commands

Environment variables

Multi-container tags

Config file

Self-hosted API

Next steps