pi-agent-backup-migrate

Backup, restore, and migrate the complete pi coding agent state across machines.

Agents remember. Machines change. Keep your save file with you.

What it does

Packages the "soul" of your pi setup into a single self-contained tarball:

Included	Excluded (by design)
pi-hermes-memory/ long-term memory	auth.json (API keys — never packaged)
projects-memory/ project memory	*.env (skill/extension secrets)
sessions/ full conversation archive	npm/ bin/ (platform binaries, recreated on install)
skills/ extensions/	sqlite lock files
settings.json models-store.json

The package is self-contained: it includes the restore script and an automatically generated migration checklist, so a fresh machine only needs the tarball.

Install

pi install git:github.com/fengfanfan-max/pi-agent-backup-migrate

Or clone and use the script directly: scripts/pi-agent-backup.sh.

Usage

# On the current machine: create a backup (data + checklist + restore script)
bash pi-agent-backup.sh backup

# Transfer the tarball via USB / AirDrop / private NAS / scp only.
# NEVER upload to public clouds — sessions/ contains private conversations.

# On the new machine: extract, then restore
tar xzf pi-agent-backup-*.tar.gz
bash ~/pi-agent-backup.sh restore pi-agent-backup-*.tar.gz

The restore command prints the generated migration checklist and runs live checks: auth.json missing → /login again; bin/ missing → reinstall binary-dependent skills.

Security rules (enforced by the script)

• API keys (auth.json, *.env) are never packaged; each machine logs in via /login
• Sessions contain PII — private transport only (USB/AirDrop/NAS/SSH), never public GitHub
• No bidirectional cloud sync of ~/.pi/agent (SQLite WAL lock conflicts)

Requirements

• bash (Git Bash on Windows, system bash on macOS/Linux)
• tar

License

MIT