AtomicMemory for Hermes Agent

AtomicMemory is a native Hermes memory provider. It participates in Hermes' memory lifecycle: background recall is prefetched for the next turn, completed turns are synced without blocking the chat loop, and the agent gets explicit tools for searching and storing durable facts.

By default, recall is shared across every AtomicMemory tool the user has touched (Claude Code, Codex, the web extension, etc.). Set memory_scope=siloed to restrict Hermes to Hermes-ingested memories only.

Architecture

Hermes Agent (Python)
  → $HERMES_HOME/plugins/atomicmemory/__init__.py
      → AtomicMemoryClient (Python protocol)
          → PythonSdkAtomicMemoryClient
              → published atomicmemory Python SDK MemoryClient

The Python provider owns Hermes lifecycle compatibility only — registration, hooks, tool schemas. Memory semantics flow through the published Python SDK.

Prerequisites

• Hermes Agent installed
• The AtomicMemory CLI (the install command below adds it if needed)
• An AtomicMemory Cloud project API key exported as ATOMICMEMORY_API_KEY

Install

Install the provider from the published npm package. The installer copies the Python provider files into Hermes' memory-provider directory; no repository clone is required.

curl --proto '=https' --tlsv1.2 -fsSL https://get.atomicstrata.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
npx -y @atomicmemory/hermes-plugin install
am init --cloud
am key create atomicmemory-hermes
export ATOMICMEMORY_API_KEY="<project-api-key-shown-once>"

With a project API key and no URL, the provider targets AtomicMemory Cloud (no local Core process or URL export). With neither set, it falls back to local Core at http://127.0.0.1:17350.

Then select and verify the provider:

hermes memory setup
# select "atomicmemory"
hermes memory status
# confirm "atomicmemory" is active

For source development, symlink the checkout instead:

cd /path/to/atomicmemory
mkdir -p "$HERMES_HOME/plugins"
ln -s "$(pwd)/plugins/hermes" "$HERMES_HOME/plugins/atomicmemory"

Config

Hermes' setup wizard prompts for a minimal pair (scope_user, memory_scope). Advanced settings live in $HERMES_HOME/atomicmemory.json.

Connection details (ATOMICMEMORY_API_URL, ATOMICMEMORY_API_KEY) flow through environment variables into the Python SDK. URL resolution: explicit URL, else Cloud when a key is set, else local Core. The Cloud project API key is required when Cloud is selected.

To use local Core, omit URL and key, or set them explicitly:

export ATOMICMEMORY_API_URL="http://127.0.0.1:17350"
export ATOMICMEMORY_API_KEY="local-dev-key"

ATOMICMEMORY_API_KEY may be omitted for the local Core URL; it defaults to local-dev-key.

If you previously exported ATOMICMEMORY_API_KEY=local-dev-key without a URL, set ATOMICMEMORY_API_URL=http://127.0.0.1:17350 as well: local-dev-key is the local Core key and is refused for Cloud origins, and Cloud hostnames are refused over plain http, so a project key is never sent in cleartext.

Environment

Env var	Purpose
ATOMICMEMORY_API_URL	AtomicMemory service URL. When unset: Cloud if ATOMICMEMORY_API_KEY is set, otherwise http://127.0.0.1:17350.
ATOMICMEMORY_API_KEY	Cloud project API key. Required for Cloud; use the configured Core key for local Core.
ATOMICMEMORY_PROVIDER	SDK provider name. Defaults to atomicmemory.
ATOMICMEMORY_SCOPE_USER	Hermes user identity. Defaults to $USER.
ATOMICMEMORY_MEMORY_SCOPE	shared (default) or siloed.
ATOMICMEMORY_MEMORY_MODE	hybrid (default), context, or tools.
ATOMICMEMORY_PREFETCH_ENABLED	true/false. Default true.
ATOMICMEMORY_PREFETCH_METHOD	context (default) or fast.
ATOMICMEMORY_SEARCH_LIMIT	Default search/list limit.
ATOMICMEMORY_TOKEN_BUDGET	Default context-package token budget.

Provider-local file

$HERMES_HOME/atomicmemory.json accepts these keys (all optional):

Key	Description
scope_user	User identity.
scope_agent	Hermes prompt label (does not change scoping).
memory_mode	hybrid / context / tools.
memory_scope	shared / siloed.
prefetch_enabled	bool.
prefetch_method	context / fast.
search_limit	int.
token_budget	int.

Secrets are never persisted here — api_key and api_url are deliberately not in the allowed key set.

Memory scope

Mode	Recall	Ingest
shared (default)	All AtomicMemory memories for the user	stamped source_site=hermes
siloed	Only Hermes-ingested memories	stamped source_site=hermes

The source_site filter on recall is enforced through the Python SDK's AtomicMemory namespace handle. If the SDK is configured against a non-AtomicMemory provider (e.g. mem0), siloed mode fails loudly with PROVIDER_UNSUPPORTED rather than silently dropping the filter.

Memory mode

memory_mode selects which Hermes surfaces AtomicMemory exposes:

Mode	Auto-recall + sync	Explicit tools
hybrid (default)	yes	yes
context	yes	hidden
tools	disabled	yes

Tools

Tool	Description
atomicmemory_search	Search AtomicMemory by meaning.
atomicmemory_context	Build an injection-ready context package.
atomicmemory_conclude	Store one explicit durable fact verbatim.
atomicmemory_profile	List recent records (description text varies by memory_scope).

Lifecycle

• queue_prefetch(query) searches AtomicMemory in a background thread, with a generation counter so a slow earlier prefetch can't overwrite a faster newer one.
• prefetch(query) returns the most recent completed recall, then clears the slot.
• sync_turn(user, assistant) enqueues the turn to a single-writer worker thread and returns immediately. The worker calls client.ingest_messages(...) with provenance.source = "hermes" and provenance.sourceUrl = "hermes://session/<session_id>".
• on_session_end(messages) drains the worker, then closes the SDK client.

Reliability

A circuit breaker pauses SDK calls for two minutes after five consecutive failures and resets on the next success. Hermes continues to run while AtomicMemory is temporarily unavailable.

Troubleshooting

Symptom	Likely cause
Provider does not appear in hermes memory setup	Wrong install path. User-installed memory providers must live directly under $HERMES_HOME/plugins/<name>/ (the plugins/memory/ layout is for providers bundled inside hermes-agent itself).
is_available() returns False	ATOMICMEMORY_API_KEY is unset on the Cloud path, or the Hermes Python environment did not install the atomicmemory dependency from plugin.yaml.
Import fails at startup	The Hermes Python environment is missing the SDK dependency from plugin.yaml.
Calls fail with PROVIDER_UNSUPPORTED while memory_scope=siloed	The configured SDK provider is not the AtomicMemory core (e.g. it's mem0). Either switch ATOMICMEMORY_PROVIDER=atomicmemory or move to memory_scope=shared.

Tests

# Python provider and SDK adapter (deterministic, no network)
python3 -m unittest discover plugins/hermes/tests