Upgrades and Compatibility

This page says what stays the same when you update AI Knowledge Fabric, what happens to Topics and Agents that are running during the update, and how an update to a new major version will work.

The short version:

  • Updates inside one major version never break anything. Everything you set up with one 1.x version keeps working with every later 1.x version.

  • Running Topics and Agents keep running. They get the new version when you stop and start them in the app.

  • Make a backup before every update. Going back to an older version is not supported.

1. What an update keeps

The version number has three parts, for example 1.2.3. The first number is the major version. As long as it stays the same, an update keeps:

  • your Topics, GraphRAG Topics, Agents and Pipelines, with all their settings,

  • the documents you uploaded — you do not have to upload them again,

  • users, roles, API tokens, and the settings on the admin pages,

  • the settings in your .env file and in the Compose or Kubernetes files: their names and their meaning,

  • the Management REST API: scripts and tools that call it keep working. An update may add new fields to the answers, so a script should ignore fields it does not know.

An update inside a major version can add new functions and settings. A new setting always has a default that keeps the old behaviour, so you do not have to change anything.

Changes that would break something come only with a new major version, for example 2.0. The release notes announce them.

2. Topics and Agents during an update

A Topic, GraphRAG Topic or Agent that runs while you update the app keeps running. Chat and upload keep working, also with the new app.

It gets the new version when you stop and start it in the app. Do this when it suits you, for example outside working hours. Until then:

  • New functions of the update that need the Topic or Agent itself are not available on it yet.

  • It still works with the other Topics and Agents, also the ones you have already restarted.

After the restart it uses its existing data. Nothing has to be uploaded again.

3. Updating to a new major version

When a new major version (for example 2.0) comes out, follow these steps:

  1. Update to the last version of your current major version first, for example the last 1.x. A new major version can only be installed on top of that one.

  2. Read the release notes. They say what changes, and whether some Topics need their documents uploaded again.

  3. Make a backup of the database and the volumes. See Backup.

  4. Update the app. It takes over its database by itself on the first start.

  5. Stop and start every Topic, GraphRAG Topic and Agent. Until you do, they are shown as needing an upgrade, and you cannot chat with them or upload to them.

There is no way back to the old major version except restoring the backup from step 3.

4. Keep the versions together

The app, the Topic image, the GraphRAG image and the Agent image belong together. Do not set one of them to another version. A mix of versions is not supported, and the promises on this page do not apply to it. See Supported settings for the version settings.