Hermes: Mnemosyne long-term memory

1. What? — Definition and context

An agent that forgets everything between two conversations is just a chatbot with tools. What distinguishes Hermes from a one-off LLM call is that it accumulates: what is said on Monday is still available on Thursday.

Mnemosyne is the external memory provider that delivers this persistence — a local SQLite database with hybrid vector + FTS5 search and background capture on every turn.

What Mnemosyne replaces

Hermes’ native memory is a MEMORY.md file re-injected into the system prompt. Simple and readable, but it plateaus quickly.

	Native MEMORY.md	Mnemosyne
Storage	A Markdown file	SQLite database
Search	None — everything is re-injected	Hybrid: vector + FTS5
Budget	Character cap in the prompt	Selective recall driven by the query
Capture	Explicit write	Background task on every turn
Structure	Free text	Episodes, temporal triples, graph

The native file is not removed for all that: it stays in place and becomes the active memory again if the external provider is disabled.

Active configuration

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  provider: mnemosyne
  nudge_interval: 10
  flush_min_turns: 6

Two distinct budgets: memory_char_limit for what the agent has retained, user_char_limit for the user profile it builds up across exchanges.

---

2. Why? — Stakes and motivations

Why wrapper mode rather than a custom image?

This is the structuring decision of the installation. Three routes were possible:

Route	Cost	Problem
Custom image	A Dockerfile extending the upstream image	Breaks the DIUN flow: no more automatic detection of upstream updates, manual rebuild on every version
Patching /opt/hermes	Modifying the application tree inside the container	Overwritten on every image update
Wrapper mode	Side venv + plugin, entirely under /opt/data	Survives recreates and image updates

Wrapper mode wins because /opt/data is a bind mount: everything living there is outside the image lifecycle. The container stays strictly the upstream image, DIUN keeps detecting new versions, and there is nothing to rebuild.

The price to pay

The container memory limit goes from 2 to 3 GB — the mnemosyne-memory[embeddings] profile bundles fastembed and its ONNX models, which run locally. On a 16 GB VPS that is the most expensive item in the ai-stack after Qdrant and CLI Ollama. In practice the container stays under 500 MiB at rest.

Why local-first?

Capture runs on every turn, over everything passing through the conversation: meeting notes, technical decisions, information about contacts. Sending that stream to an external vectorisation service would amount to continuously exporting the content of the exchanges.

Mnemosyne computes its embeddings locally and stores everything in a SQLite file on the data volume. No conversation data leaves the VPS to be indexed.

---

3. How? — Technical implementation

Where everything lives

Item	Path
Side venv (mnemosyne-hermes → mnemosyne-memory[embeddings])	/opt/data/.mnemosyne/venv
Plugin shim + manifest (discovery by Hermes)	/opt/data/plugins/mnemosyne/
Bundled skill	/opt/data/skills/memory/mnemosyne-memory-override/
SQLite database	/opt/data/mnemosyne/data/mnemosyne.db

Activation is a single line: memory.provider: mnemosyne in the config file.

The exposed tools

The plugin declares 20 tools and 3 hooks (pre_llm_call, on_session_start, post_tool_call):

Family	Tools
Memory	mnemosyne_remember, mnemosyne_recall, mnemosyne_update, mnemosyne_forget, mnemosyne_invalidate
Graph and triples	mnemosyne_triple_add, mnemosyne_triple_query, mnemosyne_graph_query, mnemosyne_graph_link
Scratchpad	mnemosyne_scratchpad_write, mnemosyne_scratchpad_read, mnemosyne_scratchpad_clear
Consolidation	mnemosyne_sleep
Transfer	mnemosyne_export, mnemosyne_import, mnemosyne_sync_push, mnemosyne_sync_pull, mnemosyne_sync_status
Diagnostics	mnemosyne_stats, mnemosyne_diagnose

The hooks do the invisible work: on_session_start loads the relevant context, pre_llm_call injects the recall into the prompt, post_tool_call captures what deserves keeping.

Consolidation through 'sleep'

mnemosyne_sleep triggers a consolidation pass: episode grouping, deduplication, promotion of recurring facts. By default it uses no LLM. The MNEMOSYNE_HOST_LLM_ENABLED=true option routes those calls to Hermes’ Codex client — finer, but it consumes the shared ChatGPT quota, hence the choice to leave it disabled.

Operations

# Is the provider actually active?
docker exec hermes hermes memory status     # → Provider: mnemosyne, available

# Database statistics
docker exec --user hermes -e HOME=/opt/data -e HERMES_HOME=/opt/data hermes \
  /opt/data/.mnemosyne/venv/bin/mnemosyne stats

# Update
docker exec --user hermes -e HOME=/opt/data hermes \
  /opt/data/.mnemosyne/venv/bin/pip install --no-cache-dir -U mnemosyne-hermes
docker compose -f ai-stack/docker-compose.yaml restart hermes

The wrapper goes stale after a Python bump

The side venv points at the image’s interpreter. If an image update moves Python from one minor version to the next, the site-packages are no longer importable and the provider silently falls “stale”. The repair is a full reinstall:

docker exec --user hermes -e HOME=/opt/data hermes \
  /opt/hermes/.venv/bin/python3 -m venv --clear /opt/data/.mnemosyne/venv
docker exec --user hermes -e HOME=/opt/data hermes \
  /opt/data/.mnemosyne/venv/bin/pip install --no-cache-dir mnemosyne-hermes
docker exec --user hermes -e HOME=/opt/data -e HERMES_HOME=/opt/data hermes \
  /opt/data/.mnemosyne/venv/bin/mnemosyne-hermes install --mode wrapper --force \
  --python /opt/data/.mnemosyne/venv/bin/python
docker compose -f ai-stack/docker-compose.yaml restart hermes

That is the flip side of wrapper mode: it decouples the installation from the image, but not from its interpreter.

memory off, never tools disable memory

To go back to native memory the command is hermes memory off — it disables the external provider and lets MEMORY.md take over. hermes tools disable memory does something else entirely: it removes the whole memory toolset, native included. The agent then loses every memorisation capability, not just Mnemosyne.

Backup

The database goes into the daily backup. The venv and the fastembed model cache are excluded: they are heavy and reinstall in one command.

A consequence worth knowing for a restore: the database comes back as-is, but the venv has to be recreated before the provider becomes available again.

---

4. What if? — Outlook and limits

Current limits

Limit	Impact	Mitigation
Memory tied to the container	A second user would share the same memory and the same profile	One container per user rather than a widened allowlist
Consolidation without an LLM	Episode grouping stays mechanical	MNEMOSYNE_HOST_LLM_ENABLED=true, at the cost of quota
Opaque content	The SQLite database is not readable in Obsidian	Export as markdown notes, planned
Wrapper fragile to a Python bump	Silent failure after an image update	Check hermes memory status after every update
No memory shared with the workstation	What Hermes knows, the local assistant does not	Bidirectional sync, planned

Evolution scenarios

If memory has to become readable:

• Export memories as markdown notes into vps-vault, with provenance frontmatter.
• The point goes beyond reading: memory versioned in Git becomes auditable and correctable by hand.
• The mnemosyne-operations skill already covers the governance of that export.

If memory has to be shared between the agent and the workstation:

• The mnemosyne_sync_push / mnemosyne_sync_pull tools already exist on the plugin side.
• What remains is choosing the source of truth on conflict, and deciding whether client-side encryption is needed.

If volume becomes a problem:

• mnemosyne_invalidate and mnemosyne_forget already allow targeted pruning.
• A regular consolidation pass compresses better than brutal deletion.

---

Related pages

Hermes

• Hermes Agent — The deployment and its security model
• Plugins — Mnemosyne is one of the four active plugins
• Skills — mnemosyne-operations, the memory governance procedure

Infrastructure

• Database backup — The database is backed up, the venv is not
• AI Stack — Qdrant, the infrastructure’s other vector database

Reference

• Glossary — Long-term memory, Embeddings, Vector Database