{"slug": "mnemosyne-for-hermes-agent-local-memory-quickstart", "title": "Mnemosyne for Hermes Agent: Local Memory Quickstart", "summary": "A developer released Mnemosyne, a local-first memory provider for Hermes Agent that stores working memory, structured facts, temporal data, and episodic history in local SQLite with no hosted service or mandatory network calls. The tool's distinguishing feature is granular control over the write path, including role-restricted or disabled conversation autosave, tool-result logging that defaults off, and opt-in self-echo suppression around context-compression boundaries to limit self-reinforcing memory loops. The stable PyPI release is mnemosyne-memory 3.15.1, with a 4.0 pre-release branch available.", "body_md": "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.\n\nIts 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.\n\nThat 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](https://www.glukhov.org/ai-systems/memory/self-reinforcing-memory-loops/) 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](https://www.glukhov.org/ai-systems/memory/agent-memory-providers/).\n\nA 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.\n\nVery 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](https://www.glukhov.org/ai-systems/memory/agent-memory-providers/).\n\nAs 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:\n\n```\nhermes mnemosyne version\n```\n\nActivate Hermes' own virtual environment first if you used the standard local installation:\n\n```\nsource ~/.hermes/hermes-agent/venv/bin/activate\n```\n\nFor local embedding support, install the core package with the embeddings extra plus the Hermes plugin wrapper:\n\n```\npython -m pip install \\\n  \"mnemosyne-memory[embeddings]\" \\\n  mnemosyne-hermes\n```\n\nThen register the plugin:\n\n```\nmnemosyne-hermes install\n```\n\nIf you are replacing an existing plugin registration:\n\n```\nmnemosyne-hermes install --force\n```\n\nActivate the provider and restart the gateway:\n\n```\nhermes config set memory.provider mnemosyne\nhermes gateway restart\n```\n\nVerify with:\n\n```\nhermes memory status\n```\n\nExpected output looks similar to:\n\n```\nProvider: mnemosyne\n\nPlugin: installed\nStatus: available\n```\n\nIf 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:\n\n```\nexport HERMES_HOME=/opt/data\nVENV=\"$HERMES_HOME/.mnemosyne/venv\"\npython3 -m venv \"$VENV\"\n\"$VENV/bin/python\" -m pip install --upgrade \"mnemosyne-memory[embeddings]\" mnemosyne-hermes\n\"$VENV/bin/mnemosyne-hermes\" install --mode wrapper --python \"$VENV/bin/python\"\nhermes config set memory.provider mnemosyne\n```\n\nThe 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`.\n\nKeep two concepts separate: Hermes' own built-in memory (`MEMORY.md` / `USER.md`, covered in full in [Hermes Agent Memory System](https://www.glukhov.org/ai-systems/hermes/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.\n\n```\nhermes memory status\nhermes mnemosyne stats\nhermes mnemosyne stats --global\nhermes mnemosyne inspect \"query\"\n```\n\nExport a portable backup:\n\n```\nhermes mnemosyne export \\\n  --output ~/mnemosyne-backup.json\n```\n\nThe 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](https://www.glukhov.org/ai-systems/hermes/hermes-agent-cli-cheatsheet/) is a faster reference than digging through `--help` output.\n\nThe 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`:\n\n```\nmemory:\n  provider: mnemosyne\n\n  mnemosyne:\n    sync_roles: []\n```\n\nAn 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.\n\nMnemosyne can also log tool executions as memory. For a conservative setup, leave that disabled in `~/.hermes/.env`:\n\n```\nMNEMOSYNE_LOG_TOOLS=0\n```\n\nThis is already the default, but setting it explicitly documents the policy rather than relying on an assumption about defaults. Restart Hermes afterward:\n\n```\nhermes gateway restart\n```\n\nWith `sync_roles: []` and `MNEMOSYNE_LOG_TOOLS=0` together, both major automatic write paths — conversation autosave and tool-result autosave — are off.\n\nDisabling 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.\n\nProvider 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`:\n\n```\n## Long-term memory policy\n\nMnemosyne is the long-term memory provider.\n\nDo not write anything to Mnemosyne unless the user explicitly asks you to\nremember, save, retain, or store that information.\n\nIf information appears useful for future sessions but the user did not\nexplicitly request that it be remembered, ask for permission before calling\nmnemosyne_remember or another Mnemosyne write tool.\n\nDo not create durable memories from your own reasoning, assumptions,\nsummaries, interpretations, conclusions, or inferred preferences.\n\nDo not create durable memories from tool output unless the user explicitly\nasks for that result to be remembered.\n\nWhen storing an approved memory, preserve what the user actually stated.\nDo not embellish it with inferred context or conclusions.\n\nReading and recalling Mnemosyne memories is allowed without asking for\npermission.\n```\n\nRestart the gateway and start a fresh session afterward:\n\n```\nhermes gateway restart\n/new\n```\n\nThis is a model-enforced policy, not a hard permission boundary — it complements the provider-level configuration above rather than replacing it.\n\n`memory.write_approval`?\nHermes 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.\n\nCurrent Mnemosyne also offers optional self-echo suppression:\n\n```\nMNEMOSYNE_SELF_ECHO_ENABLED=1\n```\n\nPut this in `~/.hermes/.env`, then restart:\n\n```\nhermes gateway restart\n```\n\nSelf-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.\n\nPutting the pieces together, a starting configuration for a self-hosted personal engineering agent looks like this. In `~/.hermes/config.yaml`:\n\n```\nmemory:\n  provider: mnemosyne\n\n  mnemosyne:\n    sync_roles: []\n```\n\nIn `~/.hermes/.env`:\n\n```\nMNEMOSYNE_LOG_TOOLS=0\nMNEMOSYNE_SELF_ECHO_ENABLED=1\n```\n\nAnd in `SOUL.md`, at minimum:\n\n```\nOnly store long-term memory when the user explicitly requests it.\nDo not promote model-generated conclusions or tool output into durable memory\nwithout explicit permission.\nphp\nflowchart LR\n    U[User conversation] -.->|blocked| M[(Mnemosyne)]\n    T[Tool results] -.->|blocked| M\n    R[\"Explicit: remember this\"] -->|mnemosyne_remember| M\n    Q[Future question] -->|recall| M\n```\n\nCheck the baseline count first:\n\n```\nhermes mnemosyne stats\n```\n\nStart a new Hermes session and say a plain factual statement without asking the agent to remember it, for example:\n\n```\nPurpleOtter uses port 48123.\n```\n\nAfterward, search for it:\n\n```\nhermes mnemosyne inspect \"PurpleOtter\"\n```\n\nExpected: `Results for 'PurpleOtter': 0`. Also re-check `hermes mnemosyne stats` — the working-memory count should not have increased because of that ordinary turn.\n\nNow say the same kind of statement, but explicitly ask for retention:\n\n```\nRemember that BlueKoala uses port 17321.\n```\n\nInspect it, then start a new session and ask for it back:\n\n```\nhermes mnemosyne inspect \"BlueKoala\"\n/new\nWhat port does BlueKoala use?\n```\n\nHermes 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).\n\nWith `MNEMOSYNE_LOG_TOOLS=0` set, ask Hermes to run a distinctive, unique command:\n\n```\nUse the terminal tool to run:\necho tool-canary-834729\n```\n\nThen search for the canary string:\n\n```\nhermes mnemosyne inspect \"tool-canary-834729\"\n```\n\nExpected: `0 results`. This is a much stronger test than simply trusting that the environment variable is honored everywhere.\n\nBecause storage is SQLite, the internal schema is directly inspectable:\n\n```\nsqlite3 ~/.hermes/mnemosyne/data/mnemosyne.db '.tables'\n```\n\nDepending 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.\n\nOne 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:\n\n```\nSELECT id, session_id, scope, content\nFROM working_memory;\n```\n\nThe provider or API needs the correct session scope to mutate session-local records — another reason to prefer supported administration tools over raw SQL edits.\n\n`sleep()`\nMnemosyne 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:\n\n```\nhermes mnemosyne sleep\n```\n\nRecent 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](https://www.glukhov.org/ai-systems/memory/self-reinforcing-memory-loops/).\n\nCreate a portable export before any significant change:\n\n```\nhermes mnemosyne export \\\n  --output ~/mnemosyne-backup.json\n```\n\nFor 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.\n\nFor 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](https://www.glukhov.org/ai-systems/hermes/production-setup/) covers the profile-level wiring for keeping them consistent.", "url": "https://wpnews.pro/news/mnemosyne-for-hermes-agent-local-memory-quickstart", "canonical_source": "https://dev.to/rosgluk/mnemosyne-for-hermes-agent-local-memory-quickstart-p0k", "published_at": "2026-09-22 10:07:07+00:00", "updated_at": "2026-09-22 10:23:16.653102+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "developer-tools"], "entities": ["Mnemosyne", "Hermes Agent", "SQLite", "PyPI", "Holographic", "Hindsight", "Honcho", "Mem0"], "alternates": {"html": "https://wpnews.pro/news/mnemosyne-for-hermes-agent-local-memory-quickstart", "markdown": "https://wpnews.pro/news/mnemosyne-for-hermes-agent-local-memory-quickstart.md", "text": "https://wpnews.pro/news/mnemosyne-for-hermes-agent-local-memory-quickstart.txt", "jsonld": "https://wpnews.pro/news/mnemosyne-for-hermes-agent-local-memory-quickstart.jsonld"}}