hermes-agent/plugins/memory/supermemory

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

• The supermemory SDK, prepared through PM by hermes memory setup when you select Supermemory. Restart Hermes after preparation; do not install into its selected environment with pip.
• Hosted: API key from app.supermemory.ai/integrations?connect=hermes
• Self-hosted: a running Supermemory local server and the API key it prints on first boot

Setup

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

Support

• Supermemory Discord
• support@supermemory.com
• supermemory.ai