> ## Documentation Index
> Fetch the complete documentation index at: https://mem0-feature-hermes-standalone-migration.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Add persistent memory to Hermes Agent with Mem0 Cloud, a self-hosted server, or the in-process OSS SDK.

Add long-term memory to [Hermes Agent](https://github.com/NousResearch/hermes-agent), a self-improving AI agent CLI by Nous Research. The [standalone Mem0 plugin](https://github.com/mem0ai/mem0/tree/main/integrations/hermes-plugin-mem0) learns facts from conversations and recalls relevant memories for the current question.

You can run Mem0 in three ways:

* **Platform mode** (default): managed Mem0 Cloud. Add your API key and you are ready.
* **Self-hosted server mode**: point the plugin at a Mem0 server you run yourself (the Docker-shipped server). The plugin only talks HTTP to your server.
* **OSS mode**: run Mem0 in-process with your own LLM, embedder, and vector store. No Mem0 server required.

## How It Works

Hermes runs a built-in memory system (file-based `MEMORY.md` and `USER.md`) alongside one external provider. When Mem0 is active, it works additively with the built-in system at two points in every conversation turn.

### 1. Current-turn recall (bounded wait)

When you send a message, Hermes searches your stored memories for the current question and waits up to 3 seconds for results. If they arrive in time, they are injected into the system prompt so the model can see them. If the backend is slower, Hermes skips the injection and the model can still call `mem0_search` itself after the bounded recall wait.

### 2. Background fact extraction (sync)

Once the model finishes, the plugin sends the user message and assistant response to Mem0 in a background thread for fact extraction. Each write includes the agent identifier and gateway channel.

<Note>
  Automatic capture truncates each message to **450 characters by default in every mode**, preferring a sentence boundary. Adjust `sync_max_chars` for your model's context limit. Capture is best effort: if the previous sync is still running after a five-second wait, the next turn is skipped. Use `mem0_add` to store specific text verbatim.
</Note>

## Agent Tools

When Mem0 is active, the model gets four tools it can call during a conversation:

| Tool          | Description                                     | Parameters                                                                                                   |
| ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `mem0_search` | Semantic search by meaning, ranked by relevance | `query` (required), `top_k` (default 10, max 50), `rerank` (uses the configured default, Platform mode only) |
| `mem0_add`    | Store a fact verbatim, with no LLM extraction   | `content` (required)                                                                                         |
| `mem0_update` | Update a memory's text by ID                    | `memory_id`, `text` (both required)                                                                          |
| `mem0_delete` | Delete a memory by ID                           | `memory_id` (required)                                                                                       |

## Installation

Install [Hermes Agent](https://github.com/NousResearch/hermes-agent) with memory-provider plugin support and Python 3.11 or later. Once the plugin directory is available on Mem0's main branch, install it from the repository subdirectory:

```bash theme={null}
hermes plugins install mem0ai/mem0/integrations/hermes-plugin-mem0
hermes plugins enable mem0
hermes memory setup
hermes memory status
```

Select **mem0** in setup and choose one of the modes below. Start a fresh Hermes conversation after setup.

Hermes installers with plugin dependency support install `mem0ai>=2.0.10,<3` and `httpx>=0.27,<1` from the plugin's `pyproject.toml`. Older hosts such as Hermes v0.21.3 require those packages to be installed explicitly into the Hermes Python environment. The OSS setup flow installs additional provider packages as needed.

<Note>
  Hermes versions that still bundle Mem0 prefer the bundled provider. The standalone copy takes over after the bundled copy is removed. Existing users should keep their current configuration; see [Migration for existing users](#migration-for-existing-users).
</Note>

## Platform Setup

Platform mode uses managed Mem0 Cloud and is the fastest way to start.

### Option 1: Interactive wizard (recommended)

```bash theme={null}
hermes memory setup
```

Select **mem0**, choose **Platform**, and paste your API key when prompted. The wizard writes settings to `$HERMES_HOME/mem0.json` and keeps the key in that profile's `.env`. The default Hermes home is `~/.hermes`; named profiles use their own home directory.

<Note>Get your API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-hermes">app.mem0.ai</a>.</Note>

### Option 2: Manual Configuration

```bash theme={null}
hermes config set memory.provider mem0
```

Add your key to the active Hermes profile's `.env`:

```dotenv theme={null}
MEM0_API_KEY=your-api-key
```

This sets `memory.provider: mem0` in the profile's `config.yaml`. Restart Hermes and check `hermes memory status`.

## Self-Hosted Server Setup

Run the [Mem0 server](https://github.com/mem0ai/mem0/tree/main/server) (FastAPI + pgvector) from its Docker image and point the plugin at it. Unlike OSS mode, the plugin just talks HTTP to your server.

### Interactive

```bash theme={null}
hermes memory setup
# Select "mem0", then "Self-hosted server", and enter the server URL
```

### With flags

```bash theme={null}
hermes memory setup mem0 --mode selfhosted \
  --host http://localhost:8888 \
  --api-key your-admin-api-key
```

### With environment variables

Set these values in the active profile's `.env` and select `mem0` with `hermes config set memory.provider mem0`:

```dotenv theme={null}
MEM0_HOST=http://localhost:8888
MEM0_API_KEY=your-admin-api-key
```

Non-empty settings in `mem0.json` override environment defaults. If switching from another mode, use the wizard to update that file too.

Then start a fresh Hermes session and call `mem0_search` — it connects to your server. The plugin authenticates with `X-API-Key` and uses the server's `/search` and `/memories` routes. The API key is optional only for servers running with `AUTH_DISABLED`.

<Note>Setting `host` routes to the self-hosted server automatically. Don't combine it with `mode: oss` — OSS takes precedence and ignores `host`.</Note>

## OSS (Self-Hosted) Setup

OSS mode runs the Mem0 SDK in the Hermes process with your chosen LLM, embedder, and vector store. It does not use Mem0 Cloud or require a Mem0 API key. Data goes to the model services you configure; use local Ollama models and local storage for a fully local setup.

### Interactive

```bash theme={null}
hermes memory setup
# Select "mem0", then "Open Source (self-hosted)"
# Follow the prompts for LLM, embedder, and vector store
```

### With flags

```bash theme={null}
hermes memory setup mem0 --mode oss \
  --oss-llm openai --oss-llm-key sk-... \
  --oss-vector qdrant
```

### Supported providers

| Component    | Providers                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------- |
| LLM          | `openai` (default model `gpt-5-mini`), `ollama` (local, default `llama3.1:8b`)            |
| Embedder     | `openai` (default `text-embedding-3-small`), `ollama` (local, default `nomic-embed-text`) |
| Vector store | `qdrant` (local path or server), `pgvector`                                               |

### Flag reference

| Flag                                                                | Description                                                                 |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `--mode`                                                            | `platform`, `selfhosted`, or `oss`                                          |
| `--api-key`                                                         | Platform API key, or the admin key of a self-hosted server                  |
| `--host`                                                            | Self-hosted server URL (with `--mode selfhosted`)                           |
| `--oss-llm`                                                         | LLM provider (`openai` or `ollama`, default `openai`)                       |
| `--oss-llm-key`                                                     | LLM API key (for `openai`)                                                  |
| `--oss-llm-model`                                                   | Override the LLM model                                                      |
| `--oss-llm-url`                                                     | LLM base URL (for `ollama` or a custom endpoint)                            |
| `--oss-embedder`                                                    | Embedder provider (default `openai`)                                        |
| `--oss-embedder-key`                                                | Embedder API key                                                            |
| `--oss-embedder-model`                                              | Override the embedder model                                                 |
| `--oss-embedder-url`                                                | Embedder base URL (for `ollama` or a custom endpoint)                       |
| `--oss-vector`                                                      | Vector store (`qdrant` or `pgvector`, default `qdrant`)                     |
| `--oss-vector-path`                                                 | Local Qdrant storage path                                                   |
| `--oss-vector-url`                                                  | Qdrant server URL                                                           |
| `--oss-vector-host`, `--oss-vector-port`                            | PGVector host and port (use `--oss-vector-url` for a Qdrant server)         |
| `--oss-vector-user`, `--oss-vector-password`, `--oss-vector-dbname` | PGVector connection details                                                 |
| `--user-id`                                                         | User identifier for Platform, OSS, or server setup                          |
| `--dry-run`                                                         | Preview configuration without saving it; setup may still check connectivity |

## Switching Modes

You can move between the three modes at any time. Run the setup command again, or edit `$HERMES_HOME/mem0.json` directly. Switching backends does not transfer memories between them. When returning to Platform, also remove any stale `MEM0_HOST` setting from your environment and profile `.env`.

```bash theme={null}
# Platform to OSS
hermes memory setup mem0 --mode oss --oss-llm-key sk-...

# OSS to Platform
hermes memory setup mem0 --mode platform --api-key sk-...

# Platform to a self-hosted server
hermes memory setup mem0 --mode selfhosted --host http://localhost:8888

# Preview without saving configuration
hermes memory setup mem0 --mode oss --oss-llm-key sk-... --dry-run
```

An OSS configuration in `$HERMES_HOME/mem0.json` can look like this (use your existing storage path when migrating):

```json theme={null}
{
  "mode": "oss",
  "oss": {
    "llm": {"provider": "openai", "config": {"model": "gpt-5-mini", "is_reasoning_model": true}},
    "embedder": {"provider": "openai", "config": {"model": "text-embedding-3-small"}},
    "vector_store": {"provider": "qdrant", "config": {"path": "~/.hermes/mem0_qdrant"}}
  }
}
```

## Configuration

Settings live in `$HERMES_HOME/mem0.json` and are written by `hermes memory setup`. API keys normally live in that profile's `.env`; distinct OpenAI LLM/embedder keys and database credentials are stored in the OSS configuration. Setup writes these files atomically with owner-only permissions.

`MEM0_MODE`, `MEM0_HOST`, `MEM0_USER_ID`, and `MEM0_AGENT_ID` supply environment defaults. Non-empty values in `mem0.json` take precedence. `MEM0_API_KEY` supplies the Cloud or server key unless `api_key` is set in the file.

| Key              | Default                             | Description                                                                                               |
| ---------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `mode`           | `platform`                          | `platform` (Mem0 Cloud) or `oss` (self-managed, in-process). Self-hosted server routing is set via `host` |
| `host`           | none                                | Self-hosted Mem0 server URL. When set, the plugin talks HTTP to your server instead of the cloud          |
| `api_key`        | none                                | Mem0 Platform API key, or the admin key of a self-hosted server. Stored in `.env` as `MEM0_API_KEY`       |
| `user_id`        | gateway user ID, then `hermes-user` | Identifier that scopes memories. See cross-channel behavior below                                         |
| `agent_id`       | `hermes`                            | Agent identifier attached to writes                                                                       |
| `rerank`         | `false`                             | Platform reranking for recall and tool searches that omit `rerank`                                        |
| `sync_max_chars` | `450`                               | Per-message character cap for automatic fact extraction in every mode                                     |
| `oss`            | `{}`                                | OSS LLM, embedder, and vector-store configuration                                                         |

### Cross-channel memories

Hermes can run from the CLI and from gateways like Telegram, Slack, and Discord. The `user_id` setting controls how memories are scoped across them:

* **Set a `user_id` other than `hermes-user`** and it applies to every gateway, so one person gets a single merged memory store no matter where they talk to the agent.
* **Leave it unset** (or at the default `hermes-user`) and each gateway uses its own native ID when available, falling back to `hermes-user`.

Every write is tagged with `metadata.channel` (for example `telegram` or `cli`). Plugin searches filter by user identity across sessions; they do not restrict recall to the current channel or session.

## Migration for Existing Users

Keep `memory.provider: mem0`, `mem0.json`, `MEM0_*` settings, user identity, and OSS database paths unchanged. Moving from the bundled provider to this standalone plugin does not require rerunning setup or moving stored memories.

Automatic migration depends on Hermes rollout as well as this repository:

1. Users need a Hermes build containing [PR #114569](https://github.com/NousResearch/hermes-agent/pull/114569).
2. Hermes maintainers must approve a catalog entry named `mem0` with `repo: https://github.com/mem0ai/mem0`, `subdir: integrations/hermes-plugin-mem0`, and a reviewed full commit SHA.
3. The bundled Mem0 provider must be removed so the standalone provider can load.

With these in place, Hermes installs a missing configured provider during `hermes update` across profiles or at agent startup. Startup installation respects `security.allow_lazy_installs`. Offline or disabled installation needs manual action; merging the plugin directory alone does not complete automatic migration.

CLI setup and status are supported. This plugin does not ship a Desktop configuration panel or provider-specific CLI commands.

## Reliability

* **Circuit breaker**: five consecutive backend failures pause calls for two minutes. The agent can continue without memory during that window. Expected update/delete errors such as a missing memory do not trip the breaker.
* **Bounded waits**: recall waits up to three seconds. Capture runs in the background, but an overlapping turn may wait up to five seconds for the previous sync before being skipped.
* **Best-effort capture**: there is no durable queue. Shutdown waits briefly for workers; pending writes are not guaranteed to finish before exit.
* **OSS data protection**: an embedding dimension mismatch fails initialization without deleting the existing collection or table.

## Troubleshooting

### "Mem0 temporarily unavailable"

The circuit breaker tripped after five consecutive failures and resets after two minutes.

* **Platform mode**: check your API key and internet connection.
* **Self-hosted server mode**: check that the server is running and reachable at the configured `host` URL.
* **OSS mode**: make sure your vector store (Qdrant or PGVector) is running and reachable.

### OSS: vector store connection refused

```bash theme={null}
# Local Qdrant: confirm the storage path is writable
ls -la ~/.hermes/mem0_qdrant

# Qdrant server: confirm it is reachable
curl http://localhost:6333/healthz

# PGVector: confirm PostgreSQL is accepting connections
pg_isready -h localhost -p 5432
```

### OSS: Ollama not reachable

```bash theme={null}
curl http://localhost:11434/api/tags
```

### Memories not appearing

* `mem0_add` stores text verbatim with no extraction. Ordinary conversation turns are extracted automatically by the background sync.
* Search is semantic, so try a broader query.
* Confirm `user_id` is the same across sessions (check `$HERMES_HOME/mem0.json`).
* Check `sync_max_chars`: facts beyond the per-message limit are not sent for extraction.

### OSS: embedding dimension mismatch

Restore the embedding model and dimensions that created the existing collection, or choose a new collection and migrate data explicitly. The plugin leaves the original collection intact when dimensions differ.

<CardGroup cols={2}>
  <Card title="OpenClaw Integration" icon="https://mintcdn.com/mem0-feature-hermes-standalone-migration/KlqdVHJghJddWMyM/images/provider-icons/openclaw.svg?fit=max&auto=format&n=KlqdVHJghJddWMyM&q=85&s=b621ca85206a13e9312a9d226b54001d" href="/integrations/openclaw" width="24" height="24" data-path="images/provider-icons/openclaw.svg">
    Add memory to OpenClaw agents with auto-recall and auto-capture
  </Card>

  <Card title="Mem0 Platform" icon="rocket" href="/platform/overview">
    Get your API key and explore the Mem0 dashboard
  </Card>
</CardGroup>

<Snippet file="star-on-github.mdx" />