[BUG] Mnemosyne Vector Embeddings Not Initializing

[nsheusi]

Mnemosyne Vector Embeddings Not Initializing

Reported: 2026-06-04
Component: mnemosyne → plugins/mnemosyne/ (Hermes memory provider) + mnemosyne.core.embeddings

---

Environment

VPS (Hermes Agent host)

Spec	Value
Hostname	nermies
OS	Ubuntu 24.04.4 LTS
Kernel	6.8.0-117-generic (x86_64)
CPU	1 core
RAM	955 MiB
Python	3.11.15 (via uv)
Hermes Agent	0.15.1
Hermes venv	/home/<user>/.hermes/hermes-agent/venv/
Hermes config	/home/<user>/.hermes/config.yaml

Package Versions (all in Hermes venv)

Package	Version	Status
mnemosyne-memory	3.1.2	Installed
fastembed	0.8.0	Installed ✓
numpy	2.4.3	Installed ✓
sqlite-vec	0.1.9	Installed ✓

Hermes Plugin Location

• Plugin path: ~/.hermes/plugins/mnemosyne/__init__.py (user-installed)
• Plugin files: __init__.py, audit.py, cli.py, hermes_llm_adapter.py

Memory Config (~/.hermes/config.yaml)

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  provider: mnemosyne
  mnemosyne:
    auto_sleep: 'true'
    ignore_patterns: one per line
    shared_surface_path: /home/<user>/.hermes/mnemosyne/data/shared/mnemosyne.db
    skip_contexts: cron,flush,subagent,background,skill_loop
    sleep_threshold: '40'
    vector_type: int8

---

Symptoms

1. mnemosyne_diagnose tool (running inside the Hermes gateway process) consistently reports:

   fastembed:              MISSING
   numpy:                  MISSING
   sqlite_vec:             OK (0.1.9)
   embeddings_available:   NO
   embeddings_model:       BAAI/bge-small-en-v1.5
   episodic_vectors:       0
   

   Key finding: "fastembed not available - install with: pip install mnemosyne-memory[embeddings]"

2. Running run_diagnostics() directly from the same Hermes venv shows everything healthy:

   fastembed:              OK (0.8.0)
   sqlite_vec:             OK (0.1.9)
   numpy:                  OK (2.4.3)
   embeddings_available:   YES
   

3. mnemosyne_recall results all show dense_score: 0.0 — the vector (dense) scoring component contributes nothing, despite keyword_score and fts_score working. The hybrid scoring formula is effectively FTS5-only.

4. The discrepancy persists even after a full gateway restart (killed by --replace, new PID 197123 confirmed).

5. Config vector_type: int8 is explicitly noted as not wired to the runtime (see plugin line 851):

   "Vector storage type (note: not yet wired to BeamMemory at runtime; reserved for future use)"

---

Investigation

What was tried

Attempt	Outcome
pip install mnemosyne-memory[embeddings]	All packages already installed
python -c "import fastembed; print(fastembed.__version__)"	0.8.0 ✓
python -c "import numpy; print(numpy.__version__)"	2.4.3 ✓
mnemosyne_diagnose from fresh venv Python	All embedding checks pass ✓
Gateway restart (hermes gateway run --replace)	Diagnose still shows fastembed MISSING
Direct import test with plugin path manipulation in fresh Python	ModuleNotFoundError: No module named 'mnemosyne.core'

Direct import test proving the path shadowing

import sys
sys.path.insert(0, '/home/linuxuser/.hermes/plugins/')  # ← what plugin does
from mnemosyne.core import embeddings  # FAILS: finds plugin, not site-packages

With the Hermes plugin directory at sys.path[0], import mnemosyne resolves to ~/.hermes/plugins/mnemosyne/ (the Hermes plugin __init__.py) instead of the installed mnemosyne package in site-packages. The plugin has no core/ subpackage, so from mnemosyne.core.episodic_graph import GraphEdge fails.

---

Root Cause Analysis

1. sys.path shadowing in the Hermes plugin

The Hermes plugin at ~/.hermes/plugins/mnemosyne/__init__.py (lines 28–30) inserts itself onto sys.path:

_mnemosyne_root = Path(__file__).resolve().parent.parent  # → ~/.hermes/plugins/
if str(_mnemosyne_root) not in sys.path:
    sys.path.insert(0, str(_mnemosyne_root))

This puts ~/.hermes/plugins/ at position 0 of sys.path. Since both the Hermes plugin and the installed mnemosyne package share the same bare namespace name (mnemosyne), any subsequent import mnemosyne (or __import__("fastembed") from within mnemosyne.diagnose.run_diagnostics()) can shadow to the wrong package depending on import order.

Why it usually works: The installed mnemosyne (from site-packages) is normally imported and cached in sys.modules before the plugin's sys.path manipulation runs. However, in certain import sequences — particularly when mnemosyne.diagnose.run_diagnostics() calls __import__("fastembed") or import numpy — the manipulated path can cause resolution failures.

2. Module-level evaluation of _FASTEMBED_AVAILABLE

In mnemosyne.core.embeddings (line 35):

_FASTEMBED_AVAILABLE = np is not None and TextEmbedding is not None

This is evaluated once at module import time. If the import happens before fastembed is available, or if it resolves to a path-shadowed context, the variable is permanently False. Python's sys.modules caching means this cannot be recovered without a process restart.

3. vector_type config is a no-op

The Hermes plugin's config schema (line 851) explicitly documents that vector_type is not wired:

{"key": "vector_type", "description": "Vector storage type (note: not yet wired to BeamMemory at runtime; reserved for future use)", ...}

The validation code (line 770–773) reads and validates the value but never passes it to BeamMemory. The config key exists for future use only.

---

Current State

Metric	Value
Working memories	331
Episodic summaries	52
Episodic vectors	0 (embeddings not active)
Shared surface	Empty
Hybrid scoring	FTS5 + importance only (no vector similarity)

---

Recommended Fixes

Short-term (operator workaround)

1. Fix the import shadowing in the Hermes plugin: Import and cache mnemosyne (and its submodules) from site-packages before modifying sys.path, so the correct modules are in sys.modules before the path manipulation takes effect.
2. Alternatively: Make the sys.path insertion conditional (insert(0, …) → append(…) or remove after a targeted import).

Medium-term (library change in mnemosyne.core.embeddings)

3. Make _FASTEMBED_AVAILABLE a lazy property or function rather than a module-level constant, so it re-evaluates on first use (or each call). This would also fix the stale-state issue when packages are installed while the process is running.

Config schema

4. Either wire vector_type to BeamMemory so it actually enables/disables vector storage, or remove the config key from the Hermes plugin schema to avoid misleading operators into thinking it's functional.

---

Files Referenced

File	Relevance
~/.hermes/plugins/mnemosyne/__init__.py	Hermes plugin — sys.path manipulation (L28–30), config schema (L851)
venv/lib/python3.11/site-packages/mnemosyne/core/embeddings.py	_FASTEMBED_AVAILABLE module-level eval (L35), available() (L175–185)
venv/lib/python3.11/site-packages/mnemosyne/diagnose.py	run_diagnostics() — separate fastembed check (L97–111) vs embeddings check (L114–119)
~/.hermes/config.yaml	Memory config with vector_type: int8

[AxDSan]

Thanks for the thorough RCA @nsheusi — best bug report we've had all week.

You've correctly identified two issues:

1. Core fix (Mnemosyne): at imports.py:35 is a module-level constant that evaluates once. If the Hermes plugin has already polluted sys.path, it's stuck False even if the real packages are importable later. I'll convert this to a lazy function/cached property that re-evaluates on first use. This is the defensive fix regardless of the plugin issue.

2. Plugin fix (Hermes plugin): The root cause is doing which shadows the installed package. The fix is to import the real mnemosyne into sys.modules before modifying sys.path. This belongs in the Hermes plugin repo.

I'll tackle both this week. Thanks again for the detailed analysis — this is exactly the kind of debugging we need more of.

[nsheusi]

Appreciate it. In full transparency written with the help of Hermes, of course. Deepseek (main) & Granite (auxiliary).

[AxDSan]

@nsheusi thanks for the thorough writeup. Full env dump and config made this easy to trace.

The short version is that the diagnose tool and your Hermes venv might be looking for packages on different paths. So even though fastembed and numpy are installed, the process running diagnose can't reach them.

A quick way to check - could you activate your Hermes venv and try importing one of the packages directly? If it works, we know the packages are fine and it's just a context mismatch between the gateway and the venv where you installed things.

Separately, the model download failing on startup (BAAI/bge-small-en-v1.5) is a transient issue that's been hitting CI runners too. Usually clears on retry.

One more thing - the stats showing 0 vectors is a known bug I'm fixing in another PR. Your recall likely works fine even with the 0 showing.

Let me know what you find on the import check and I'll walk you through the rest.

[AxDSan]

@nsheusi — this was comprehensively diagnosed in the thread. Two root causes identified (core imports.py eval-once constant + Hermes plugin sys.path pollution), and the fixes are in progress.

No follow-up in 50h since the last response, so closing for board hygiene. If the next release doesn't resolve your setup, reopen with the output of hermes memory status and I'll pick it right back up.

[nsheusi]

@AxDSan apologies, I've been travelling. Will give this a shot when I return. Thank you.