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

> Effortlessly migrate PAI v2.5 to v3.0. Learn how to preserve your settings.json and personal content by treating the upgrade as a fresh install. Get the most out of your PAI upgrade.

- Repository: [Daniel Miessler 🛡️/Personal_AI_Infrastructure](https://github.com/danielmiessler/personal_ai_infrastructure)
- Tags: migration-guide
- Published: 2026-02-16

---

**Migrating from PAI v2.5 to v3.0 requires treating the upgrade as a fresh installation while preserving your [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Tools/BackupRestore.ts) script handles backup creation and migration analysis. Run the following from the repository root:

```bash
bun Tools/BackupRestore.ts backup

```

This creates a timestamped directory at `~/claude-backup-YYYYMMDD-HHMMSS` containing your entire v2.5 environment, including [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Tools/BackupRestore.ts#L9-L10)).

### 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:

```bash
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:

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

```

The installer reads the existing [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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:

```bash

# 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:

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

```

This command scans for [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/settings.json) sections, custom hooks, private skills, and memory directories, reporting exactly what can be merged into the fresh install ([source lines 76‑80](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Tools/BackupRestore.ts#L76-L80)).

### 4. Verify the Migration

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

```bash
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:

```bash
#!/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/PAI-Install/install.sh) | The v3.0 installer script that respects existing [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/BackupRestore.ts) tool to see all existing backups with their timestamps and contents:

```bash
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`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/settings.json), hooks, and skills. Review this list to identify the most recent valid backup before proceeding with the v3.0 migration.