Hermes Agent

Add persistent conversational memory to Nous Research Hermes Agent with the native MemoryRouter provider.

The published hermes-memoryrouter package captures clean conversational exchanges and recalls relevant memories across sessions. Hermes already has persistent MEMORY.md and USER.md files. This provider adds automatic conversational memory alongside those files.

Verified September 8, 2026: Hermes Agent 0.19.0, hermes-memoryrouter 0.1.1, Python 3.12. All 32 offline tests passed, followed by exact-token recall in separate real Hermes conversations before publishing and again from a fresh PyPI install.

Requirements

A working Hermes Agent installation with its model provider configured.
Python 3.11 through 3.13 for Hermes 0.19.0. Python 3.14 can resolve an older Hermes version instead of the current release.
A MemoryRouter account and memory key.

Use the same Python environment as your Hermes executable. Set HERMES_HOME if you use a non-default profile. Otherwise Hermes and the installer use ~/.hermes.

Quick start

Export your key in the environment where Hermes runs:

export MEMORYROUTER_API_KEY='YOUR_MEMORYROUTER_KEY'

Install and activate the provider:

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

The installer copies the packaged provider to $HERMES_HOME/plugins/memoryrouter/ (or ~/.hermes/plugins/memoryrouter/). Hermes 0.19.0 requires this directory installation. Re-run hermes-memoryrouter install after upgrading the package.

The package also declares the hermes_agent.memory_providers entry point, memoryrouter = "hermes_memoryrouter:register", for Hermes versions that support pip memory-provider discovery. On those versions, pip install and activation are sufficient; the directory copy is still a fallback.

Activation writes this to your Hermes config.yaml:

memory:
  provider: memoryrouter

Restart your running Hermes session after changing the provider. hermes memory setup is also available for interactive configuration.

Manual directory installation

If you prefer not 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

Key-file option

Instead of exporting the key on each run, store it in your Hermes home:

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"

Key lookup order:

MEMORYROUTER_API_KEY in the environment.
MEMORYROUTER_API_KEY_FILE pointing to a mode-0600 file.
$HERMES_HOME/memoryrouter.key with mode 0600.
MEMORYROUTER_API_KEY in $HERMES_HOME/.env.

The plugin does not read the macOS Keychain. Without a key, it remains idle.

Verify it works

hermes memory status

Expect Provider: memoryrouter, Plugin: installed, and Status: available.

Then test actual recall:

In one Hermes conversation, say: "Remember: the project verification token is ORCHID-7419."
End the session and start a fresh conversation, without resuming its history.
Ask: "What is the project verification token I told you before?"
Confirm the exact token is returned. Do not include the token in the question.

Our release proof used two separate Hermes processes with GPT-4.1 mini, distinct session IDs, no enabled toolsets, and no shared conversation history. The fresh PyPI install repeated that proof with a new random token. This validates that setup, not every possible Hermes model or deployment.

How it works

Recall: before a turn, /v1/memory/prepare retrieves relevant memories using the current user text. The result is wrapped in <memoryrouter-context> as background context. Default recall is capped at 24,000 characters and a 2.5-second timeout.

Capture: after a completed turn, /v1/memory/ingest stores the clean user message and final assistant reply. Capture is asynchronous with one retry. Tool calls, tool results, thinking blocks, system text, and recalled-memory wrappers are filtered out.

Your model provider and inference credentials remain configured in Hermes. Conversational exchanges are sent to the MemoryRouter account behind your key. Only enable capture for conversations you want stored there.

Configuration

Non-secret settings live in $HERMES_HOME/memoryrouter.json:

{
  "vault": "core",
  "density": "default",
  "auto_recall": true,
  "auto_capture": true,
  "recall_max_chars": 24000,
  "recall_timeout": 2.5
}

Option	Default	Meaning
`base_url`	`https://api.memoryrouter.ai`	Memory endpoint, also `MEMORYROUTER_BASE_URL`.
`vault`	`core`	Shared across sessions. `session` isolates each conversation.
`density`	`default`	`low`, `default`, `high`, or `xhigh`.
`auto_recall`	`true`	Retrieve memory before turns.
`auto_capture`	`true`	Store completed exchanges.
`include_subagents`	`false`	Allow capture from subagent contexts.
`recall_limit`	`0`	Explicit count override, or server default.
`recall_max_chars`	`24000`	Maximum injected recall length.
`store_max_chars`	`8000`	Maximum stored text per side.
`recall_timeout`	`2.5`	Recall timeout in seconds.
`store_timeout`	`10`	Timeout per store attempt in seconds.
`debug`	`false`	Enable provider debug logging.

To pause memory, set auto_capture and auto_recall to false, then restart Hermes. This does not delete previously stored memories. Manage your vault in the MemoryRouter dashboard.

Troubleshooting

Plugin is not installed: run hermes-memoryrouter install from the same Python environment as Hermes. Verify HERMES_HOME matches in both commands. On 0.19.0, pip installation alone is not enough.

Provider is unavailable: check that the key is set in the environment of the actual Hermes process, or that the key file exists with mode 0600. Do not paste credentials into support logs.

An older Hermes version is installed: check python --version and pip show hermes-agent. Use Python 3.11 through 3.13 for the tested Hermes 0.19.0 release.

A fresh session recalls nothing: confirm vault is core, both sessions use the same key, and capture is enabled. Allow a few seconds for ingestion. Ask about a distinctive fact rather than a trivial greeting.

Turns feel slower: recall can add up to its configured timeout. Lower recall_timeout for a tighter cap. Memory failures do not crash Hermes, but failed writes are not guaranteed to be retained.

Changes disappear after an upgrade: the directory copy is separate from the pip package. Re-run hermes-memoryrouter install after pip install --upgrade hermes-memoryrouter.

Limitations

This is a native Hermes memory provider, not a replacement for every use of MEMORY.md or USER.md. The verified configuration above is a release-specific proof, not a universal compatibility claim. Core-vault mode shares context among sessions using the same key; session-vault mode intentionally does not. Capture sends selected conversational text to MemoryRouter, and failed asynchronous writes are not guaranteed to survive an outage.

Next steps

View the integration · Create an account · All integrations