Hermes Agent | Agent frameworks

SurrealDB Agent Memory is a memory provider for the 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. 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

pip install agent-memory-hermes

Environment

export AGENT_MEMORY_API_KEY="..."
export AGENT_MEMORY_ENDPOINT="https://your-instance.agent-memory.dev"
export 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:

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.
To call SurrealDB Agent Memory directly, use the Python SDK.