Migrating from PAI v2.5 to v3.0: How to Preserve Your Settings

Migrating from PAI v2.5 to v3.0 requires treating the upgrade as a fresh installation while preserving your settings.json file and personal content directories before running the new installer.

Upgrading the Personal AI Infrastructure (PAI) from the v2 series to the rewritten v3.0 release involves a complete re-installation of the core system. Because the installer and internal algorithm representation have changed fundamentally, you must manually preserve your identity settings, API keys, and custom content. This guide walks through the exact process using the official BackupRestore.ts utility and source files from the danielmiessler/Personal_AI_Infrastructure repository.

Why PAI v3.0 Requires a Re‑install

The v3.0 release (codenamed "O") replaces the entire installation engine found in v2.x (codenamed "S"). According to the source code in Releases/v3.0/.claude/PAI-Install/install.sh, the new installer generates a fresh directory structure and only respects existing configuration if it finds a settings.json file present before execution. If the file is absent, the installer creates default values for daidentity, principal, and hooks, effectively resetting your personal setup.

Pre‑migration: Backing Up Your PAI v2.5 Installation

Before touching the v3.0 installer, create a complete snapshot of your current ~/.claude directory. The repository provides a dedicated TypeScript tool for this purpose.

Using the BackupRestore Tool

The Tools/BackupRestore.ts script handles backup creation and migration analysis. Run the following from the repository root:

bun Tools/BackupRestore.ts backup

This creates a timestamped directory at ~/claude-backup-YYYYMMDD-HHMMSS containing your entire v2.5 environment, including settings.json, custom hooks, and private skills. The tool specifically records the presence of configuration files and user directories to facilitate later restoration (source lines 9‑10).

Manual Backup of Critical Files

If you prefer manual control, ensure you copy these specific paths:

• ~/.claude/settings.json – Contains API keys, DA identity, timezone, and hook configuration
• ~/.claude/hooks/ – Custom automation scripts
• ~/.claude/skills/_* – Private skills (prefixed with underscore)
• ~/.claude/MEMORY/ – Long‑term observation archives
• ~/.claude/USER/ – Personal user data

Step‑by‑Step PAI v2.5 to v3.0 Migration Process

Once your backup is secure, proceed through these four phases to complete the migration while preserving your settings.

1. Preserve settings.json Before Installation

The v3.0 installer checks for ~/.claude/settings.json at runtime. To prevent default generation, copy your v2.5 settings file into place before executing the install script:

cp ~/claude-backup-<timestamp>/settings.json ~/.claude/settings.json

This file holds your daidentity (name, voice, color), principal (timezone, username), and API credentials that the installer will reuse rather than regenerate.

2. Run the v3.0 Installer

With settings preserved, execute the new installer:

cd Personal_AI_Infrastructure/Releases/v3.0
cp -r .claude ~/
cd ~/.claude && ./PAI-Install/install.sh

The installer reads the existing settings.json to maintain continuity. If you skip step 1, the installer creates a fresh default configuration, effectively resetting your identity and keys.

3. Migrate Personal Content and Hooks

After installation completes, restore your custom assets from the backup:

# Custom hooks

cp -r ~/claude-backup-<timestamp>/hooks/* ~/.claude/hooks/

# Private skills (underscore prefix)

cp -r ~/claude-backup-<timestamp>/skills/_* ~/.claude/skills/

# Memory archives

cp -r ~/claude-backup-<timestamp>/MEMORY ~/.claude/

You can also use the migrate command to analyze your backup and list candidates for restoration:

bun Tools/BackupRestore.ts migrate claude-backup-<timestamp>

This command scans for settings.json sections, custom hooks, private skills, and memory directories, reporting exactly what can be merged into the fresh install (source lines 76‑80).

4. Verify the Migration

Restart your Claude Code client to load the new v3.0 environment. Run a quick validation:

pai status

# Or test a custom skill

pai skill <your-private-skill>

Confirm that your DA identity (name, voice settings) and API configurations match your previous v2.5 setup.

Automated Migration Script

For users managing multiple environments or seeking a repeatable process, combine the steps into a single bash script:

#!/usr/bin/env bash
set -euo pipefail

# Configuration

REPO_ROOT="$(git rev-parse --show-toplevel)"
BACKUP_NAME="pre-v3-migration-$(date +%Y%m%d-%H%M%S)"

# 1. Create backup

echo "Creating backup..."
BACKUP_DIR=$(bun "$REPO_ROOT/Tools/BackupRestore.ts" backup --name "$BACKUP_NAME")
echo "Backup created at: $BACKUP_DIR"

# 2. Stage v3.0 files

echo "Staging v3.0 installation..."
cp -r "$REPO_ROOT/Releases/v3.0/.claude" ~/

# 3. Restore settings before install

echo "Restoring settings.json..."
cp "$HOME/$BACKUP_DIR/settings.json" ~/.claude/settings.json

# 4. Run installer

echo "Running v3.0 installer..."
cd ~/.claude && ./PAI-Install/install.sh

# 5. Migrate personal content

echo "Migrating personal content..."
for dir in hooks skills/_* MEMORY; do
  if [[ -d "$HOME/$BACKUP_DIR/$dir" ]]; then
    cp -r "$HOME/$BACKUP_DIR/$dir" ~/.claude/
  fi
done

echo "Migration complete. Restart your Claude client to verify."

Save this as migrate-to-v3.sh, make it executable (chmod +x), and run it from the repository root.

Key Files and Their Roles in Migration

Understanding these specific files in the danielmiessler/Personal_AI_Infrastructure repository ensures you target the correct assets during your migration:

File	Purpose	Migration Action
Tools/BackupRestore.ts	CLI utility that creates snapshots and analyzes migration candidates	Run backup and migrate commands to identify transferable content
~/.claude/settings.json	Unified configuration file containing daidentity, principal, API keys, and hook settings	Copy from v2.5 backup to new install before running installer
Releases/v3.0/.claude/PAI-Install/install.sh	The v3.0 installer script that respects existing settings.json or generates defaults	Execute after placing preserved settings; handles core system setup
~/.claude/hooks/	Custom automation scripts and user-defined hooks	Copy from backup after installation completes
~/.claude/skills/_*	Private skills (prefixed with underscore) not part of core distribution	Restore from backup to retain custom capabilities
~/.claude/MEMORY/	Long-term observation archives and conversation history	Migrate from backup to maintain continuity

Summary

• Migrating from PAI v2.5 to v3.0 is a re‑install, not an in‑place upgrade, because the v3.0 installer rebuilds the core system from scratch.
• Preserve settings.json first – this single file contains your identity, API keys, and hook configuration; place it in ~/.claude/ before running the v3.0 installer to prevent default generation.
• Use Tools/BackupRestore.ts – the backup command snapshots your entire v2.5 environment, while the migrate command analyzes what content (hooks, private skills, memory) can be transferred.
• Migrate personal content after installation – copy custom hooks, private skills (folders prefixed with _), and MEMORY/ directories only after the installer completes to avoid conflicts with the new directory structure.
• Verify identity and functionality – restart your Claude client and test a custom skill or the pai command to confirm your DA identity and settings survived the migration.

Frequently Asked Questions

Can I upgrade PAI v2.5 to v3.0 without losing my API keys?

Yes, provided you copy your settings.json file from the v2.5 installation into ~/.claude/ before executing the v3.0 installer. The installer checks for this file at runtime and reuses your existing API credentials, identity settings, and hook configuration rather than generating new defaults. If you run the installer without restoring settings.json first, you will need to re-enter all API keys manually.

What happens if I run the v3.0 installer without restoring settings.json first?

The installer will treat the installation as a fresh setup and generate a new default settings.json containing generic identity values, blank API keys, and default hook configurations. This effectively resets your DA identity (name, voice, color) and removes your personalized timezone and API credentials. You would then need to manually reconfigure these values or restore the file from a backup after the fact, which may require restarting the installer or manually editing the generated file.

Are custom skills and memory archives preserved during migration?

Custom skills and memory archives are not automatically preserved by the v3.0 installer because it rebuilds the directory structure from scratch. You must manually copy these assets from your v2.5 backup after the installation completes. Specifically, copy private skills (directories prefixed with _ under skills/), custom hooks, and the MEMORY/ directory to the new ~/.claude/ location. The Tools/BackupRestore.ts utility can analyze your backup and list exactly which personal content is available for migration.

How do I list available backups before migrating?

Use the list command provided by the BackupRestore.ts tool to see all existing backups with their timestamps and contents:

bun Tools/BackupRestore.ts list

This outputs each backup directory (e.g., claude-backup-20260114-153000), the creation date, total size, and a summary of contained assets such as settings.json, hooks, and skills. Review this list to identify the most recent valid backup before proceeding with the v3.0 migration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}