Setting Up Mnemosyne Memory for Claude Code

Mnemosyne is a local-first AI memory system that integrates with Claude Code via MCP, giving Claude persistent memory across sessions.

Why MCP Instead of CLI

The CLI (mnemosyne store, mnemosyne recall) is a manual tool — you run it yourself and paste results back. The MCP integration makes Mnemosyne a first-class tool Claude can call directly, just like any other tool in a session.

Concretely, with MCP:

Claude automatically stores and retrieves memories during a conversation without any manual intervention
Memory reads and writes happen inline, so context is enriched transparently
No copy-pasting: Claude calls mnemosyne_remember or mnemosyne_recall the same way it calls any other tool

The CLI remains useful for inspection (mnemosyne stats), backup (mnemosyne export), and manual management — but it is not a substitute for the MCP integration when Claude is the one that needs to remember things.

Step 0: Disable Claude Code’s Built-in Auto-Memory

Claude Code has its own file-based memory system that writes to ~/.claude/projects/*/memory/. It runs in parallel with Mnemosyne if not suppressed, duplicating everything. Disable it by adding the following to ~/.claude/CLAUDE.md (create it if it doesn’t exist — this file is loaded in every session regardless of working directory):

## Memory

**Use Mnemosyne exclusively for persistent memory.** Call `mnemosyne_remember` and `mnemosyne_recall` via MCP tools.

**Never write to the file-based auto-memory system** at `~/.claude/projects/*/memory/`. Do not create or edit files there. Do not create or update any `MEMORY.md` index files. That system is not used.

Step 1: Install via pipx

pipx install mnemosyne-memory

This installs the mnemosyne CLI to ~/.local/bin/mnemosyne.

Step 2: Install the Hermes Tool Schemas

The MCP server depends on mnemosyne-hermes for its tool definitions. It must be injected into the same pipx venv:

~/.local/share/pipx/venvs/mnemosyne-memory/bin/python -m pip install mnemosyne-hermes

Skip this and mnemosyne mcp will start and complete the protocol handshake but advertise zero tools — silently broken.

Step 3: Register the MCP Server

claude mcp add --scope user mnemosyne   -e MNEMOSYNE_DATA_DIR=$HOME/.local/share/mnemosyne   -- ~/.local/bin/mnemosyne mcp

This writes the entry to ~/.claude.json, which is where Claude Code 2.x reads MCP server definitions. Do not add it to ~/.claude/settings.json — that file is not used for MCP configuration.

Step 4: Set the Data Directory in Your Shell

So that the CLI uses the same database as the MCP server, add to ~/.bashrc:

export MNEMOSYNE_DATA_DIR="$HOME/.local/share/mnemosyne"

Then run source ~/.bashrc.

Step 5: Restart Claude Code and Verify

MCP servers connect at session startup. After completing the above, start a new Claude Code session, then check:

claude mcp get mnemosyne   # should show Status: ✔ Connected
mnemosyne stats            # confirms CLI hits the right database

Step 6: Install the Mnemosyne Dashboard (Optional)

The Mnemosyne Dashboard is a local-first web UI for browsing, visualising, and maintaining your memory store. It’s intentionally minimal: Python standard library server, static HTML/CSS/JS frontend, no external JS runtime, no cloud calls, and read-only by default.

Install via Hermes

hermes plugins install wysie/mnemosyne-dashboard --enable
hermes gateway restart

Run as a persistent systemd service (Linux)

If you want the dashboard to survive Hermes restarts, run it as a systemd user service instead. Create ~/.config/systemd/user/mnemosyne-dashboard.service:

[Unit]
Description=Mnemosyne Dashboard
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/.hermes/plugins/mnemosyne-dashboard
ExecStart=python3 server.py --host 0.0.0.0 --port 8765 --db %h/.local/share/mnemosyne/mnemosyne.db
Restart=on-failure
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=default.target

Then enable and start it:

systemctl --user daemon-reload
systemctl --user enable mnemosyne-dashboard
systemctl --user start mnemosyne-dashboard

The dashboard will be available at http://localhost:8765/ (or your machine’s LAN IP if you bound to 0.0.0.0).

Configuration

Config lives at ~/.hermes/plugin-data/mnemosyne-dashboard/config.json. Key fields:

{
  "host": "0.0.0.0",
  "port": 8765,
  "db_path": "~/.local/share/mnemosyne/mnemosyne.db",
  "auth_enabled": false,
  "memory_admin_enabled": false
}

Memory admin (supersede, expire, importance updates) is disabled by default. If you enable it on a non-localhost bind address, password auth is required. Admin actions create a SQLite backup and append to an audit log — no hard deletes or raw overwrites are exposed.

Data Locations

Path	Purpose
`~/.local/share/mnemosyne/mnemosyne.db`	Primary database (set via `MNEMOSYNE_DATA_DIR`)
`~/.hermes/mnemosyne/data/mnemosyne.db`	Default fallback when `MNEMOSYNE_DATA_DIR` is unset
`~/.local/share/pipx/venvs/mnemosyne-memory/`	pipx virtual environment
`~/.hermes/plugin-data/mnemosyne-dashboard/`	Dashboard config, backups, and audit log

Troubleshooting

MCP server connects but no tools appear

The mnemosyne-hermes package is missing from the pipx venv. Run Step 2 above. You can confirm by checking the tools/list response — if "tools":[], the package is missing.

CLI uses wrong database

The CLI default is ~/.hermes/mnemosyne/data/. Set MNEMOSYNE_DATA_DIR in ~/.bashrc (Step 4) to point it at the same path the MCP server uses.

Tools missing after restart

The config is probably in the wrong file. Claude Code 2.x reads MCP servers from ~/.claude.json, not ~/.claude/settings.json. Run claude mcp get mnemosyne — if it says “not found”, re-run Step 3.