Skip to main content
The AtomicMemory Hermes plugin registers AtomicMemory as a first-class native memory provider within Hermes Agent. Once installed, Hermes automatically prefetches relevant memories in the background before each turn, syncs completed turns without blocking the chat loop, and exposes explicit tools for the agent to search and store durable facts. By default, recall draws from all memories you have created across every AtomicMemory-enabled tool — Claude Code, Codex, the web extension, and more. You can narrow this to Hermes-only memories when you prefer a siloed context.

​
Prerequisites

Before installing the plugin, make sure you have:
  • Hermes Agent installed and available on your PATH
  • ATOMICMEMORY_API_URL exported in your shell pointing to a running AtomicMemory core
  • ATOMICMEMORY_API_KEY exported if your core requires authentication (the Core Quickstart service does)

​
Install

1

Run the plugin installer

Install the provider from the published npm package. The installer copies the Python provider files into Hermes’ memory-provider directory — no repository clone required.
npx -y @atomicmemory/hermes-plugin install
2

Export connection variables

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

Select the provider

Run the Hermes memory setup wizard and select atomicmemory when prompted:
hermes memory setup
# select "atomicmemory" from the list
4

Confirm the provider is active

hermes memory status
# expected output: atomicmemory — active
For source development, symlink your local checkout instead of running the npm installer:
mkdir -p "$HERMES_HOME/plugins"
ln -s "$(pwd)/plugins/hermes" "$HERMES_HOME/plugins/atomicmemory"

​
Configuration

Hermes’ setup wizard prompts for the two most important settings (scope_user and memory_scope). All advanced settings can be set through environment variables or the provider-local config file at $HERMES_HOME/atomicmemory.json.

​
Environment variables

VariablePurposeDefault
ATOMICMEMORY_API_URLAtomicMemory core URLRequired
ATOMICMEMORY_API_KEYBearer credential for authenticated cores—
ATOMICMEMORY_PROVIDERMemory backend nameatomicmemory
ATOMICMEMORY_SCOPE_USERUser identity for memory scoping$USER
ATOMICMEMORY_MEMORY_SCOPEshared or siloedshared
ATOMICMEMORY_MEMORY_MODEhybrid, context, or toolshybrid
ATOMICMEMORY_PREFETCH_ENABLEDEnable background prefetch before each turntrue
ATOMICMEMORY_PREFETCH_METHODPrefetch strategy: context (full package) or fast (keyword search)context
ATOMICMEMORY_SEARCH_LIMITDefault result count for search and list operations—
ATOMICMEMORY_TOKEN_BUDGETContext-package token budget—
The provider does not have a default API URL. If ATOMICMEMORY_API_URL is unset, the provider fails to start. Always export it before running Hermes.

​
Provider-local config file

The $HERMES_HOME/atomicmemory.json file accepts the same keys as environment variables, for settings you want to persist across shell sessions: 
{
  "scope_user": "alice",
  "scope_agent": "hermes",
  "memory_scope": "shared",
  "memory_mode": "hybrid",
  "prefetch_enabled": true,
  "prefetch_method": "context",
  "search_limit": 10,
  "token_budget": 2000
}
Secrets are never persisted in this file. api_key and api_url are deliberately excluded from the allowed key set — always pass them through environment variables.

​
Memory scope

ATOMICMEMORY_MEMORY_SCOPE controls which memories Hermes can recall:
ScopeRecallIngest
shared (default)All AtomicMemory memories for the user, across all toolsStamped with source_site=hermes
siloedOnly memories ingested by HermesStamped with source_site=hermes
Use shared when you want Hermes to benefit from context gathered in Claude Code, Codex, or other AtomicMemory tools. Use siloed when you want a strictly Hermes-only memory context — for example, when running multiple agents with separate knowledge domains.
siloed mode requires ATOMICMEMORY_PROVIDER=atomicmemory. If the SDK is configured against a different provider (e.g. mem0), siloed mode fails loudly with PROVIDER_UNSUPPORTED rather than silently dropping the filter. Switch to memory_scope=shared or set ATOMICMEMORY_PROVIDER=atomicmemory to resolve this.

​
Memory mode

ATOMICMEMORY_MEMORY_MODE controls which Hermes memory surfaces AtomicMemory exposes:
ModeAuto-recall + turn syncExplicit tools
hybrid (default)EnabledVisible
contextEnabledHidden
toolsDisabledVisible
  • hybrid gives the agent both automatic background recall and on-demand tool access — the recommended mode for most workflows.
  • context keeps recall transparent to the agent; use this when you want memories injected into context without the agent being aware of the mechanism.
  • tools disables automatic recall and relies entirely on the agent calling tools explicitly; useful when you want full agent control over when memory is accessed.

​
Available tools

When memory_mode is hybrid or tools, the agent has access to four explicit tools:
ToolDescription
atomicmemory_searchSearch AtomicMemory by semantic meaning
atomicmemory_contextBuild an injection-ready context package for the current turn
atomicmemory_concludeStore one explicit durable fact verbatim
atomicmemory_profileList recent memory records (description reflects current memory_scope)

​
Lifecycle and reliability

The provider integrates deeply with Hermes’ turn lifecycle:

Background prefetch

queue_prefetch(query) searches AtomicMemory in a background thread before the next turn. A generation counter ensures a slow earlier prefetch cannot overwrite a faster newer one.

Non-blocking turn sync

sync_turn(user, assistant) enqueues the completed turn to a single-writer worker thread and returns immediately, so AtomicMemory writes never block the chat loop.

Circuit breaker

After 5 consecutive failures, the circuit breaker pauses all SDK calls for 2 minutes. Hermes continues to run normally while AtomicMemory is temporarily unavailable. The breaker resets automatically on the next successful call.

Session drain

on_session_end(messages) drains the worker queue before closing the SDK client, ensuring no buffered turns are lost at session end.

​
Troubleshooting

The provider is installed to the wrong path. User-installed memory providers must live directly under $HERMES_HOME/plugins/<name>/. The plugins/memory/ layout is reserved for providers bundled inside Hermes Agent itself. Re-run the installer and verify the output path.
Either ATOMICMEMORY_API_URL is unset, or the Hermes Python environment is missing the atomicmemory SDK dependency from plugin.yaml. Export ATOMICMEMORY_API_URL and confirm the SDK is installed in Hermes’ Python environment.
The Hermes Python environment is missing the atomicmemory dependency. Install it into the environment Hermes uses, not your global Python environment.
The configured SDK provider is not the AtomicMemory core. Either set ATOMICMEMORY_PROVIDER=atomicmemory to use the AtomicMemory backend, or switch to ATOMICMEMORY_MEMORY_SCOPE=shared to remove the provider requirement for scope filtering.