> ## Documentation Index > Fetch the complete documentation index at: https://docs.entire.com/llms.txt > Use this file to discover all available pages before exploring further. # Upgrade and Recover > Upgrade Brain safely, verify automatic migration and cleanup, and recover interrupted work. Brain v0.5.0 introduced one repository memory store. v0.5.1 adds automatic removal of verified legacy copies, including copies retained by v0.5.0. You can upgrade from stable v0.2.0, v0.3.0, v0.4.0, or v0.5.0. See the [v0.5.1 release notes](https://github.com/entireio/entire-brain/releases/tag/v0.5.1) for the full change list. > [!WARNING] > > Local migration is one-way. Brain v0.2.0 to v0.4.0 cannot reopen a migrated store. > Back up the complete data before upgrading. A memory export alone is not a > complete backup. ## Upgrade an Existing Installation **1. Record the current environment** Run these commands from your project repository: ```bash theme={null} entire brain version entire brain path entire brain status --json ``` Keep the output for comparison after the upgrade. **2. Pause writers and make a backup** Pause background Brain work: ```bash theme={null} entire brain stop ``` 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](https://docs.entire.com/guides/checkpoints/checkpoint-storage.md). 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: ```bash theme={null} entire plugin info graph entire plugin info brain ``` Update Graph before Brain. For each plugin installed from the index or a repository URL, run its upgrade command: ```bash theme={null} entire plugin upgrade graph entire plugin upgrade brain ``` `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: ```bash theme={null} entire plugin install graph --force entire plugin install brain --force ``` 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 `--pin` removes the existing pin. See [Upgrade Plugins](https://docs.entire.com/cli-reference/plugin.md#upgrade-plugins) for pin and installation behavior. Check the installed versions: ```bash theme={null} entire graph version entire brain version ``` Automatic cleanup requires Brain v0.5.1 or later. See [installation options](https://docs.entire.com/guides/brain/overview.md#install-entire-brain) for compatible Graph versions. Check the [release notes](https://github.com/entireio/entire-brain/releases) for additional upgrade steps in a newer version. **4. Refresh the agent instructions** Before setup, read [Agent Instructions](https://docs.entire.com/guides/brain/overview.md#agent-instructions) to check which files are replaced or preserved. Run setup in each repository that uses Graph and Brain: ```bash theme={null} entire graph setup --repo . entire brain setup --no-backfill ``` 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](https://docs.entire.com/guides/graph/set-up-graph.md) 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: ```bash theme={null} entire brain start ``` 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: ```bash theme={null} entire brain memories storage status --json entire brain status --json ``` If you use global memories, also check their store: ```bash theme={null} entire brain memories storage status --global --json ``` 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](https://discord.gg/jZJs3Tue4S). 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](https://discord.gg/jZJs3Tue4S) 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](https://docs.entire.com/guides/brain/storage-and-sync.md). ## Command Changes * `memories storage rollback` is removed. * The old `facts promote` and `facts review` workflows are removed. Memories no longer need promotion between branch stores. * `facts` remains an alias for supported `memories` commands. The alias does not restore removed subcommands. * `entire brain setup` replaces the removed `init-agents` command for generated agent instructions. * Brain v0.5.1 does not provide the previously documented `mcp` command. Use the [CLI agent integration](https://docs.entire.com/guides/brain/overview.md#use-brain-from-your-agent).