Mnemosyne for Hermes Agent: Local Memory Quickstart

Mnemosyne is a local-first memory provider for Hermes Agent, storing working memory, structured facts, temporal data, and episodic history in local SQLite — no hosted service, no mandatory network calls, and unusually granular write control.

Its most useful property is not raw recall quality. It is the amount of control it exposes over the write path: conversation autosave can be restricted by role or disabled outright, tool-result logging defaults off, explicit remember and forget operations stay available regardless, and newer releases add opt-in self-echo suppression around context-compression boundaries. That combination makes it a reasonable choice when you want persistent memory without automatically turning every conversation into permanent knowledge.

That write-path discipline matters because agent memory has a well-documented failure mode: a model’s own inference can be captured, retrieved later as if it were an observation, and used to justify an even stronger version of itself. Self-Reinforcing Memory Loops in AI Agents covers that failure mode in depth; this guide focuses on the concrete Mnemosyne configuration that limits it in practice. For where Mnemosyne sits relative to the other Hermes memory backends, see Agent Memory Providers Compared.

Mnemosyne in one minute

A typical memory provider does some version of capture, extract, store, retrieve, then inject into a future prompt. Mnemosyne adds several distinct layers around that basic loop: working memory, semantic and lexical recall, structured facts, temporal information, entity links, episodic memory, consolidation, canonical facts, and memory validation. Storage is local SQLite with FTS5 and optional vector retrieval, which makes it considerably more inspectable than a cloud-only memory product and more capable than a plain MEMORY.md file.

Very briefly, relative to the rest of the Hermes provider ecosystem: Holographic is simpler and deliberately fact-store oriented; Hindsight emphasizes hybrid retrieval, knowledge graphs, and reflection; Honcho emphasizes peer and user modeling with dialectic reasoning; Mem0 emphasizes automatic LLM-based fact extraction; and Mnemosyne combines local SQLite storage, hybrid recall, consolidation, structured facts, and unusually granular retention controls. The full breakdown, including infrastructure requirements and self-hosting notes for every provider, is in Agent Memory Providers Compared.

Current versions

As of September 2026, the stable PyPI release is mnemosyne-memory 3.15.1, with the 4.0 branch available as a pre-release. For a production Hermes installation, start with the stable version unless you specifically need a 4.0 fix or feature and are prepared to test the database migration and behavior change. Check your installed version with:

hermes mnemosyne version

Installing Mnemosyne into Hermes

Activate Hermes’ own virtual environment first if you used the standard local installation:

source ~/.hermes/hermes-agent/venv/bin/activate

For local embedding support, install the core package with the embeddings extra plus the Hermes plugin wrapper:

python -m pip install \
  "mnemosyne-memory[embeddings]" \
  mnemosyne-hermes

Then register the plugin:

mnemosyne-hermes install

If you are replacing an existing plugin registration:

mnemosyne-hermes install --force

Activate the provider and restart the gateway:

hermes config set memory.provider mnemosyne
hermes gateway restart

Verify with:

hermes memory status

Expected output looks similar to:

Provider: mnemosyne

Plugin: installed
Status: available

Docker and persistent-server installs

If Hermes runs inside a persistent Docker or image-based deployment, install into a side virtual environment on the mounted Hermes home instead of the container’s rebuildable Python environment, so the plugin survives image rebuilds:

export HERMES_HOME=/opt/data
VENV="$HERMES_HOME/.mnemosyne/venv"
python3 -m venv "$VENV"
"$VENV/bin/python" -m pip install --upgrade "mnemosyne-memory[embeddings]" mnemosyne-hermes
"$VENV/bin/mnemosyne-hermes" install --mode wrapper --python "$VENV/bin/python"
hermes config set memory.provider mnemosyne

The side venv must use the same Python major/minor version as the running Hermes gateway — do not point it at an unrelated python3 from PATH. Restart the actual container or service afterward and verify with "$VENV/bin/mnemosyne-hermes" status alongside hermes memory status.

Do not disable the whole Hermes memory toolset

Keep two concepts separate: Hermes’ own built-in memory (MEMORY.md / USER.md, covered in full in Hermes Agent Memory System) and the external provider (Mnemosyne). Do not casually run hermes tools disable memory when configuring an external provider — depending on the Hermes version, that command can also hide external memory-provider tools. Use provider configuration instead, as shown below.

Basic status and inspection

hermes memory status
hermes mnemosyne stats
hermes mnemosyne stats --global
hermes mnemosyne inspect "query"

Export a portable backup:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

The backing database normally lives under ~/.hermes/mnemosyne/data/mnemosyne.db. Because it is SQLite, inspection and backup are straightforward with standard tools. For the rest of the gateway, session, and diagnostics commands referenced throughout this guide, the Hermes Agent CLI cheat sheet is a faster reference than digging through --help output.

The default retention policy deserves attention

The first control worth understanding is sync_roles. Current Mnemosyne defaults are already more conservative than early releases — automatic Hermes synchronization defaults to user turns rather than both user and assistant turns — but for strict explicit-only retention, disabling turn autosave completely is worth the extra step. Edit ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

An empty list means ordinary conversation turns are not automatically saved by sync_turn(). Explicit mnemosyne_remember operations continue to work regardless — normal conversation stops flowing into memory automatically, while an explicit “remember this” still reaches Mnemosyne.

Disable automatic tool-result logging

Mnemosyne can also log tool executions as memory. For a conservative setup, leave that disabled in ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0

This is already the default, but setting it explicitly documents the policy rather than relying on an assumption about defaults. Restart Hermes afterward:

hermes gateway restart

With sync_roles: [] and MNEMOSYNE_LOG_TOOLS=0 together, both major automatic write paths — conversation autosave and tool-result autosave — are off.

Keep automatic recall

Disabling automatic writes does not require disabling recall. A useful policy keeps automatic retention off while automatic recall, explicit remember, and explicit forget all stay on — memory should be easy to read and difficult to write, which is close to the opposite of a “capture everything and sort it out later” default.

Add a durable agent instruction

Provider configuration blocks automatic provider-level capture, but the model can still decide to call an explicit write tool on its own initiative. Add an explicit policy to SOUL.md:

## Long-term memory policy

Mnemosyne is the long-term memory provider.

Do not write anything to Mnemosyne unless the user explicitly asks you to
remember, save, retain, or store that information.

If information appears useful for future sessions but the user did not
explicitly request that it be remembered, ask for permission before calling
mnemosyne_remember or another Mnemosyne write tool.

Do not create durable memories from your own reasoning, assumptions,
summaries, interpretations, conclusions, or inferred preferences.

Do not create durable memories from tool output unless the user explicitly
asks for that result to be remembered.

When storing an approved memory, preserve what the user actually stated.
Do not embellish it with inferred context or conclusions.

Reading and recalling Mnemosyne memories is allowed without asking for
permission.

Restart the gateway and start a fresh session afterward:

hermes gateway restart

/new

This is a model-enforced policy, not a hard permission boundary — it complements the provider-level configuration above rather than replacing it.

What about memory.write_approval?

Hermes supports memory.write_approval: true for built-in MEMORY.md / USER.md writes, and Mnemosyne implements its own provider-specific staging for explicit writes in newer releases. This is promising, but there is an architectural caveat worth taking seriously: Hermes does not yet expose one uniform, provider-neutral approval contract across all external memory providers, and Mnemosyne’s pending/apply implementation is provider-specific rather than part of a shared standard. Do not assume approval works correctly just because the configuration key is present — test it against your exact Hermes and Mnemosyne versions. Until provider-independent approval matures, combining sync_roles: [], MNEMOSYNE_LOG_TOOLS=0, and the explicit-write SOUL.md policy above gives you a dependable baseline, with the approval path tested separately if you intend to rely on it.

Enable self-echo suppression

Current Mnemosyne also offers optional self-echo suppression:

MNEMOSYNE_SELF_ECHO_ENABLED=1

Put this in ~/.hermes/.env, then restart:

hermes gateway restart

Self-echo suppression targets context-compression boundaries specifically — its purpose is to reduce cases where memory the provider just created gets immediately fed back into the agent as if it were independent context. It is intentionally best-effort and does not replace write filtering: write controls stop questionable memories from entering in the first place, while self-echo controls stop recent provider output from bouncing straight back. Both matter, and neither substitutes for the other.

A conservative Mnemosyne configuration

Putting the pieces together, a starting configuration for a self-hosted personal engineering agent looks like this. In ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

In ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0
MNEMOSYNE_SELF_ECHO_ENABLED=1

And in SOUL.md, at minimum:

Only store long-term memory when the user explicitly requests it.
Do not promote model-generated conclusions or tool output into durable memory
without explicit permission.

Test that ordinary conversation is not retained

Check the baseline count first:

hermes mnemosyne stats

Start a new Hermes session and say a plain factual statement without asking the agent to remember it, for example:

PurpleOtter uses port 48123.

Afterward, search for it:

hermes mnemosyne inspect "PurpleOtter"

Expected: Results for 'PurpleOtter': 0. Also re-check hermes mnemosyne stats — the working-memory count should not have increased because of that ordinary turn.

Test explicit memory

Now say the same kind of statement, but explicitly ask for retention:

Remember that BlueKoala uses port 17321.

Inspect it, then start a new session and ask for it back:

hermes mnemosyne inspect "BlueKoala"

/new

What port does BlueKoala use?

Hermes should retrieve the value correctly — this pair of tests isolates the write-path policy (nothing gets in without asking) from the retrieval mechanism (what gets in comes back out reliably).

Test tool logging

With MNEMOSYNE_LOG_TOOLS=0 set, ask Hermes to run a distinctive, unique command:

Use the terminal tool to run:
echo tool-canary-834729

Then search for the canary string:

hermes mnemosyne inspect "tool-canary-834729"

Expected: 0 results. This is a much stronger test than simply trusting that the environment variable is honored everywhere.

Inspecting the database

Because storage is SQLite, the internal schema is directly inspectable:

sqlite3 ~/.hermes/mnemosyne/data/mnemosyne.db '.tables'

Depending on version, you may see tables such as working_memory, episodic_memory, facts, consolidated_facts, gists, graph_edges, memoria_facts, and memory_embeddings. This matters when testing deletion — a memory system can successfully remove a working-memory row while leaving a derived fact, gist, or graph object behind. Mnemosyne has had real bugs in this area involving orphaned derived records, and newer releases have tightened both deletion and diagnostics accordingly. Prefer the provider’s supported delete and doctor/repair paths over manually deleting SQLite rows unless you fully understand the current schema.

Deleting session-scoped working memory

One subtlety: Mnemosyne working memories can be session-scoped, so a row with scope = session may not be visible to a standalone delete operating in the default session. When debugging, inspect scope directly:

SELECT id, session_id, scope, content
FROM working_memory;

The provider or API needs the correct session scope to mutate session-local records — another reason to prefer supported administration tools over raw SQL edits.

Consolidation: do not rush to sleep()

Mnemosyne can consolidate working memory into longer-lived representations, which is useful but is a mutating operation. Before enabling aggressive automatic consolidation, inspect what is actually being captured, verify that ordinary turns are not entering memory unexpectedly, verify deletion end to end, and back up the database. Then experiment with:

hermes mnemosyne sleep

Recent Mnemosyne changes made conflict handling more conservative — semantic similarity alone no longer proves that one memory should invalidate another, which is exactly the direction a durable agent-memory system should move in, as covered in Self-Reinforcing Memory Loops in AI Agents.

Backup before upgrades

Create a portable export before any significant change:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

For important installations, also copy the local database or data directory before major upgrades. Mnemosyne 4.x is currently a pre-release line, so a major-version upgrade deserves more caution than a routine patch update.

Final recommended setup

For a long-running Hermes installation where memory accuracy matters more than remembering everything, the durable configuration is: Mnemosyne local storage on, automatic recall on, conversation autosave off, assistant-message autosave off, tool-result logging off, explicit remember and forget on, self-echo suppression on, session search on, and human review for sensitive writes desirable once the approval path is tested. That makes Mnemosyne function primarily as a curated long-term memory store rather than a transcript archive — the goal is not to make Hermes remember everything it has ever said, but to make it remember the things that will still be true when the next session begins. If you run several profiles with different providers or retention policies, Hermes Agent production setup covers the profile-level wiring for keeping them consistent.