# 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: **`spectron-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.

## Requirements

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

## Installation

```bash
pip install spectron-hermes
```

## Environment

```bash
export SPECTRON_API_KEY="..."
export SPECTRON_ENDPOINT="https://your-instance.spectron.dev"
export SPECTRON_CONTEXT="my-context"
```

## Activate

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

```bash
hermes memory setup      # choose "spectron"
hermes memory status     # confirm it is active
hermes                   # run a session with Spectron-backed memory
```

## Configuration

| Setting | Env var | Default | Notes |
| --- | --- | --- | --- |
| `api_key` | `SPECTRON_API_KEY` | n/a | Secret, required (kept in `.env`) |
| `endpoint` | `SPECTRON_ENDPOINT` | n/a | Required, origin with no trailing slash |
| `context` | `SPECTRON_CONTEXT` | n/a | Required; a client is pinned to one context |
| `recall_mode` | `SPECTRON_RECALL_MODE` | `hybrid` | `hybrid`, `context`, or `tools` |
| `write_frequency` | `SPECTRON_WRITE_FREQUENCY` | `turn` | `turn` or `session` |
| `top_k` | `SPECTRON_TOP_K` | `5` | Memories recalled per turn |
| `default_scope` | `SPECTRON_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 `spectron_recall` / `spectron_context`.

## Tools

| Tool | Purpose |
| --- | --- |
| `spectron_recall` | Search memory across semantic, lexical, graph, and temporal signals. |
| `spectron_remember` | Store a durable fact. |
| `spectron_context` | Return a synthesised answer from memory. |
| `spectron_forget` | Supersede (default) or hard-delete. |
| `spectron_reflect` | Derive insights, optionally persisting them. |
| `spectron_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).