How to Back Up the ai-memory SQLite Database: CLI, HTTP, and Programmatic Methods

You can back up the ai-memory SQLite database safely while the server is running using SQLite's online backup API, which creates a gzipped tarball containing both the database snapshot and the wiki directory.

The akitaonrails/ai-memory project stores all persistent state in a single SQLite database running in WAL (Write-Ahead Logging) mode alongside a markdown-based wiki directory. Because the system uses SQLite's online backup capabilities through rusqlite::Connection::backup, you can create consistent snapshots without stopping the server or interrupting active write operations.

Understanding the ai-memory Backup Architecture

ai-memory maintains its state in two locations: the SQLite database file and the wiki/ directory containing markdown pages.

What Gets Backed Up

The backup process creates a gzipped tarball that preserves both components:

• A snapshot of the live SQLite database (main file plus WAL file)
• The entire wiki/ directory with all markdown pages, maintaining workspace/project layout

This dual-capture approach ensures you can fully restore your workspace state, including both structured data and unstructured documentation.

How the Live Backup Works

The server implements the backup logic in crates/ai-memory-mcp/src/admin.rs within the handle_backup function. This handler calls build_backup_tarball_file, which orchestrates the snapshot process.

The actual database consistency is handled by rusqlite::Connection::backup as implemented in crates/ai-memory-store/src/reader.rs. This API copies the database while writes may continue, avoiding race conditions through SQLite's native online backup mechanism:

conn.backup(rusqlite::DatabaseName::Main, &dest_path, None)?;

Because the database operates in WAL mode, the backup captures both the main database file and the write-ahead log, ensuring transactional consistency.

Methods to Back Up the ai-memory Database

You have three primary interfaces for creating backups: the command-line interface, direct HTTP requests, or programmatic Rust code.

Using the CLI

The simplest method uses the CLI front-end implemented in crates/ai-memory-cli/src/commands/backup.rs. The command POSTs to the server's /admin/backup endpoint and writes the response to your specified path.

# Create a gzipped tarball backup

ai-memory backup --to /tmp/ai-memory-backup.tar.gz

The CLI automatically handles authentication and streams the tarball to disk with owner-only permissions to prevent accidental exposure.

Using HTTP/API

For automation scripts or external tools, you can call the /admin/backup endpoint directly:

curl -X POST http://127.0.0.1:49374/admin/backup \
     -o /tmp/ai-memory-backup.tar.gz \
     -H "Accept: application/gzip"

This approach returns the same gzipped tarball as the CLI method, suitable for integration with cron jobs or backup orchestration systems.

Programmatic Backup in Rust

If you need to embed backup functionality in your own Rust application, you can use the same primitives as the ai-memory server. According to the source code in crates/ai-memory-store/src/reader.rs, you invoke the backup API on an open connection:

use rusqlite::{Connection, DatabaseName, OpenFlags};

let src_conn = Connection::open_with_flags(
    "/path/to/data/ai-memory.sqlite",
    OpenFlags::SQLITE_OPEN_READ_WRITE,
)?;
let dest_path = "/tmp/ai-memory-snapshot.sqlite";
src_conn.backup(DatabaseName::Main, &dest_path, None)?;

This creates a consistent SQLite snapshot while the source database remains available for reads and writes.

Safety Guarantees and Permissions

The ai-memory backup system enforces three critical safety guarantees:

• Live-process guard: The server refuses destructive operations while the writer thread is active, as documented in AGENTS.md
• Consistent snapshot: SQLite's online backup API (rusqlite::Connection::backup) ensures transactional consistency even during active writes
• Private output files: The CLI creates tarball files with owner-only permissions (implemented in http_client.rs) to prevent unauthorized access

Summary

• ai-memory stores data in a WAL-mode SQLite database and a wiki/ directory, both captured in the backup tarball.
• The backup uses SQLite's online backup API (Connection::backup) in crates/ai-memory-store/src/reader.rs for consistency without downtime.
• Use ai-memory backup --to <path> (CLI), POST to /admin/backup (HTTP), or rusqlite::Connection::backup (Rust) to create snapshots.
• The handle_backup handler in crates/ai-memory-mcp/src/admin.rs orchestrates the tarball creation process.
• Backups include both the database snapshot and wiki directory, with file permissions restricted to the owner.

Frequently Asked Questions

Can I back up ai-memory while the server is running?

Yes. The system uses SQLite's online backup API, which allows consistent snapshots while the database remains open for reads and writes. The handle_backup function in crates/ai-memory-mcp/src/admin.rs implements this via rusqlite::Connection::backup, ensuring the snapshot captures a transactionally consistent state even if writes occur during the backup process.

What files are included in the backup tarball?

The gzipped tarball contains two components: a snapshot of the live SQLite database (including the main file and WAL file) and the entire wiki/ directory with all markdown pages. This preserves both your structured data and project documentation, maintaining the workspace layout as documented in docs/lifecycle-ops.md.

How do I restore from an ai-memory backup?

Use the ai-memory restore --from <tarball> command documented in docs/lifecycle-ops.md. This extracts the SQLite database and wiki directory from the tarball and places them in the appropriate locations for the server to use. Ensure the server is not actively writing to the database during restoration to avoid conflicts.

Where is the backup logic implemented in the source code?

The backup logic spans three main files: crates/ai-memory-mcp/src/admin.rs contains the HTTP handler (handle_backup), crates/ai-memory-cli/src/commands/backup.rs implements the CLI wrapper, and crates/ai-memory-store/src/reader.rs handles the low-level SQLite backup operations using rusqlite::Connection::backup.

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