Hermes Mnemosyne Memory — Full Setup Guide

Setup

Install, wire, and tune the Mnemosyne memory provider inside Hermes Agent. Covers provider selection, autosleep / reflection thresholds, guardrails, memory-filter patterns, and per-profile isolation — with the venv and sudo-HOME pitfalls called out.

What you’ll learn

How to install the Mnemosyne provider into the Hermes runtime venv.
The “sudo-home” trap and how to work around it.
Which config knobs matter most for a busy box.

Contents

Step 1 — choose a provider
Step 2 — install into the right venv
Step 3 — wire the plugin (the sudo trap)
Step 4 — verify it's actually live
Step 5 — configuration knobs
Step 6 — restart the gateway

Step 1 — choose a provider

The hermes setup memory wizard only offers the built-in list (honcho, mem0, openviking, hindsight, holographic, retaindb, byterover). Mnemosyne is not on that list on current Hermes versions, so you install its pip package and its hermes_memory_provider plugin, then select it directly via hermes config set memory.provider mnemosyne. One provider instance serves the whole active profile — CLI, Telegram, Discord, etc.

Pick an install extra by available RAM (free -h):

Extra	RAM	Use when
`mnemosyne-memory` (core)	~50 MB	Low-RAM; needs an external embedding API URL
`mnemosyne-memory[embeddings]`	~800 MB	Default; local vector search, needs ≥2 GB free
`mnemosyne-memory[all]`	~1.5 GB	Adds a local consolidation LLM; wants 8 GB+ free

Step 2 — install into the right venv

The plugin must go into the Hermes runtime venv — never a side venv (it will crash on numpy/sqlite-vec/fastembed ABI). The launcher shebang tells you that path:

VPY=$(head -1 "$(which hermes)" | sed 's|^#!||')
"$VPY" --version
# root-owned venv needs sudo:
sudo "$VPY" -m pip install --upgrade --no-cache-dir "mnemosyne-memory[embeddings]"
"$VPY" -c "import mnemosyne; print('ok')"

Step 3 — wire the plugin (the sudo trap)

The sudo trap. sudo "$VPY" -m mnemosyne.install writes the plugin symlink and edits config in the sudo user's $HOME (/root/.hermes/), not the real profile home. So run the installer steps manually against the real home:

MANS=$(ls -d /usr/local/lib/hermes-agent/venv/lib/python3.*/site-packages/hermes_memory_provider)
ln -s "$MANS" ~/.hermes/plugins/mnemosyne
export HOME="$HOME"
hermes config set memory.provider mnemosyne

If you already ran it under sudo, undo root's pollution and re-point the real home:

sudo rm -f /root/.hermes/plugins/mnemosyne
sudo sed -i "s/^\\(\\s*\\)provider: mnemosyne$/\\1provider: ''/" /root/.hermes/config.yaml

Step 4 — verify it's actually live

hermes memory status always prints "Built-in: always active" and can't tell you the provider is working. Verify instead:

hermes doctor | grep -i memory        # expect: ✓ mnemosyne provider active
hermes mnemosyne version              # expect: Mnemosyne v3.x
hermes mnemosyne stats                 # JSON: working / episodic / memoria
# end-to-end round trip:
hermes chat -q "Use mnemosyne_remember to store a test fact: team color is navy."
hermes mnemosyne inspect "team color"  # expect 1 result

Step 5 — configuration knobs

All under memory.mnemosyne. in ~/.hermes/config.yaml, set with hermes config set memory.mnemosyne.KEY VALUE. (Lists like regex filters are multi-line YAML blocks — edit the file for those.)

Key	Default	What it does
`auto_sleep`	`true`	Run the background consolidation daemon
`sleep_threshold`	`50`	Consolidate once N unconsolidated working memories accumulate (tune up for low-RAM/busy boxes)
`reflect` (or `reflect_*`)	—	Reflection/guardrail knob: `disabled_for_cron`, `max_calls_per_session`
`ignore_patterns`	`[]`	Memory-filter patterns: regexes; matching text is never stored
`skip_contexts`	`[cron, flush, subagent, background, skill_loop]`	Agent contexts where auto-save is skipped
`sync_roles`	`[user]`	Which roles auto-save (`user` only avoids assistant noise); `[]` disables autosave
`profile_isolation`	`false`	Profile: one shared DB, or a separate DB per Hermes profile
`default_scope`	`global`	Default memory scope for writes
`vector_type`	`int8`	Embedding quantization: `float32` \| `int8` \| `bit`

Recommended baseline for a busy box running Postgres/gateway too:

# scalar knobs via CLI
hermes config set memory.provider mnemosyne
hermes config set memory.mnemosyne.auto_sleep true
hermes config set memory.mnemosyne.sleep_threshold 60
hermes config set memory.mnemosyne.profile_isolation false
hermes config set memory.mnemosyne.default_scope global
hermes config set memory.mnemosyne.vector_type int8
# list values are easier as YAML in the file:
#   ignore_patterns: [".*ERROR.*"]
#   sync_roles: [user]
#   skip_contexts: [cron, flush, subagent, background, skill_loop]

Step 6 — restart the gateway

The polling gateway does not hot-load a new provider's tools. Restart it so live CLI and messaging sessions pick Mnemosyne up:

# stop the running gateway, then:
hermes gateway run
# confirm in ~/.hermes/logs/gateway.log:
#   ✓ a2a connected / ✓ telegram connected
#   Gateway running with 2 platform(s)

Public blog · verified on Hermes v0.20.5 (Linux) · venv-aware install · date 2026-10.