# How to Perform a Backup of ai-memory Data Using the CLI

> Easily backup ai-memory data with the CLI. Learn to create a gzipped tarball of your SQLite snapshot and wiki directory by accessing the /admin/backup endpoint.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-21

---

**The ai-memory CLI creates a consistent, gzipped tarball containing a live SQLite snapshot and the wiki directory by issuing a `POST` request to the server's `/admin/backup` endpoint.**

The `akitaonrails/ai-memory` repository provides a dedicated backup command that captures both the database state and plaintext content without requiring server downtime. Understanding how to perform a backup of ai-memory data using the CLI ensures you can safely archive your workspace pages, links, FTS indexes, and embedding vectors for disaster recovery or migration purposes.

## Understanding the ai-memory Backup Architecture

**ai-memory** persists state in two distinct locations that must be snapshot together for consistency:

- **SQLite database**: Contains the live write-ahead log (WAL), pages, links, full-text search indexes, and embedding vectors
- **Wiki directory**: A plaintext tree structure at `wiki/<workspace>/<project>/` holding markdown source files

The backup system uses SQLite's **online-backup API**, which allows the database to remain open for reads and writes while the snapshot is taken. This eliminates downtime during backup operations.

## The Backup Process Flow

When you execute the backup command, the following sequence occurs according to the source code:

1. **CLI Request**: The client in [`crates/ai-memory-cli/src/commands/backup.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/backup.rs) sends a `POST /admin/backup` request to the running server.

2. **Database Snapshot**: The handler in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) invokes `build_backup_tarball_file`, which calls `sqlite::backup` (implemented in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) lines 3956‑3963) to copy the live database to a temporary file using the online-backup API.

3. **Archive Creation**: The handler tars the temporary database file together with the entire `wiki/` directory, compresses the result with gzip, and streams it back with a `Content-Disposition: attachment; filename="backup.tar.gz"` header.

4. **Local Write**: The CLI receives the binary response and writes it to the path specified with `--to <tarball>`. The file is created with **private permissions** (`0600`) to protect embedded secrets, then prints a confirmation message like `✓ wrote backup to /tmp/ai-memory-backup.tar.gz (23 MiB)` (see [`crates/ai-memory-cli/src/commands/backup.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/backup.rs) lines 28‑34).

## CLI Backup Command Syntax and Examples

The basic syntax requires only the destination path:

```bash
ai-memory backup --to <path-to-tarball>

```

### Basic Local Backup

Create a timestamped backup in your current directory:

```bash
ai-memory backup --to ./ai-memory-backup.tar.gz

# Or with a timestamp

ai-memory backup --to /tmp/ai-memory-$(date +%Y%m%d-%H%M).tar.gz

```

### Docker Container Backups

For production deployments running in Docker, execute the backup inside the container, then copy the file to your host:

```bash

# Create backup inside container

docker exec ai-memory \
  ai-memory backup --to /data/snapshot-$(date +%F).tar.gz

# Copy to host

docker cp ai-memory:/data/snapshot-$(date +%F).tar.gz ./backups/

```

### Remote Host Backup

When the ai-memory server listens on a TCP address rather than a local socket, set the `AI_MEMORY_URL` environment variable:

```bash
AI_MEMORY_URL=http://host:49374 \
ai-memory --url "$AI_MEMORY_URL" backup \
  --to ./remote-backup.tar.gz

```

## Restoring from a Backup

The backup tarball contains both the SQLite snapshot and the plaintext wiki, enabling complete state recovery. To restore your system, use the companion restore command:

```bash
ai-memory restore --from ./ai-memory-backup.tar.gz

```

This command extracts the database and wiki files, returning your ai-memory instance to the exact state captured in the backup.

## Summary

- **Dual storage**: ai-memory stores data in SQLite (structured data) and the `wiki/` directory (markdown files), both captured in the backup.
- **Online backup**: The process uses SQLite's online-backup API, allowing the server to remain operational during the snapshot.
- **Secure permissions**: Backup files are created with `0600` permissions to prevent unauthorized access to embedded data.
- **Single command**: The `ai-memory backup --to <path>` command handles the entire process, from snapshot creation to local file writing.
- **Complete recovery**: The resulting tarball contains everything needed for a full restore via `ai-memory restore --from`.

## Frequently Asked Questions

### Does the ai-memory backup command require stopping the server?

No. The backup uses SQLite's online-backup API (implemented in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs)), which creates a consistent snapshot while the database remains open for reads and writes. This allows production systems to stay online during backup operations.

### What permissions does the backup file have?

The CLI creates backup files with **mode `0600`** (read/write for owner only) as implemented in [`crates/ai-memory-cli/src/commands/backup.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/backup.rs). This protects any secrets or sensitive embedding data that might be contained in the SQLite database.

### Can I backup ai-memory data to a remote server directly?

The CLI does not support direct remote storage like S3 or NFS. You must specify a local filesystem path with `--to`. For remote backups, write to a local path first, then transfer the file using `scp`, `rsync`, or your cloud provider's CLI tools. Alternatively, run the CLI from a host that has the target filesystem mounted.

### What is included in the ai-memory backup tarball?

The gzipped tarball contains two components: (1) a point-in-time snapshot of the SQLite database including all pages, links, FTS indexes, and embedding vectors, and (2) the complete `wiki/` directory tree containing all plaintext markdown files. This combination ensures full state recovery without additional data sources.