hermes-memory-providers

Mnemosyne — Hermes Memory Provider

Mnemosyne is a local-first memory layer for AI agents. When deployed as a Hermes memory provider, it replaces the built-in MEMORY.md/USER.md system with SQLite-backed vector + FTS5 hybrid search, episodic consolidation, temporal knowledge graphs, and optional bidirectional sync.

100% local. Zero cloud. Sub-millisecond recall.

What It Gives You

• System prompt injection — # Mnemosyne Memory context block in every prompt
• Pre-turn prefetch — relevant memories injected before each LLM call
• Post-turn sync — conversation turns auto-stored to episodic memory
• 20 tools auto-injected into the model's tool surface (remember, recall, sleep, triples, scratchpad, graph, sync, diagnostics, etc.)
• 3 lifecycle hooks — pre_llm_call, on_session_start, post_tool_call
• CLI commands — hermes mnemosyne {stats|sleep|inspect|export|import|clear|version}

All without touching Hermes core — deployed purely through the plugin directory.

Quick Check

hermes memory status     # See active provider and installed plugins

Install

Step 1 — Install the package

pip install mnemosyne-hermes

Debian/Trixie users (bare pip blocked): use a venv first:

python3 -m venv ~/.hermes/hermes-agent/venv
source ~/.hermes/hermes-agent/venv/bin/activate
pip install mnemosyne-hermes

mnemosyne-hermes wraps the core mnemosyne-memory library with the plugin manifest and entry points Hermes needs. It does not pull embeddings or LLM deps — pair it with one of:

Step 2 — Link the plugin

mnemosyne-hermes install

This creates the symlink ~/.hermes/plugins/mnemosyne/ → <installed package> so Hermes discovers it on startup.

Docker / read-only venv — use persistent wrapper mode so the plugin survives image rebuilds:

mnemosyne-hermes install --mode wrapper --python /path/to/venv/bin/python --hermes-home /opt/data
mnemosyne-hermes status --hermes-home /opt/data
hermes gateway restart

Step 3 — Activate

hermes config set memory.provider mnemosyne
hermes memory setup

Step 4 — (Optional) Disable built-in memory

Mnemosyne is additive by default — the built-in MEMORY.md/USER.md keeps running alongside it. To make Mnemosyne the sole memory system, edit ~/.hermes/config.yaml:

memory:
  memory_enabled: false
  user_profile_enabled: false

Do NOT run hermes tools disable memory — that also kills all 20 Mnemosyne-registered tools.

Step 5 — Verify

hermes memory status       # Should show "Provider: mnemosyne"
hermes mnemosyne stats     # Working + episodic memory counts

Test in a conversation:

hermes chat -q "Remember that I love apples. What do I love?"

You should see mnemosyne_remember and mnemosyne_recall calls succeed.

If hermes mnemosyne stats gives "invalid choice: 'mnemosyne'", the plugin CLI registration didn't load. Use hermes hermes-mnemosyne stats as a fallback, or re-run Step 2 to relink.

MCP vs. Provider Plugin

Mnemosyne ships an MCP server (mnemosyne mcp, stdio + SSE transports) that exposes 35 tools — usable with any MCP-compatible client (Claude Desktop, etc.):

mnemosyne mcp                              # stdio transport
mnemosyne mcp --transport sse --port 8080  # SSE transport

For Hermes, prefer the provider plugin over MCP. The provider plugin gives deeper integration that MCP cannot: the pre_llm_call context injection hook, on_session_start initialization, post_tool_call memory capture, and the hermes mnemosyne CLI subcommands. MCP is a generic fallback for non-Hermes agents.

Switching Back

hermes memory off          # Disable external provider, revert to built-in
hermes memory setup        # Or use the interactive picker

Or manually:

hermes config set memory.provider memory

Then restart Hermes.

CLI Commands

hermes mnemosyne stats                # Current session stats
hermes mnemosyne stats --global       # Stats across all sessions
hermes mnemosyne inspect "query"      # Search memories
hermes mnemosyne sleep                # Run consolidation (working → episodic)
hermes mnemosyne export --output backup.json
hermes mnemosyne import --input backup.json
hermes mnemosyne clear                # Clear scratchpad
hermes mnemosyne version              # Show version

Data Location

~/.hermes/mnemosyne/
└── data/
    ├── mnemosyne.db              # Main SQLite database (WAL mode)
    ├── triples.db                # Standalone TripleStore
    └── banks/<name>/mnemosyne.db # Named memory banks (per-bank isolation)

Persists across sessions via ~/.hermes/ (including on ephemeral VMs like Fly.io).

Optional: Host LLM Routing

Mnemosyne's consolidation (sleep) and fact extraction can use a local GGUF or a remote OpenAI-compatible API. Hermes users with OAuth-backed providers (e.g. openai-codex) can route those LLM calls through Hermes' authenticated auxiliary client instead — no extra credentials needed:

export MNEMOSYNE_HOST_LLM_ENABLED=true

See docs/hermes-llm-integration.md for the full behavior model and config.

Troubleshooting

References

• Hermes Integration Guide — canonical setup reference
• Hermes Auxiliary LLM Integration — host LLM routing
• Mnemosyne vs Hindsight Comparison — architecture and feature comparison
• hermes-agent skill — general Hermes setup, config, and plugin system