# Hermes native memory provider

Source: https://docs.rushdb.com/connect/hermes-memory/

`rushdb-hermes-memory` implements Hermes Agent's native `MemoryProvider` contract. It performs automatic recall before inference and persists completed turns without requiring the model to call an MCP tool.

The MCP integration remains useful for explicit database operations, but it is not a replacement for provider lifecycle hooks such as `prefetch`, `sync_turn`, `on_pre_compress`, and `on_session_end`.

## Install

```bash
pip install rushdb-hermes-memory
hermes memory setup
```

The package registers the `rushdb` provider through the official entry-point group:

```toml
[project.entry-points."hermes_agent.memory_providers"]
rushdb = "rushdb_hermes_memory:register"
```

Requires Python 3.11–3.13, installed into the same environment as Hermes Agent.

### RushDB Cloud

```bash
export RUSHDB_API_KEY=your-project-api-key
# Optional: a different RushDB Cloud API endpoint
# export RUSHDB_API_URL=https://api.rushdb.com/api/v1
```

### A self-hosted RushDB engine

Recall is a vector search. RushDB Cloud embeds memories for you; a self-hosted engine does not, so the provider embeds them itself through an OpenAI-compatible embeddings endpoint:

```bash
export RUSHDB_ENGINE_URL="http://127.0.0.1:3000"
export RUSHDB_ENGINE_TOKEN="your-engine-token"
# export RUSHDB_ENGINE_SCOPE="tenant-1"   # only for an engine started with --multitenant
export RUSHDB_EMBEDDING_API_KEY="sk-..."
export RUSHDB_EMBEDDING_MODEL="text-embedding-3-small"
export RUSHDB_EMBEDDING_DIMENSIONS="1536"
# export RUSHDB_EMBEDDING_BASE_URL="https://api.openai.com/v1"
```

On start the provider creates the external vector indexes it needs; every memory is written with its vector, and recall searches with the embedded query. With RushDB Cloud the embedding settings are optional. When the configuration is incomplete, `hermes memory status` reports what is missing.

In either mode, set a salt so participant hashes can't be correlated across deployments:

```bash
export RUSHDB_MEMORY_SCOPE_SALT=a-long-random-secret
```

## Lifecycle behavior

| Hermes method                 | RushDB behavior                                                               |
| ----------------------------- | ----------------------------------------------------------------------------- |
| `prefetch`                    | Time-budgeted `EPISODE.summary` and active `MEMORY_FACT.text` semantic recall |
| `queue_prefetch`              | Background next-turn cache warmup                                             |
| `sync_turn`                   | Profile-local durable enqueue; no network wait on the conversation path       |
| `on_pre_compress`             | Queue the latest bounded conversational episode before compression            |
| `on_memory_write`             | Mirror explicit add/replace operations as active memory facts                 |
| `on_session_switch`           | Rotate session identity and clear stale prefetch state                        |
| `on_session_end` / `shutdown` | Bounded writer flush                                                          |

The provider stores its outbox under the active `HERMES_HOME/rushdb-memory/outbox`, preserving Hermes profile isolation. Failed writes stay in that directory and replay when the provider starts again.

Only bounded user and assistant text leaves the device automatically. The optional `messages` argument, tool calls, command output, and complete transcripts are deliberately ignored.

## Scope and degraded operation

Recall always filters on the Hermes agent/profile identity, privacy scope, a salted participant hash, and sandbox eligibility before semantic ranking. Non-primary contexts such as subagents and cron/flush agents do not write memory.

RushDB timeouts or errors produce empty/degraded recall rather than a failed Hermes turn. Recent locally queued episodes remain eligible for lexical fallback while embeddings are pending.

## Verify

```bash
hermes memory setup
```

Then complete a turn, end the session, and confirm that exactly one `EPISODE` exists for its deterministic `eventId`. Repeat the same event to validate idempotent upsert behavior, and test with RushDB temporarily offline to confirm the conversation remains available.
