Mnemosyne Configuration

Mnemosyne is the zero-dependency AI memory system baked into Hermes. It handles

working memory, episodic memory, semantic search, and the sleep/consolidation

cycle that summarizes working memories into durable episodic entries.

This skill covers the LLM-powered consolidation path — how it works, how to

configure it, and what to do when the 657 MB GGUF model appears out of nowhere.

When This Skill Activates

Use this skill when the user:

• Asks about Mnemosyne, memory consolidation, or the sleep cycle
• Discovers a large .gguf file in ~/.hermes/mnemosyne/models/
• Wants to change how memory summarization works (local, remote, host, or off)
• Needs to troubleshoot mnemosyne_diagnose output (e.g., missing backends)
• Asks where to set Mnemosyne environment variables
• Wonders why a model was auto-downloaded

The Consolidation Fallback Chain

When Mnemosyne runs its sleep/consolidation cycle (summarize_memories()), it

tries backends in this exact order:

0. Host LLM (MNEMOSYNE_HOST_LLM_ENABLED=true + registered backend)
1. Remote OpenAI-compatible API (MNEMOSYNE_LLM_BASE_URL set)
2. Local GGUF via llama-cpp-python
3. Local GGUF via ctransformers (x86_64, legacy)
4. AAAK encoding (text-based compression — no LLM needed, always works)

Critical rule: When the host backend is attempted (step 0) and produces no

usable text, the remote URL (step 1) is skipped — falls straight to local

GGUF, then None. This prevents accidentally routing memory content to a stale

MNEMOSYNE_LLM_BASE_URL the user forgot to clear.

The Local Model (MiniCPM5-1B)

Mnemosyne's default local model is openbmb/MiniCPM5-1B-GGUF (Q4_K_M quant,

~657 MB). It's auto-downloaded from Hugging Face to:

$HERMES_HOME/mnemosyne/models/MiniCPM5-1B-Q4_K_M.gguf

The download happens lazily — the first time consolidation runs and no

remote/host backend is configured.

The model is dead weight without a runtime. Mnemosyne needs either llama-cpp-python or ctransformers to actually run inference. When neither is

installed (which is common in production Hermes deployments), the sleep cycle

silently falls through to AAAK encoding. The 657 MB file sits on disk unused.

Check what's installed:

mnemosyne_diagnose  # shows ctransformers and other dep status
python3 -c "import llama_cpp"  # exit 0 = installed
python3 -c "import ctransformers"  # exit 0 = installed

Environment Variables

Set these in $HERMES_HOME/.env (e.g., /opt/data/.env when HERMES_HOME

is overridden). For the default install, ~/.hermes/.env.

Ways to set them:

# Direct append
echo 'MNEMOSYNE_HOST_LLM_ENABLED=true' >> $HERMES_HOME/.env

Or via hermes config
hermes config set env.MNEMOSYNE_HOST_LLM_ENABLED true

Restart Hermes after changing env vars (/restart or gateway restart).

Essential Env Vars

Variable	Default	Effect
MNEMOSYNE_LLM_ENABLED	true	Master kill-switch. Set to false to skip ALL LLM paths (host, remote, local). Consolidation falls back to AAAK encoding only.
MNEMOSYNE_HOST_LLM_ENABLED	false	Route consolidation through Hermes's own LLM. When true AND a host backend is registered, this becomes the first-choice path. Recommended for Hermes users who already have an LLM provider configured.
MNEMOSYNE_LLM_BASE_URL	(empty)	OpenAI-compatible endpoint for remote consolidation. If set and LLM is enabled, used as step 1 in the fallback chain.
MNEMOSYNE_LLM_API_KEY	(empty)	API key for the remote endpoint.
MNEMOSYNE_LLM_MODEL	"local"	Model name sent to the remote endpoint.
MNEMOSYNE_FORCE_LOCAL	(empty)	Set to 1 or true to skip the remote API even when MNEMOSYNE_LLM_BASE_URL is set.

Tuning Vars

Variable	Default	Effect
MNEMOSYNE_LLM_N_CTX	2048	Context window for local GGUF models. Also used as the token budget for chunking memories.
MNEMOSYNE_LLM_MAX_TOKENS	2048	Max output tokens. Capped internally at n_ctx // 4 to prevent negative input budget.
MNEMOSYNE_LLM_N_THREADS	4	CPU threads for local inference.
MNEMOSYNE_HOST_LLM_N_CTX	32000	Context budget when the host LLM path is active. Much larger than LLM_N_CTX because Codex/GPT-class aux models can handle it.
MNEMOSYNE_HOST_LLM_TIMEOUT	15	Seconds before host LLM call times out.
MNEMOSYNE_LLM_TIMEOUT	60	Seconds before remote LLM call times out.

Custom Model Vars

Variable	Default	Effect
MNEMOSYNE_LLM_REPO	openbmb/MiniCPM5-1B-GGUF	Hugging Face repo for the GGUF model. Set together with MNEMOSYNE_LLM_FILE to use a different local model.
MNEMOSYNE_LLM_FILE	MiniCPM5-1B-Q4_K_M.gguf	Filename within the repo.
MNEMOSYNE_SLEEP_PROMPT	(built-in)	Custom consolidation prompt. Supports {source}, {memories}, {memory_count}.
MNEMOSYNE_LLM_FALLBACK_MODELS	(empty)	Comma-separated model names to try if the primary remote model fails with a retryable error (404, 400, 5xx).
MNEMOSYNE_LLM_FALLBACK_BASE_URL	(same as LLM_BASE_URL)	Endpoint for fallback models.
MNEMOSYNE_LLM_FALLBACK_API_KEY	(same as LLM_API_KEY)	Key for fallback endpoint.

Common Scenarios

Scenario 1: "Why is there a 657 MB GGUF file on my disk?"

Mnemosyne auto-downloaded it. This happens when consolidation runs and no

remote/host backend is configured. The model was downloaded but likely can't

run — llama-cpp-python and ctransformers are rarely pre-installed.

Fix: Delete the model and configure a backend you can actually use:

# Option A: Use Hermes itself (recommended for Hermes users)
rm -rf $HERMES_HOME/mnemosyne/models/
echo 'MNEMOSYNE_HOST_LLM_ENABLED=true' >> $HERMES_HOME/.env

Option B: Use a remote API
rm -rf $HERMES_HOME/mnemosyne/models/
echo 'MNEMOSYNE_LLM_BASE_URL=https://api.openai.com/v1' >> $HERMES_HOME/.env
echo 'MNEMOSYNE_LLM_API_KEY=sk-...' >> $HERMES_HOME/.env

Option C: Install the backend and keep the model
pip install llama-cpp-python

Option D: Disable LLM consolidation entirely
rm -rf $HERMES_HOME/mnemosyne/models/
echo 'MNEMOSYNE_LLM_ENABLED=false' >> $HERMES_HOME/.env

Scenario 2: "I want fully offline, no-API-key memory consolidation"

Install llama-cpp-python and keep the default model. Everything runs locally.

pip install llama-cpp-python
Model auto-downloads on first consolidation run

Scenario 3: "I already use OpenRouter/Anthropic — use that"

Enable the host LLM path. Mnemosyne will call back to Hermes's own LLM provider

for consolidation. No extra API keys, no local model.

echo 'MNEMOSYNE_HOST_LLM_ENABLED=true' >> $HERMES_HOME/.env
rm -rf $HERMES_HOME/mnemosyne/models/  # optional: clean up the dead weight

Diagnosing Mnemosyne

# Full health check
mnemosyne_diagnose

Quick check: is the LLM path working?
python3 -c "
from mnemosyne.core.local_llm import llm_available
print('LLM available:', llm_available())
"

Check if the model is on disk
ls -lh $HERMES_HOME/mnemosyne/models/*.gguf

Key things to look for in mnemosyne_diagnose output:

• ctransformers: "OPTIONAL" is fine — it's the legacy fallback
• embeddings_available: should be "YES" (semantic search)
• MNEMOSYNE_LLM_ENABLED: "unset" means defaulting to true

File Layout

$HERMES_HOME/
├── .env                          # Set Mnemosyne env vars here
├── config.yaml                   # Hermes config (memory.enabled, etc.)
└── mnemosyne/
    ├── models/
    │   ├── MiniCPM5-1B-Q4_K_M.gguf   # Default local model
    │   └── .cache/huggingface/        # HF download cache
    └── data/
        └── mnemosyne.db               # SQLite memory store

Pitfalls

• Model downloads silently and looks like bloat. No warning, no prompt — Mnemosyne just pulls the 657 MB GGUF from Hugging Face the first time it needs local inference. If disk space matters, pre-configure a remote or host backend before the first consolidation run.
• The model downloads even when it can't run. There's no pre-flight check for llama-cpp-python or ctransformers before downloading. The download and the inference loading are separate steps.
• MNEMOSYNE_HOST_LLM_ENABLED does nothing without a registered backend. The env var alone isn't sufficient — the Hermes host must also register its LLM backend with Mnemosyne. But the Hermes integration handles this automatically; just set the env var and restart.
• Context budget mismatch. LLM_N_CTX (2048) is calibrated for MiniCPM5-1B. When using the host LLM path with a 128K-context model, HOST_LLM_N_CTX (32000) kicks in. Forgetting to set MNEMOSYNE_HOST_LLM_N_CTX when using a large-context remote model means memories get unnecessarily chunked into tiny pieces.
• MNEMOSYNE_LLM_ENABLED=false kills ALL LLM paths, including host and remote. It's the master kill-switch. Use it only when you want pure AAAK encoding with zero LLM involvement.
• Env vars need a restart. Changes to .env don't take effect until Hermes restarts (/restart in chat, or gateway restart for messaging platforms).

Supporting Files

• references/local-llm-internals.md — Deep dive into local_llm.py: download behavior, backend priority, prompt budget math, consolidation flow, and system-specific context from the investigation session.