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

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 sends a POST /admin/backup request to the running server.

2. Database Snapshot: The handler in 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 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 lines 28‑34).

CLI Backup Command Syntax and Examples

The basic syntax requires only the destination path:

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

Basic Local Backup

Create a timestamped backup in your current directory:

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:

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

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:

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), 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}