Mnemosyne Maintenance

Mnemosyne Maintenance

Use when: upgrading Mnemosyne, diagnosing slow/hung consolidation (mnemosyne_sleep), fixing missing embeddings, or troubleshooting import/version mismatches.

Triggers

• mnemosyne_sleep hanging for >2 minutes
• Diagnose reports "fastembed not available" or "sqlite_vec not available" despite being installed
• Version mismatch: pip shows newer version than runtime
• Embeddings_available=NO when deps are present

Core troubleshooting (in order)

1. Run diagnostics:

• mnemosyne_diagnose
• Look for: missing fastembed, sqlitevec, ctransformers; embeddingsavailable status; mnemosyne_version

1. Check for local dev shadowing:

• A local ~/mnemosyne directory will shadow the pip-installed package because Python adds ~ to sys.path on macOS.
• Confirm with:

python -c "import mnemosyne, inspect; print(mnemosyne.__file__)" If it prints ~/mnemosyne/..., that's the problem.

1. Fix shadowing (if present):

• Rename or move local dev copy:

mv ~/mnemosyne ~/mnemosyne-local

• Ensure PYTHONPATH prioritizes site-packages in gateway plist:

plutil -replace "EnvironmentVariables.PYTHONPATH" -string "~/.hermes/hermes-agent/venv/lib/python3.11/site-packages" ~/Library/LaunchAgents/ai.hermes.gateway.plist

• Restart gateway:

launchctl stop ai.hermes.gateway && launchctl start ai.hermes.gateway

1. Remove stale plugin symlinks:

• Old setups may have:

~/.hermes/plugins/mnemosyne -> ~/mnemosyne/hermesmemoryprovider Modern Mnemosyne (3.8+) includes Hermes integration in the package; this symlink is unnecessary and can break imports.

• If present, remove it:

rm ~/.hermes/plugins/mnemosyne

1. Upgrade Mnemosyne + deps:

• From venv:

pip install --upgrade "mnemosyne-memory[embeddings]" sqlite-vec

• If version mismatch persists (pip shows new, runtime still old):
• Uninstall and reinstall cleanly:

pip uninstall -y mnemosyne-memory && pip install --upgrade "mnemosyne-memory[embeddings]" sqlite-vec

1. Restart gateway after changes:

• launchctl stop ai.hermes.gateway && launchctl start ai.hermes.gateway

1. Verify:

• Run:

python -c "import mnemosyne; print(mnemosyne.__version__, mnemosyne.__file__)" Confirm it loads from site-packages and shows expected version.

• Run mnemosyne_diagnose again.
• Test consolidation:

mnemosynesleep (dryrun=true)

Embeddings

• If episodic_vectors=0, future operations will be slow on large DBs.
• Enabling embeddings requires:
• MNEMOSYNEVECTYPE set to "fastembed" in .env (not just sqlite_vec)
• sqlite-vec and fastembed installed
• A migration pass to vectorize existing memories

Enable embeddings (step-by-step)

1. Add env var (use Python to avoid overwriting):

• python -c "

import os path = os.path.expanduser('~/.hermes/.env') with open(path, 'a') as f: f.write('MNEMOSYNEVECTYPE=fastembed\n') "

1. Restart gateway:

• launchctl stop ai.hermes.gateway && launchctl start ai.hermes.gateway

1. Run auto-fix diagnostics (ensures deps and vec indexes are healthy):

• ~/.hermes/hermes-agent/venv/bin/mnemosyne diagnose --fix

1. Plan reindex (dry run first):

• ~/.hermes/hermes-agent/venv/bin/mnemosyne reindex --dry-run

Confirms model, dimensions, and memory counts before writing.

1. Execute reindex to vectorize existing memories:

• ~/.hermes/hermes-agent/venv/bin/mnemosyne reindex --yes

This can take several minutes on large DBs; it is safe and non-blocking for Hermes runtime.

1. Verify:

• mnemosynediagnose → embeddingsavailable=OK, episodic_vectors > 0

Pitfalls

• Never trust pip show alone; always verify with import mnemosyne + __file__.
• Do not leave a local ~/mnemosyne directory in place if you intend to use the pip-installed version.
• After any Mnemosyne change, restart the gateway — Hermes caches imports at startup.
• mnemosyne_diagnose can lie about versions and deps when a local dev copy shadows site-packages (it reads from whatever import mnemosyne resolves to). Always confirm with:

python -c "import mnemosyne; print(mnemosyne.__version__, mnemosyne.__file__)" If it prints ~/mnemosyne/... instead of site-packages, your diagnosis is using the wrong package.

• On large DBs (40K+ working memories) without embeddings, mnemosyne_sleep can hang for 30+ minutes doing brute-force FTS + LLM passes. Treat this as a hard signal to enable embeddings, not just "wait longer."
• The mnemosyne reindex command may default to ~/.mnemosyne/data/ instead of ~/.hermes/mnemosyne/data/, causing backup or DB-not-found errors. Fix by:
• Setting MNEMOSYNEDATADIR=~/.hermes/mnemosyne, or
• Using --no-backup if you're confident in the DB integrity and just need to reindex.
• A stale plugin symlink at ~/.hermes/plugins/mnemosyne -> ~/mnemosyne/hermesmemoryprovider will break imports on modern Mnemosyne (3.8+), which bundles Hermes integration directly. Remove it if present.
• Hermes currently bundles mnemosyne 3.0.0 internally, so even after upgrading the pip package to 3.8+, the runtime may still report 3.0.0 and refuse to fully activate embeddings. In that case:
• Ensure PYTHONPATH in gateway plist points to site-packages.
• Add MNEMOSYNEVECTYPE=fastembed via plutil (see "Embeddings" section).
• Run reindex with MNEMOSYNEDATADIR set explicitly.
• If mnemosyne_sleep runs fast and no longer hangs, the fix worked even if diagnose still says 3.0.0.
• When using a local dev copy of Mnemosyne (e.g., ~/mnemosyne-dev), ensure its __init__.py delegates to the real package instead of shadowing it:
• Remove sys.path.insert(0, repo_root) lines that bring in the inner mnemosyne/ subpackage.
• Import everything from the installed mnemosyne-memory package via "from mnemosyne import *" so Hermes gets the latest version.

Hard-learned rules (from live sessions)

• Trust behavior over version numbers:
• If mnemosynesleep completes quickly and no longer hangs, the fix worked — even if diagnose still reports 3.0.0 or embeddingsavailable=NO.
• Hermes bundles its own older mnemosyne internally; pip upgrades alone won't change what diagnose prints. What matters is whether operations are fast and non-blocking.
• When reindex fails with "Database not found" or backup errors:
• It's using ~/.mnemosyne/data/ instead of ~/.hermes/mnemosyne/data/.
• Either set MNEMOSYNEDATADIR=~/.hermes/mnemosyne before running, or use --no-backup if you're confident in DB integrity.
• If all deps are installed and fastembed/sqlitevec show OK but embeddingsavailable=NO:
• Likely Hermes is loading its bundled mnemosyne 3.0.0 instead of the pip-installed 3.8+.
• Ensure PYTHONPATH in gateway plist points to site-packages, remove stale plugin symlinks, restart gateway, then verify with a live mnemosyne_sleep run rather than diagnose output alone.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AtlasOmnia
• Source: AtlasOmnia/donna-starter
• License: MIT

Install and usage instructions live in the source repository linked above.