> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Hermes Agent

SurrealDB Agent Memory as a memory provider for the Hermes Agent.

SurrealDB Agent Memory is a memory provider for the [Hermes Agent](https://github.com/NousResearch/hermes-agent). Once installed and selected, the agent recalls relevant memories before each turn, writes each completed turn back to SurrealDB Agent Memory asynchronously, and consolidates memory when a session ends. It also gains explicit memory tools it can call directly.

Package: **`agent-memory-hermes`** (PyPI). It pulls in the SurrealDB SDK (`surrealdb` v3, which bundles SurrealDB Agent Memory) and registers the plugin with Hermes through the `hermes_agent.plugins` entry point.

> [!NOTE]
> This is the hosted provider. For a persistent filesystem on a SurrealDB instance you run, with a toolset the agent calls directly, see the [SurrealDB filesystem integration for Hermes](/docs/build/integrations/ai-frameworks/hermes.md). Only one memory provider can be active at a time, so pick one.

## Requirements

- Python 3.10+
- A running Hermes Agent install
- SurrealDB Agent Memory access: endpoint, context, and API key

## Installation

```bash
pip install agent-memory-hermes
```

## Environment

**Bash**

```bash
export AGENT_MEMORY_API_KEY="..."
export AGENT_MEMORY_ENDPOINT="https://your-instance.agent-memory.dev"
export AGENT_MEMORY_CONTEXT="my-context"
```

**PowerShell**

```powershell
$env:AGENT_MEMORY_API_KEY = "..."
$env:AGENT_MEMORY_ENDPOINT = "https://your-instance.agent-memory.dev"
$env:AGENT_MEMORY_CONTEXT = "my-context"
```

## Activate

Select the provider. Hermes prompts for any missing settings and writes the non-secret ones to `$HERMES_HOME/agent-memory.json`:

```bash
hermes memory setup      # choose "agent_memory"
hermes memory status     # confirm it is active
hermes                   # run a session with Agent Memory-backed memory
```

## Configuration

| Setting | Env var | Default | Notes |
| --- | --- | --- | --- |
| `api_key` | `AGENT_MEMORY_API_KEY` | n/a | Secret, required (kept in `.env`) |
| `endpoint` | `AGENT_MEMORY_ENDPOINT` | n/a | Required, origin with no trailing slash |
| `context` | `AGENT_MEMORY_CONTEXT` | n/a | Required; a client is pinned to one context |
| `recall_mode` | `AGENT_MEMORY_RECALL_MODE` | `hybrid` | `hybrid`, `context`, or `tools` |
| `write_frequency` | `AGENT_MEMORY_WRITE_FREQUENCY` | `turn` | `turn` or `session` |
| `top_k` | `AGENT_MEMORY_TOP_K` | `5` | Memories recalled per turn |
| `default_scope` | `AGENT_MEMORY_DEFAULT_SCOPE` | n/a | For example `user/tobie`; scope for writes and lens for reads |

**Recall modes.** `hybrid` injects raw recalled memories before each turn; `context` injects a synthesised answer instead; `tools` injects nothing and lets the model recall explicitly with `agent_memory_recall` / `agent_memory_context`.

## Tools

| Tool | Purpose |
| --- | --- |
| `agent_memory_recall` | Search memory across semantic, lexical, graph, and temporal signals. |
| `agent_memory_remember` | Store a durable fact. |
| `agent_memory_context` | Return a synthesised answer from memory. |
| `agent_memory_forget` | Supersede (default) or hard-delete. |
| `agent_memory_reflect` | Derive insights, optionally persisting them. |
| `agent_memory_upload` | Ingest a document into knowledge memory. |

## Reliability

The provider is built not to destabilise the agent. Writes run on a background daemon thread, so turns never block on I/O. Every SurrealDB Agent Memory call is wrapped; failures are logged and degrade to empty results rather than raising into the agent loop (fail open). After repeated failures or an authentication error, a circuit breaker disables memory for the rest of the session.

## When to use MCP or the SDK instead

- For an MCP-native host, use the [MCP server](/docs/agent-memory/integrations/mcp-server/install.md).
- To call SurrealDB Agent Memory directly, use the [Python SDK](/docs/agent-memory/integrations/sdks/python.md).