Back up, restore, and upgrade

Make a portable backup

Export to a new directory:

mash export /absolute/path/to/new-backup

This saves your indexed conversations and retained attachments. Keep your configuration and credentials separately; models and the agents’ original history files are not included.

Keep backups private. They can contain sensitive text and credentials, even when those credentials are masked in search results.

Restore without replacing your current history

Use a compatible Mash release and a new destination:

mash import /absolute/path/to/new-backup --into /absolute/path/to/restored.sqlite3
mash --db /absolute/path/to/restored.sqlite3 index --rebuild-local-views --full
mash --db /absolute/path/to/restored.sqlite3 search 'a word you remember' --local

Keep the local search service running. The restored copy is separate from your usual index; keep passing --db to use it. If you use a custom configuration or model directory, also pass --config PATH or --models-dir PATH.

Upgrade an existing installation

Mash upgrades schema-62 through schema-65 databases in place to schema 66 when opening them for writing. Run mash index with the new release after stopping old watchers and agent connections. The shared server uses the same migration when opening each node’s database. The upgrade preserves history, identities and existing chat search data; it does not require a Qdrant rebuild. Schema 66 retires open questions as a kind of saved record: any that exist are deleted, with their revisions and the links that resolved them. Decisions, preferences and facts are untouched. Read-only commands never migrate a database. Restart agent connections and watchers after the upgrade.

This release needs Qdrant 1.20 or later. Upgrade Qdrant first: stop the 1.19 service, start 1.20 on the same storage, then install the new Mash and run mash index once. That run adds a word-search index to your existing search data; it does not rebuild it or recompute embeddings. Until it has run, search reports that the views need upgrading. Qdrant storage opened by 1.20 should not be opened by 1.19 again, so back up first if you may need to go back.

For shared indexing, upgrade the server and publishing nodes to a matching release. The synchronization handshake rejects older peers that cannot publish native records. A protocol mismatch does not require deleting or rebuilding valid chat search data. Upgrade the server’s Qdrant to 1.20 before starting the new mash-server; it adds the word-search index when it starts.

Earlier schemas, including schema 54, are not supported by this migration. Use the export/import fallback below for those versions. Do not change database version numbers by hand.

Back up before replacing Mash, and keep the old executable until you have checked that the new version can read your history.

If your configuration contains views.query.experimental_gpu_reranking, remove that setting. Experimental GPU reranking has been removed; contextual reranking uses CPU. This configuration change does not require reindexing or new models.

Legacy remote-provider settings are unsupported. Replace old [embeddings] settings with the explicit local/remote configuration described in embedding inference, and remove redaction.remote_embeddings. Server configuration still rejects these settings. If you previously used a different embedding model, run mash models install to install the local query model and rebuild local views with mash index --rebuild-local-views --full. Existing local-model installations and their vectors remain valid.

For a shared index that used a different embedding space, coordinate the upgrade across its server and nodes. Install models on the server, then explicitly activate and replay its views with mash-server --server-config PATH --models-dir PATH --activate-views --replay-views. This rebuilds search data from retained shared history; it does not replace silver. Keep a backup and allow for search downtime during replay.

If Mash reports an unsupported older index, ordinary indexing cannot upgrade it. Export with the version that wrote the index, then test an import with the new version at a separate path:

/path/to/old/mash export /absolute/path/to/new-backup
/path/to/new/mash import /absolute/path/to/new-backup --into /absolute/path/to/staged.sqlite3 --keep-identity

Use --db PATH with the old executable if your index is outside its default location. Some older backups are incompatible too: if import fails, keep the original data and executable. Do not delete the index or edit version numbers.

The --keep-identity option is for replacing an installation. Stop the old watcher and agent connections before switching to the replacement; do not publish from both copies at once. At the replacement’s final path, run:

mash --db /absolute/path/to/replacement.sqlite3 index --rebuild-local-views --full
mash --db /absolute/path/to/replacement.sqlite3 status

Continue passing --db when the replacement is outside the default location, including in your agent’s MCP setup. Restart your agents and watchers after upgrading.

If you share history, upgrade the server and machines together. A local export is not a complete shared-server backup; have the server administrator preserve the existing installation before changing it.