> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Backup & Restore (Phoenix)

> Phoenix backup system for ArgentOS workspace data — local, Git, S3, and Cloudflare R2 targets with compression, encryption, and retention policies.

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

<Warning>
  Losing this data means losing the agent's accumulated knowledge, personality, and relationship context. Phoenix ensures you can always recover.
</Warning>

## CLI Commands

### Create a Backup

```bash theme={null}
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

```bash theme={null}
argent backup list
```

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

### Restore from Backup

```bash theme={null}
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

```bash theme={null}
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`):

```json theme={null}
{
  "workspace": "~/argent",
  "backupDir": "~/backups/argent",
  "targets": {
    "local": {
      "enabled": true,
      "path": "~/backups/argent"
    },
    "git": {
      "enabled": false,
      "repo": "git@github.com: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

<Tabs>
  <Tab title="Local Filesystem">
    The simplest target. Copies backup snapshots to a local directory.

    ```json theme={null}
    {
      "local": {
        "enabled": true,
        "path": "~/backups/argent"
      }
    }
    ```
  </Tab>

  <Tab title="Git Repository">
    Commits backups to a Git repository with optional auto-push.

    ```json theme={null}
    {
      "git": {
        "enabled": true,
        "repo": "git@github.com: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.
  </Tab>

  <Tab title="Amazon S3">
    Uploads backup snapshots to an S3 bucket. Requires AWS CLI configured with appropriate credentials.

    ```json theme={null}
    {
      "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)
  </Tab>

  <Tab title="Cloudflare R2">
    Uploads to Cloudflare R2 object storage. R2 has no egress fees, making it ideal for backups that may need frequent restores.

    ```json theme={null}
    {
      "r2": {
        "enabled": true,
        "accountId": "YOUR_CLOUDFLARE_ACCOUNT_ID",
        "bucket": "agent-backups",
        "prefix": "argent/",
        "accessKeyId": "optional-if-using-wrangler",
        "secretAccessKey": "optional-if-using-wrangler"
      }
    }
    ```
  </Tab>
</Tabs>

## Retention Policies

Retention policies automatically prune old backups to manage storage:

```json theme={null}
{
  "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      |

<Tip>
  Set any value to `-1` for unlimited retention.
</Tip>

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

```json theme={null}
{
  "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](https://age-encryption.org))

## Restore Process

<Steps>
  <Step title="Select a backup">
    Select a backup by timestamp (or use `--latest`)
  </Step>

  <Step title="Verify integrity">
    Verify the backup integrity (checksums, decompression)
  </Step>

  <Step title="Stop the gateway">
    Stop the gateway if running (to prevent database conflicts)
  </Step>

  <Step title="Copy files">
    Copy files from the backup to the workspace
  </Step>

  <Step title="Restore databases">
    Restore databases using SQLite `.restore`
  </Step>

  <Step title="Restart the gateway">
    Restart the gateway
  </Step>
</Steps>

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

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

```typescript theme={null}
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                     |