All plugins

supermemory

Supermemory semantic long-term memory provider — profile recall, semantic search, explicit memory tools, and per-turn conversation capture. Maintained by Supermemory; the same provider that shipped in-tree.

supermemoryai9Memoryv1.0.1Updated 1 month ago

About

Supermemory semantic long-term memory provider — profile recall, semantic search, explicit memory tools, and per-turn conversation capture. Maintained by Supermemory; the same provider that shipped in-tree.

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

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

Support

README from the reviewed commit 91405dd; it updates when the author re-pins.