RepoNous ResearchNous Researchpublished Sep 17, 2026seen Sep 18

NousResearch/hermes-plugin-supermemory

Python

Open original ↗

Captured source

source ↗
GH
GitHub/github.com/NousResearch/hermes-plugin-supermemory
NousResearch/hermes-plugin-supermemory repository metadata
Source ↗
published Sep 17, 2026seen Sep 18captured Sep 18http 200method plain

NousResearch/hermes-plugin-supermemory

Description: Handoff: standalone Hermes memory provider plugin (supermemory). Supermemory semantic long-term memory with profile recall, semantic search, explicit memory tools, and per-tur

Language: Python

License: MIT

Stars: 1

Forks: 1

Open issues: 0

Created: 2026-09-17T16:02:27Z

Pushed: 2026-09-17T16:02:30Z

Default branch: main

Fork: no

Archived: no

README: > 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](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

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 = __b, 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