Backups & Recovery

Overview

A robust backup strategy ensures state continuity for your agentic memory layer. For a self-hosted sovseal deployment, backups must cover two distinct data structures: the relational metadata/snapshots database and the vector search collection indices.

1. Database Backups (PostgreSQL / pgvector)

All user authentication, API key hashes, transaction logs, and encrypted snapshots reside in your Postgres instance.

Running pg_dump

To perform a hot backup of the relational memory store:

docker exec -t sovseal-db-container pg_dump -U postgres -d sovseal > backup_$(date +%F).sql

Restoring from SQL Dump

To restore your database schemas and snapshot lineages:

1. Re-initialize a blank database:

   docker exec -i sovseal-db-container psql -U postgres -c "DROP DATABASE IF EXISTS sovseal; CREATE DATABASE sovseal;"

2. Import the backup file:

   docker exec -i sovseal-db-container psql -U postgres -d sovseal < backup_date.sql

2. Vector DB Backups (Qdrant / Chroma)

If you are using Qdrant as your vector store provider, back up the vector collections using Qdrant's native Snapshot API.

Create a Collection Snapshot

Run a POST query against the Qdrant instance:

curl -X POST http://localhost:6333/collections/agent_memory/snapshots

This returns a snapshot identifier. The snapshot file is saved inside the container directory at /qdrant/snapshots/.

Restore a Vector Collection

To recover the index from a snapshot file:

curl -X POST http://localhost:6333/collections/agent_memory/snapshots/recover \
  -H "Content-Type: application/json" \
  -d '{"location": "http://localhost:6333/snapshots/agent_memory_backup.snapshot"}'

3. Client Lineage Recovery

Since sovseal enforces VSR (Verified Semantic Recall) with parent-snapshot linkages, restoring a snapshot that breaks the chronological parent hash sequence will trigger client-side validation warnings.

To recover a device state following local cache loss:

1. Configure ~/.sovseal/config.json with the original project_id and encryption_key.
2. The client will query the edge API endpoint for the highest sequence snapshot matching the hashed agent_id.
3. The client downloads the encrypted payload, verifies the SHA-256 integrity hash on the decrypted contents, and repopulates the local LanceDB instance automatically on first boot.