# How to Backup and Restore ai-memory Data Including SQLite and Wiki Git Repository

> Learn to backup and restore ai-memory data. The ai-memory backup command creates a gzipped tarball of your SQLite database and wiki Git repository for easy restoration.

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

---

**The `ai-memory backup` command generates a gzipped tarball containing a consistent snapshot of the live SQLite database and the complete wiki Git repository, while `ai-memory restore` extracts this archive to rebuild your instance.**

The `akitaonrails/ai-memory` project stores all persistent state across two critical components: a SQLite database for embeddings and metadata, and a Git-managed wiki directory for Markdown pages. Understanding how to backup and restore ai-memory data ensures you can migrate instances, recover from failures, or clone environments without losing vector embeddings or page history.

## Understanding the ai-memory Data Architecture

Before executing backup commands, you must understand where `ai-memory` persists data. The system splits state between transactional metadata and version-controlled content.

### SQLite Database Storage

The **SQLite database** resides in `<data-dir>/sqlite/` (default: `~/.local/share/ai-memory/sqlite/`). This file contains vector embeddings, FTS indexes, and metadata tables. According to the source code in [`crates/ai-memory-store/src/sqlite.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/sqlite.rs), the database operates with WAL (Write-Ahead Logging) enabled, requiring special handling for consistent backups while the server runs.

### Wiki Git Repository Structure

The **wiki repository** lives at `<data-dir>/wiki/` as a standard Git repository. This directory stores all Markdown pages that serve as the source of truth for your knowledge base. Unlike the SQLite database, the wiki is already version-controlled, but the backup process captures the working tree state alongside the database to ensure point-in-time consistency.

## How to Backup ai-memory Data

The backup process uses SQLite's online-backup API to create consistent snapshots without stopping the server, then archives both the database snapshot and wiki directory into a single portable file.

### Using the backup Command

Execute the following command to create a complete backup:

```bash
ai-memory backup --output-path /tmp/ai-memory-backup.tar.gz

```

For non-default data directories, specify the path:

```bash
ai-memory --data-dir /var/lib/ai-memory backup --output-path /var/lib/backups/ai-memory-$(date +%Y%m%d).tar.gz

```

The resulting tarball contains:

- A consistent SQLite snapshot using the online-backup API
- The complete `wiki/` directory tree
- Metadata required for restore operations

### Backup Implementation Details

As implemented in [`crates/ai-memory-store/src/sqlite.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/sqlite.rs), the backup command invokes `sqlite3 .backup` on the live database. The implementation in [`src/bin/ai-memory.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/bin/ai-memory.rs) parses the `backup` subcommand, creates a temporary directory, copies the SQLite snapshot, then streams the entire archive using `tar` without buffering the full file in memory. This approach allows backups of large datasets while the server continues handling requests.

## How to Restore ai-memory from Backup

Restoring requires the server to be stopped to prevent database corruption during file replacement. The restore command extracts the tarball, places files in the correct locations, and re-indexes the wiki if necessary.

### Restore Prerequisites

Before running the restore command:

1. Stop any running `ai-memory` process (the command includes a `sysinfo` guard that aborts if the server is active)
2. Ensure the target data directory is empty or specify `--confirm` to overwrite existing data
3. Verify you have read permissions on the backup tarball and write permissions on the data directory

### Using the restore Command

Run the following to restore your instance:

```bash
ai-memory restore --from /tmp/ai-memory-backup.tar.gz --data-dir /var/lib/ai-memory --confirm

```

The `--confirm` flag is mandatory to prevent accidental data loss. The command performs these steps:

1. Extracts the tarball to a temporary location
2. Moves the SQLite snapshot into `<data-dir>/sqlite/`
3. Restores the `wiki/` directory to `<data-dir>/wiki/`
4. Re-indexes wiki files if the database requires rebuilding FTS indexes

### Re-indexing After Restore

If restoring to a fresh data directory, the restore command automatically triggers the indexing pipeline defined in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) to rebuild FTS indexes and vector embeddings. This ensures the SQLite database stays synchronized with the restored wiki content.

## Practical Backup and Restore Examples

Use these patterns for common operational scenarios.

**Daily automated backup:**

```bash
#!/bin/bash
ai-memory --data-dir ~/.local/share/ai-memory backup --output-path ~/backups/ai-memory-$(date +%F).tar.gz

```

**Docker container backup:**

```bash
docker exec ai-memory ai-memory backup --output-path /data/snapshot-$(date +%F).tar.gz

```

**Remote restore via SSH:**

```bash
scp user@server:/backups/ai-memory-2024-01-15.tar.gz ./
ai-memory restore --from ./ai-memory-2024-01-15.tar.gz --confirm

```

**Systemd service backup:**

```bash
sudo -u ai-memory ai-memory --data-dir /var/lib/ai-memory backup --output-path /var/lib/ai-memory/backups/latest.tar.gz

```

## Summary

- **Single-archive backups**: The `ai-memory backup` command produces one gzipped tarball containing both the SQLite database (via online-backup API) and the wiki Git repository
- **Live backups supported**: SQLite's online-backup API allows consistent snapshots while the server runs, though stopping the server ensures maximum consistency
- **Mandatory confirmation**: The `restore` command requires the `--confirm` flag and aborts if the server process is detected
- **Automatic re-indexing**: Restore operations rebuild FTS indexes and embeddings automatically using the wiki indexing pipeline
- **Source locations**: Implementation resides in [`crates/ai-memory-store/src/sqlite.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/sqlite.rs) for database operations and [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) for wiki handling

## Frequently Asked Questions

### Can I backup ai-memory while the server is running?

Yes. The backup command uses SQLite's online-backup API (implemented in [`crates/ai-memory-store/src/sqlite.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/sqlite.rs)) to create a consistent snapshot of the live database. However, for critical restores, stopping the server first guarantees no in-flight transactions are missed.

### What flags are required for restoring ai-memory data?

The `restore` command requires `--from <path>` to specify the tarball and `--confirm` to acknowledge potential data overwrites. You may also specify `--data-dir <path>` for non-default installations. Without `--confirm`, the command aborts to prevent accidental destruction.

### Where does ai-memory store its SQLite database and wiki files?

By default, ai-memory stores the SQLite database in `~/.local/share/ai-memory/sqlite/` and the wiki repository in `~/.local/share/ai-memory/wiki/`. Both paths are relative to the data directory configurable via the `--data-dir` flag or environment variables.

### How does ai-memory ensure backup consistency?

The system ensures consistency by using SQLite's native `.backup` command to create a point-in-time snapshot of the database, then atomically packages this snapshot with the wiki directory into a single tarball. As documented in [`docs/lifecycle-ops.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/lifecycle-ops.md), this approach prevents partial backups where the database and filesystem states diverge.