Upgrade an Existing Installation
1
Record the current environment
Run these commands from your project repository:Keep the output for comparison after the upgrade.
2
Pause writers and make a backup
Pause background Brain work:Wait for active work to finish. Stop other writers that share this local store.
Other agents can still run commands that write to this store.Back up the complete Brain data directory and the repository’s
checkpoint refs.
Include the global store if you use it. Keep the backup separate from the
active data directory. Confirm that you can read the backup before continuing.
3
Update Graph and Brain
Check how each plugin was installed:Update Graph before Brain. For each plugin installed from the index or a
repository URL, run its upgrade command:This replaces that plugin’s registered local executable with a release installation.Plugin upgrades preserve version pins. If a pinned version is too old, choose
a compatible version before continuing. Reinstalling without Automatic cleanup requires Brain v0.5.1 or later. See
installation options for compatible
Graph versions. Check the release notes
for additional upgrade steps in a newer version.
plugin upgrade cannot update a plugin installed from a local executable path.
This includes Brain installations made with get-brain.sh.For a local installation, rerun its installer or rebuild its source checkout.
To replace it with a released plugin, run the corresponding install command:--pin removes
the existing pin. See Upgrade Plugins
for pin and installation behavior.Check the installed versions:4
Refresh the agent instructions
Before setup, read Agent Instructions
to check which files are replaced or preserved.Run setup in each repository that uses Graph and Brain:Graph setup also adds a Claude Code SubagentStart hook to the per-user,
untracked
.claude/settings.local.json. It merges the hook into existing
settings. Add --no-claude-hook to the Graph command to skip this hook.
See Set Up Graph for details.Brain’s --no-backfill flag skips extraction from past sessions.Review and commit the updated instruction files.
Keep .claude/settings.local.json untracked. Restart your coding agent
or reload its repository instructions before continuing work.5
Resume normal activity
Resume background work if you paused it:Brain migrates storage and removes verified legacy copies during normal
writes, refreshes, and background work. No migration or cleanup command is
required. Large stores can need several passes before cleanup finishes.
6
Verify the result
Check repository storage and overall status:If you use global memories, also check their store:After migration, the format is
repository, with schema version 3.
Confirm that expected memories remain available. Migration combines copies
with the same memory ID and keeps their source references. The number of
stored copies can decrease while the number of unique memories stays the same.Keep the backup until you have checked your memories and storage status.What Cleanup Removes
Brain verifies each legacy record, including its source references and whether it was retracted, before removing the copy. Files that Brain cannot verify remain available for recovery. The active store, retained sessions, and checkpoint history still use disk space. Disk savings depend on how many redundant copies your store contains. Cleanup can finish over several passes. Do not delete the active store, checkpoint refs, or unverified recovery files to reclaim space. If retained recovery data needs attention, keep the files and ask for help in Discord. Have the storage status output available.Recover an Interrupted Migration
If the process stops during migration or cleanup, resume normal Brain activity. Brain uses its saved progress to continue. Do not restore old branch copies over the active store or remove recovery files to force another attempt. If Brain reports corruption, preserve the data directory and your backup. Stop other writers and ask for help in Discord before changing those files.Use an Older Version
Brain v0.2.0 to v0.4.0 cannot read the migrated local store. There is no supported in-place storage rollback command. To use an older version, restore a complete pre-migration backup into a separate environment. That backup does not contain writes made after the backup. Do not point an older client at the upgraded directory. Older and newer clients can exchange hosted memories through separate local stores. See Storage and Sync.Command Changes
memories storage rollbackis removed.- The old
facts promoteandfacts reviewworkflows are removed. Memories no longer need promotion between branch stores. factsremains an alias for supportedmemoriescommands. The alias does not restore removed subcommands.entire brain setupreplaces the removedinit-agentscommand for generated agent instructions.- Brain v0.5.1 does not provide the previously documented
mcpcommand. Use the CLI agent integration.