Skip to content

backup-restore.md

Latest commit

 

History

History
144 lines (101 loc) · 3.94 KB

backup-restore.md

File metadata and controls

144 lines (101 loc) · 3.94 KB

Backup & Restore

Mnemonic stores all data in a single SQLite database at ~/.mnemonic/memory.db. This guide covers backup strategies and disaster recovery.

Quick Backup

mnemonic backup

This creates a timestamped JSON export in ~/.mnemonic/backups/ and automatically keeps only the last 5 backups.

Backup Types

JSON Export

Exports memories, associations, and raw memories as structured JSON:

mnemonic export --format json --output ~/my-backup.json

Pros: Human-readable, importable, format-stable across versions. Cons: Doesn't include SQLite-specific data (patterns, abstractions, episodes, system metadata).

SQLite File Copy

Copies the raw database file:

mnemonic export --format sqlite --output ~/my-backup.db

Pros: Complete copy of all data including patterns, abstractions, and indexes. Cons: May not be compatible across major schema changes.

Automatic Pre-Migration Backups

The daemon automatically creates a SQLite backup before applying schema migrations at startup. These are saved as pre_migrate_<timestamp>.db in ~/.mnemonic/backups/.

Restore from Backup

Restore a SQLite Backup

mnemonic restore ~/.mnemonic/backups/pre_migrate_2026-03-10_143022.db

This will:

  1. Verify the backup file exists and passes PRAGMA integrity_check
  2. Check that the daemon is not running (stop it first with mnemonic stop)
  3. Move the current database aside as memory.db.old
  4. Copy the backup into place as the new memory.db

After restoring, start the daemon:

mnemonic start

Import a JSON Backup

mnemonic import ~/my-backup.json --mode merge

Modes:

  • merge — Add imported memories alongside existing ones (default)
  • replace — Clear existing data and load from backup

Disaster Recovery

Database Deleted

If ~/.mnemonic/memory.db is accidentally deleted:

  1. Check for automatic backups:

    ls -lt ~/.mnemonic/backups/

  2. Restore the most recent one:

    mnemonic restore ~/.mnemonic/backups/<most-recent>.db

  3. If no backups exist, start fresh:

    mnemonic serve   # creates a new empty database

    Then re-ingest important projects:

    mnemonic ingest ~/Projects/my-project --project my-project

Database Corrupted

If mnemonic diagnose reports corruption:

  1. Try restoring from a pre-migration backup (created automatically):

    mnemonic restore ~/.mnemonic/backups/pre_migrate_<latest>.db

  2. Try SQLite's built-in recovery:

    sqlite3 ~/.mnemonic/memory.db ".recover" | sqlite3 /tmp/recovered.db
mnemonic restore /tmp/recovered.db

  3. Last resort — purge and start over:

    mnemonic purge

Embedding Model Changed

If you switched LLM embedding models, existing vector embeddings are incompatible:

  1. The daemon detects this and warns at startup.
  2. Existing memories still work for keyword search (FTS) but semantic search quality degrades.
  3. Options:
    • Switch back to the original model
    • Accept degraded semantic search for old memories (new ones will use the new model)
    • mnemonic purge and re-ingest if semantic quality is critical

Backup Schedule Recommendations

Use Case Strategy
Personal use Run mnemonic backup weekly
Heavy use Run mnemonic backup daily via cron
Before upgrades The daemon does this automatically (pre-migration backup)
Before experiments Manual mnemonic export --format sqlite --output ~/before-experiment.db

Automated Daily Backup (cron)

# Add to crontab: crontab -e
0 3 * * * /path/to/mnemonic --config /path/to/config.yaml backup

Backup Location

All backups are stored in ~/.mnemonic/backups/. The backup command automatically manages retention (keeps last 5). Pre-migration backups are also stored here but are not subject to the retention limit — clean them up manually if needed.