Handoff repository. This is the standalone copy of the supermemory memory provider formerly bundled with Hermes Agent, published so its upstream maintainers can take it over. Not an official Nous Research plugin. See HANDOFF.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 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