Skip to content

Upgrading without losing the assistant

An assistant that has run for months is not an application any more. It is an application plus an accumulated state that took those months to form. Upgrading treats the first part and routinely damages the second, because the two are stored in completely different places and only one of them is in version control.

The three layers, and which one an upgrade touches

Layer Where it lives Replaced on upgrade?
Application code repository yes — wholesale
Configuration environment file should be merge, never overwrite
Accumulated state databases, working files never

Almost every bad upgrade is a violation of row three or a careless implementation of row two.

Rule 1 — the upgrade must know what it is allowed to delete

The only safe way to replace code is an explicit manifest: a list of directories and files that belong to the distribution, replaced wholesale, and everything else left alone. The dangerous alternative is a blanket sync with deletion enabled over the whole project root — it works perfectly until the day someone stores something valuable in a directory the manifest never heard of.

Practical consequence for anyone extending a self-hosted assistant: put your own code in a directory the upgrade does not manage, and load it through a documented extension point. Editing a distribution file directly means your change survives exactly until the next release.

Rule 2 — configuration merges, it never overwrites

New releases add settings. The instinct is to ship a new configuration file. The correct behaviour is append-only: read the existing file, add keys that are missing, never touch keys that already have a value. A single overwrite of a live configuration file can cost hours of re-authorising integrations, and the failure is silent — the process starts fine and simply behaves as though it never met you.

Rule 3 — back up before, verify after, roll back atomically

Before touching anything: one archive of every database, stored outside the directory being upgraded. Not because upgrades usually fail, but because the one that does will fail in a way you did not anticipate.

After: check that the process actually restarted onto the new build. This sounds trivial and is the single most common invisible failure — files replaced, service never reloaded, and every subsequent observation is made against code that is no longer on disk. Log the build identity and start time at boot, and compare them.

And the rollback must be one operation, not a checklist. A partially applied upgrade — new code, old schema — is worse than either state alone.

Rule 4 — schema migrations run forward only, and idempotently

Every migration must be safe to run twice, because eventually it will be. The pattern that survives contact with reality: check whether the change is already present, apply it if not, record that it ran. Migrations that assume a clean starting state break on exactly the installations that have been running longest — the ones with the most data to lose.

Rule 5 — a version number is a promise about compatibility

If an upgrade requires manual intervention, that must be announced before it runs, not discovered afterwards in a log. And a version that has been published is immutable: re-cutting the same number with different content makes every installation's record of what it is running a lie.

The checklist

  1. Archive every database somewhere outside the upgrade path.
  2. Apply code by manifest, never by blanket delete-sync.
  3. Merge configuration, append-only.
  4. Run migrations forward, idempotently.
  5. Restart, then verify the running build is the new one.
  6. Ask the assistant something that requires memory — if it answers from before the upgrade, state survived.

Further reading: self-hosted personal AI assistant · avelina.ai