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

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

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

For non-default data directories, specify the path:

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, the backup command invokes sqlite3 .backup on the live database. The implementation in 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:

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

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

Docker container backup:

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

Remote restore via SSH:

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:

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 for database operations and 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) 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, this approach prevents partial backups where the database and filesystem states diverge.

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