Persistent memory for Hermes Agent

Persistent conversational memory for Nous Research Hermes Agent, powered by MemoryRouter. Your agent can remember what you told it yesterday across sessions, without you manually curating every useful detail into a memory file. Hermes already has persistent MEMORY.md and USER.md files. This native memory provider adds automatic capture of conversational exchanges and relevant recall from your MemoryRouter vault.

Tested against hermes-agent==0.19.0, the current PyPI release on September 8, 2026, with Python 3.12. Hermes 0.19.0 requires Python 3.11 through 3.13. Python 3.14 can silently resolve an older Hermes release, so use a supported Python version.

30-second install

Requires a working Hermes Agent install. Use the same Python environment as Hermes. Create a MemoryRouter account and get your key, then export MEMORYROUTER_API_KEY in the shell where you run Hermes.

pip install hermes-memoryrouter
hermes-memoryrouter install
hermes config set memory.provider memoryrouter

The installer copies the packaged provider into ${HERMES_HOME:-~/.hermes}/plugins/memoryrouter/. Hermes 0.19.0 discovers memory providers from this directory, not from pip entry points. Re-run the install command after upgrading the package.

The package also declares hermes_agent.memory_providers with memoryrouter = "hermes_memoryrouter:register" for Hermes versions that support memory-provider entry points. On those versions, pip install plus the config command is sufficient. The directory install remains a fallback.

Manual equivalent if you do not want to use the helper:

export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/plugins/memoryrouter"
cp -R "$(python -c 'import hermes_memoryrouter,pathlib; print(pathlib.Path(hermes_memoryrouter.__file__).parent)')/." "$HERMES_HOME/plugins/memoryrouter/"
hermes config set memory.provider memoryrouter

API key

The plugin never reads the macOS Keychain. Key lookup order:

1. MEMORYROUTER_API_KEY in the environment
2. MEMORYROUTER_API_KEY_FILE pointing to a mode-0600 file
3. $HERMES_HOME/memoryrouter.key (mode 0600)
4. MEMORYROUTER_API_KEY= inside $HERMES_HOME/.env

Without a key the provider is idle. To use a file instead of an environment variable:

export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
umask 077
printf '%s\n' 'YOUR_MEMORYROUTER_KEY' > "$HERMES_HOME/memoryrouter.key"
chmod 600 "$HERMES_HOME/memoryrouter.key"
hermes memory status

hermes memory setup is also available for interactive configuration. Keep your model provider and model key as configured in Hermes. This plugin supplies memory, not model inference.

How it works

• Capture: stores clean user messages and final assistant replies after completed turns.
• Recall: retrieves relevant past conversation context before each turn, bounded by a 2.5-second default timeout and a 24,000-character cap.
• Filter: excludes tool results, tool calls, thinking blocks, system text, and recalled-memory wrappers from capture.
• Fail open: memory errors do not crash a conversation. Recall can delay a turn up to its timeout; capture runs in the background.

This is a native Hermes MemoryProvider, not OpenClaw's mr-memory plugin. Completed conversational exchanges are sent to the MemoryRouter account behind your key. Only configure it for conversations you want stored there.

Configuration

Non-secret settings live in $HERMES_HOME/memoryrouter.json. The setup wizard only asks for the key.

How capture works

Hermes calls sync_turn(user, assistant, messages=...) after each completed turn. The plugin:

1. Takes the user and assistant strings Hermes already split out.
2. Strips <system-reminder>, <memory_context>, thinking tags, and tool-call XML.
3. Drops slash commands (/new, /status, …) and trivial prompts (ok, thanks, hi).
4. If either side is empty, falls back to the last clean user/assistant pair in messages, ignoring tool and system roles.
5. Truncates each side and POSTs {messages:[{role:user},{role:assistant}]} to /v1/memory/ingest on a daemon thread.

Recall uses /v1/memory/prepare with the current user text as the query. Results are wrapped in <memoryrouter-context> so they cannot be re-ingested.

By default (vault: core) exchanges go to the key's core vault, so session B can recall what session A stored. That is the point of persistent memory.

CLI

When memory.provider is memoryrouter:

hermes memoryrouter status
hermes memoryrouter config

Development

python -m pytest -q

Unit tests are offline (local HTTP mock). The release gate also runs actual Hermes conversations in two separate Python processes with GPT-4.1 mini and no enabled toolsets. A unique token taught in session A must appear exactly in session B, whose prompt does not contain the token. The gate is repeated from a fresh PyPI install after publishing. scripts/live_cross_session.py is a separate lower-level provider smoke test.

License

MIT © John Rood · memoryrouter.ai