Backup and Restore

Backup & Restore

Mnemolis's entire persisted state lives in exactly six files, all under /app/data inside the container:

File	What it holds
cache.json	The result cache
routing_cache.json	The routing cache
query_log.db	The query log — every request's timestamp, source, success, latency, and fallback flag
snapshots.db	Snapshot history for the background diff engine
adversarial_testing.db	Adversarial self-testing combination history — synthetic generated queries only, never real user queries
temporal_patterns.db	Cross-source temporal pattern detection event history and mined pattern candidates

GET /backup tars all six into a downloadable .tar.gz. GET /backup/info shows what's currently in each file (size, last-modified time) without actually creating a backup — useful for a quick "is this worth backing up right now" check.

What's deliberately not in the backup

Kiwix ZIM files, your docker-compose.yml, and searxng/settings.yml aren't included. /backup only covers Mnemolis's own internal state — back up your ZIM files and compose configuration separately, as part of your normal homelab backup routine. None of these would be useful to restore without the rest of your actual deployment configuration intact anyway.

A real gotcha worth knowing before you need it: volume naming

Docker Compose automatically prefixes named volumes with your project name, which defaults to whatever folder docker-compose.yml lives in. A volume declared as mnemolis_data in your YAML doesn't actually get created with that exact name — if your folder is minisearch/, the real volume Docker creates is minisearch_mnemolis_data.

This matters specifically the moment you try to restore manually with docker run -v, because that command needs the real volume name, not the name written in the YAML. Always check first:

docker volume ls | grep data
# or, for a running container, the most direct check:
docker inspect mnemolis --format '{{json .Mounts}}' | python3 -m json.tool

docker inspect against the actual running container is the more reliable of the two — it shows you exactly which host path or named volume is genuinely mounted where, right now, rather than asking you to infer it from a list of volume names that might not obviously correspond to the right container.

If you want a stable, predictable volume prefix regardless of what the folder happens to be named, set it explicitly:

echo "COMPOSE_PROJECT_NAME=mnemolis" > .env

Restoring

docker compose down

docker run --rm -v mnemolis_data:/app/data -v $(pwd):/backup alpine \
  sh -c "cd /app/data && tar xzf /backup/mnemolis-backup.tar.gz"

docker compose up -d

Replace mnemolis_data in that command with whatever docker volume ls actually reported — not the bare name from docker-compose.yml — if you haven't set COMPOSE_PROJECT_NAME.

Why this volume-naming detail earned its own section

It's the kind of thing that looks like a Mnemolis bug the first time it bites someone — a restore command that silently does nothing, or appears to succeed while writing into a volume nothing's actually mounting — when the real cause is just Docker Compose's own naming convention being non-obvious. Worth checking the real volume name before assuming anything's broken, the same instinct that mattered when diagnosing The SearXNG Timeout Lesson — verify what's actually true on disk and in the running container before trusting what a config file or command should have done.