Hermes Agent | Spectron

Spectron 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 Spectron asynchronously, and consolidates memory when a session ends. It also gains explicit memory tools it can call directly.

Package: spectron-hermes-agent (PyPI). It pulls in the Spectron SDK (surrealdb[spectron]) and registers the plugin with Hermes through the hermes_agent.plugins entry point.

Requirements

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

Installation

pip install spectron-hermes-agent

Environment

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:

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 Spectron 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 Spectron directly, use the Python SDK.