Upgrade the server

Before you start

1. Read the release notes in the changelog for anything marked as requiring action.
2. Tell users there will be a short interruption. Requests during the restart fail and clients show an error; nothing is written half-way.

Docker Compose

cd total-agent-memory
git pull                                                  # or check out the release tag
docker compose -f docker-compose.team.yml stop team-memory
docker compose -f docker-compose.team.yml run --rm -v /srv/tam-backups:/backups team-memory \
  python /app/src/team_memory/cli.py backup --out /backups/pre-upgrade-$(date +%Y%m%d)
docker compose -f docker-compose.team.yml build
docker compose -f docker-compose.team.yml up -d
curl -s http://127.0.0.1:3738/healthz                     # "version" shows the new release

The backup above runs with the old image, before build. The image name defaults to total-agent-memory:<version>; set TAM_TEAM_IMAGE in .env if you tag images yourself.

Python package

# stop the server, then:
tam-team --root /srv/tam-team backup --out /backups/pre-upgrade-20260925
/opt/tam-team/.venv/bin/python -m pip install -U total-agent-memory
# start the server again
curl -s http://127.0.0.1:3738/healthz

After the upgrade

• Check /healthz shows the new version and sign in to the web interface with a test token.
• Ask one person to run “list my memory scopes” and a search.
• Clients do not need updating unless the release notes say so. If you distributed remote.py by copying it, compare it with the new version and redistribute it if it changed.

Rolling back

Stop the server, reinstall the previous version (previous image tag, or pip install total-agent-memory==<old version>), restore the pre-upgrade backup into a new directory or volume, and start the server on it. Do not run an older release against data a newer release has already opened.