Move files into one folder

Last published : Nov 09, 2026
This guide shows you how to move the files Knowledge Worker Agent keeps in a workspace into one folder, check what would move first, and move them back.
Earlier releases kept their files in several places in the home folder: the database, chats, projects, and configuration. Current releases keep everything in one folder, ~/Knowledge_Worker_Agent. A workspace from an earlier release moves its files there once. For where each file goes, see Storage locations.
The move is off by default. You turn it on with KWA_MIGRATE.
Related information
Administer Knowledge Worker Agent

How the move protects data

  • Nothing is copied or deleted. Each file and folder is renamed into place, on the same disk.
  • Stored paths follow. Paths in the database are rewritten, and each opencode session is pointed at its chat's new folder. Links inside the moved folders are rewritten too.
  • Every change is recorded first. If the move fails, everything is set back. If the workspace stops during the move, the move is undone at the next start, and runs again.
  • Backups are taken first. Both databases are copied, and each affected opencode session is exported. The backups are removed 30 days after the move.
Files that mention an old path in their contents, such as scripts, aren't edited. The report lists them.

Check what would move

  1. Set KWA_MIGRATE=dry-run for Knowledge Worker Agent, and restart it.
  2. Search the log for One-folder migration, dry run: nothing has changed. The lines after it list each place that would move, its size, how many stored paths and sessions would change, and the files that mention an old path.
Nothing changes. Users see a banner, Your files will move into one folder, with how long the move takes and how much free disk space it needs.
You can also run the dry run from a terminal in the workspace:
knowledge-worker-agent migrate dry-run
It prints the report and exits with 0 when nothing would stop the move.
A location set with a legacy setting to a custom value isn't moved. The report lists it as Kept where it is. For the legacy settings, see Environment variables.

Move the files

  1. Make sure the workspace has the free disk space the dry run reports. The space is used for the backups.
  2. Set KWA_MIGRATE=on, and restart Knowledge Worker Agent.
While the files move:
  • Knowledge Worker Agent is unavailable. Its port shows a status page, Reorganizing your files, with the progress.
  • /api/status reports migrating.
  • The workspace counts as busy, so it isn't stopped for being idle.
  • Don't stop or restart the workspace. If it stops anyway, nothing is lost.
When the move finishes, Knowledge Worker Agent starts as usual. The log shows a line such as One-folder migration: done: 12 places moved, …. The full report is in a folder in ~/Knowledge_Worker_Agent/.system/migration.
To move the files without starting the server, stop Knowledge Worker Agent, then run knowledge-worker-agent migrate on.

If there isn't enough disk space

Users see Files can't move into one folder yet, with how much space is needed, how much is free, and how much to free up. Nothing has changed, and they can keep working. Free up the space, then restart the workspace.

If the move fails

Everything is set back, and nothing is lost. Users see Moving your files failed. Knowledge Worker Agent doesn't try again until the next release. Check the log for lines that start with ✗ One-folder migration.

Move the files back

  1. Set KWA_MIGRATE=undo, and restart Knowledge Worker Agent.
The undo runs the same way as the move, with the same checks, backups, and status page. It keeps everything created since the move, including new chats. It works at any time, also after the backups have been removed.
To undo without starting the server, stop Knowledge Worker Agent, then run knowledge-worker-agent migrate undo.

Go back to an earlier release

Undo the move first, then install the earlier release. An earlier release doesn't know the new folder. It starts with an empty database, and new chats go into that database.
If an earlier release ran after the move anyway, the current release warns at its next start. The log says has appeared since the migration, and users see Some chats aren't shown.