Backup and upgrade

Where the state is

All of it lives under the sodamem-data volume:

path	contents
per-user store files	facts, spans, raw turns
Chroma index	vectors
/data/.control/	job records, named API keys, the request log

Splitting the control plane out means deleting a user's memories never takes the operator's job history with it, and job status survives a restart — GET /v1/jobs/{id} no longer answers 404 for a job that was in flight during a deploy.

Backup

Back it up like any other named volume:

docker run --rm -v sodamem-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/sodamem-data.tar.gz -C /data .

Restore is the same command with tar xzf into an empty volume.

Stop the server first for a consistent snapshot

The stores are SQLite without WAL. A tar of a live volume can catch a write mid-flight. docker compose stop → back up → docker compose start costs seconds and removes the question.

Upgrade

git pull
docker compose up -d --build

The named volume is untouched by a rebuild — only the image changes.

Check schema_version in /health before and after if you are jumping multiple releases. A store-schema bump would need a migration note; none exist yet.

curl http://localhost:8000/health
# {"status":"ok","version":"0.1.1","schema_version":1,"auth":"enabled"}

Rollback

Point the image back at the previous tag and bring it up. Because corrections are ADD-only, a rollback does not have to undo writes — the data written by the newer version is still readable by the older one as long as schema_version matches.

Pre-1.0 compatibility

CHANGELOG.md in the repository states what a pre-1.0 release does and does not promise. Read it before upgrading across a minor version.