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

> Learn how to back up your ai-memory SQLite database safely using CLI, HTTP, or programmatic methods. Create a gzipped tarball with a live server backup.

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

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/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.

```bash

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

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs), you invoke the backup API on an open connection:

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) contains the HTTP handler (`handle_backup`), [`crates/ai-memory-cli/src/commands/backup.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/backup.rs) implements the CLI wrapper, and [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) handles the low-level SQLite backup operations using `rusqlite::Connection::backup`.