Backup & Restore (Phoenix)

Overview

Phoenix is the ArgentOS backup and restore system. It protects your agent’s workspace data — memory files, identity documents, configuration, databases, and alignment docs — by creating versioned snapshots and distributing them across multiple storage targets. Phoenix supports four backup targets: local filesystem, Git repositories, Amazon S3, and Cloudflare R2. Backups can be compressed, encrypted, and managed with retention policies that automatically prune old snapshots.

Why Phoenix Exists

Your agent’s workspace contains irreplaceable data:

SOUL.md, IDENTITY.md, USER.md — Agent personality and identity
MEMORY.md and memory/ — Durable knowledge and daily notes
observations.db — MemU memory database with thousands of observations
memory.db — Full memory store with embeddings and entity tracking
Configuration — All argent.json settings and channel configs

Losing this data means losing the agent’s accumulated knowledge, personality, and relationship context. Phoenix ensures you can always recover.

CLI Commands

Create a Backup

argent backup create

Flag	Description
`--dry-run`	Preview what would be backed up without executing
`--verbose`	Show detailed output during backup
`--memory-only`	Only backup memory files (MEMORY.md, observations.db)
`--databases-only`	Only backup SQLite databases
`--config <path>`	Use a custom config file

List Backups

argent backup list

Shows all available backups with timestamps, sizes, and compression status.

Restore from Backup

argent backup restore
argent backup restore --latest
argent backup restore --backup 2026-03-15-14-30

Flag	Description
`--latest`	Restore from the most recent backup
`--backup <timestamp>`	Restore from a specific backup
`--memory-only`	Only restore memory files
`--databases-only`	Only restore databases
`--identity-only`	Only restore identity files (SOUL.md, IDENTITY.md, etc.)
`--dry-run`	Preview what would be restored

Initialize Configuration

argent backup init

Creates an example configuration file at ~/.argentos/backup.json with sensible defaults.

Configuration

Phoenix is configured via ~/.argentos/backup.json (also searched at ~/.argentos/phoenix.json and ~/.config/argentos/backup.json):

{
  "workspace": "~/argent",
  "backupDir": "~/backups/argent",
  "targets": {
    "local": {
      "enabled": true,
      "path": "~/backups/argent"
    },
    "git": {
      "enabled": false,
      "repo": "[email protected]:youruser/agent-backup.git",
      "branch": "main",
      "autoCommit": true
    },
    "s3": {
      "enabled": false,
      "bucket": "my-agent-backups",
      "prefix": "argent/",
      "storageClass": "STANDARD_IA"
    },
    "r2": {
      "enabled": false,
      "accountId": "YOUR_CLOUDFLARE_ACCOUNT_ID",
      "bucket": "agent-backups",
      "prefix": "argent/"
    }
  },
  "include": [
    "MEMORY.md",
    "SOUL.md",
    "USER.md",
    "AGENTS.md",
    "IDENTITY.md",
    "memory/*.md",
    "scripts/",
    "config/",
    "~/.argentos/observations.db"
  ],
  "exclude": [
    "*.log",
    "node_modules/",
    ".git/",
    "*.tmp",
    ".DS_Store"
  ],
  "compression": true,
  "retention": {
    "daily": 7,
    "weekly": 4,
    "monthly": 12
  },
  "notifications": {
    "enabled": false,
    "onSuccess": "silent",
    "onFailure": "alert"
  },
  "encryption": {
    "enabled": false,
    "method": "gpg"
  }
}

Configuration Fields

Field	Type	Description
`workspace`	`string`	Root directory of the workspace to back up
`backupDir`	`string`	Directory to store backup snapshots
`targets`	`object`	Backup target configurations (see below)
`include`	`string[]`	Glob patterns for files to include
`exclude`	`string[]`	Glob patterns for files to exclude
`compression`	`boolean`	Enable gzip compression (default: `true`)
`retention`	`object`	Retention policy for automatic pruning
`notifications`	`object`	Notification settings for success/failure
`encryption`	`object`	Encryption settings (GPG or age)

Storage Targets

Local Filesystem
Git Repository
Amazon S3
Cloudflare R2

The simplest target. Copies backup snapshots to a local directory.

{
  "local": {
    "enabled": true,
    "path": "~/backups/argent"
  }
}

Commits backups to a Git repository with optional auto-push.

{
  "git": {
    "enabled": true,
    "repo": "[email protected]:youruser/agent-backup.git",
    "branch": "main",
    "autoCommit": true
  }
}

Git backup creates a commit for each snapshot. With autoCommit: true, it also pushes to the remote after each commit. This provides version history and off-site backup in one step.

Uploads backup snapshots to an S3 bucket. Requires AWS CLI configured with appropriate credentials.

{
  "s3": {
    "enabled": true,
    "bucket": "my-agent-backups",
    "prefix": "argent/",
    "storageClass": "STANDARD_IA"
  }
}

Supported storage classes:

STANDARD — Frequent access
STANDARD_IA — Infrequent access (lower cost, retrieval fees)
GLACIER — Archive storage (minutes to hours retrieval)
DEEP_ARCHIVE — Long-term archive (12+ hours retrieval)

Uploads to Cloudflare R2 object storage. R2 has no egress fees, making it ideal for backups that may need frequent restores.

{
  "r2": {
    "enabled": true,
    "accountId": "YOUR_CLOUDFLARE_ACCOUNT_ID",
    "bucket": "agent-backups",
    "prefix": "argent/",
    "accessKeyId": "optional-if-using-wrangler",
    "secretAccessKey": "optional-if-using-wrangler"
  }
}

Retention Policies

Retention policies automatically prune old backups to manage storage:

{
  "retention": {
    "daily": 7,
    "weekly": 4,
    "monthly": 12
  }
}

Policy	Description	Default
`daily`	Number of daily backups to keep	7
`weekly`	Number of weekly backups to keep	4
`monthly`	Number of monthly backups to keep	12

Set any value to -1 for unlimited retention.

Database Backup

SQLite databases are backed up using the SQLite .backup command, which creates a consistent snapshot even while the database is in use. This is safer than simple file copy, which can capture a database in an inconsistent state. Databases backed up include:

~/.argentos/observations.db — MemU memory store
~/.argentos/memory.db — Legacy memory database
~/.argentos/data/dashboard.db — Dashboard task database

Compression

When compression: true (the default), backup snapshots are compressed with gzip. This typically reduces backup size by 60-80% for text-heavy workspace content. The system checks for gzip availability on the host before attempting compression.

Encryption

Phoenix supports optional encryption for backup snapshots:

{
  "encryption": {
    "enabled": true,
    "method": "gpg",
    "keyId": "your-gpg-key-id"
  }
}

Supported methods:

gpg — GnuPG encryption with a specified key ID
age — Modern encryption with age (https://age-encryption.org)

Restore Process

Select a backup

Select a backup by timestamp (or use --latest)

Verify integrity

Verify the backup integrity (checksums, decompression)

Stop the gateway

Stop the gateway if running (to prevent database conflicts)

Copy files

Copy files from the backup to the workspace

Restore databases

Restore databases using SQLite .restore

Restart the gateway

Partial restores are supported via --memory-only, --databases-only, and --identity-only flags. This lets you restore specific components without overwriting everything.

Workspace Zip Backup

In addition to Phoenix, the alignment docs system creates workspace zip backups independently. These are created through the dashboard and stored locally. Phoenix and workspace zip backups are complementary — Phoenix handles scheduled, multi-target backups while workspace zip is for ad-hoc dashboard-initiated snapshots.

Backup State

Phoenix tracks backup state in ~/.argentos/backup/.last-backup:

interface BackupState {
  timestamp: number;    // Unix timestamp
  date: string;         // ISO date string
  backupPath: string;   // Path to the backup
  compression: boolean; // Whether compression was used
  success: boolean;     // Whether the backup succeeded
}

This state file is used to report the last backup status and determine when the next backup should run.

Key Files

File	Description
`src/backup/runner.ts`	Core backup and restore operations
`src/backup/types.ts`	Type definitions for config and operations
`src/backup/config.ts`	Configuration loading and validation
`src/backup/index.ts`	Module exports
`~/.argentos/backup.json`	Backup configuration file
`~/.argentos/backup/`	Backup state directory

Web UI

Dashboard

Tasks

Gateway & Ops

Intent & Safety

Security

Backup & Restore (Phoenix)

Overview

Why Phoenix Exists

CLI Commands

Create a Backup

List Backups

Restore from Backup

Initialize Configuration

Configuration

Configuration Fields

Storage Targets

Retention Policies

Database Backup

Compression

Encryption

Restore Process

Workspace Zip Backup

Backup State

Key Files

Web UI

Dashboard

Tasks

Gateway & Ops

Intent & Safety

Security

​Overview

​Why Phoenix Exists

​CLI Commands

​Create a Backup

​List Backups

​Restore from Backup

​Initialize Configuration

​Configuration

​Configuration Fields

​Storage Targets

​Retention Policies

​Database Backup

​Compression

​Encryption

​Restore Process

​Workspace Zip Backup

​Backup State

​Key Files

Overview

Why Phoenix Exists

CLI Commands

Create a Backup

List Backups

Restore from Backup

Initialize Configuration

Configuration

Configuration Fields

Storage Targets

Retention Policies

Database Backup

Compression

Encryption

Restore Process

Workspace Zip Backup

Backup State

Key Files