supermemory/apps/docs/integrations/hermes.mdx

---
title: "Hermes"
sidebarTitle: "Hermes"
description: "Supermemory plugin for Hermes. Semantic memory, profiles and search across Telegram, Discord, Slack, the CLI and more."
icon: "/images/hermes.svg"
---


The [hermes-supermemory](https://github.com/supermemoryai/hermes-supermemory) plugin is the **supermemory** memory provider for [Hermes agent](https://github.com/NousResearch/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](https://console.supermemory.ai/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

```bash
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:

```bash
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):

```bash
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:

```json
{
  "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](https://github.com/supermemoryai/hermes-supermemory) 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](#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:

```json
{
  "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:

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

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

## Next steps

<CardGroup cols={2}>
  <Card title="Hermes plugin README" icon="/images/github-icon.svg" href="https://github.com/supermemoryai/hermes-supermemory">
    Full config table, env vars, and multi-container details.
  </Card>

  <Card title="OpenClaw plugin" icon="/icons/hugeicons/message-02.svg" href="/integrations/openclaw">
    Multi-platform memory for Telegram, WhatsApp, Discord, and more.
  </Card>
</CardGroup>

Questions about the API or product? [Discord](https://supermemory.link/discord) · [support@supermemory.com](mailto:support@supermemory.com) · [Developer docs](/overview/what-is-supermemory)