Which AI-Memory Lifecycle Operations Require Stopping the Server?

The reset --confirm, restore --from <tarball>, and reindex commands require stopping the ai-memory server because they perform direct-disk operations that need exclusive access to the data directory.

The ai-memory CLI provides comprehensive lifecycle management for your AI memory store according to the akitaonrails/ai-memory source code. While most administrative commands route safely through the HTTP admin API, three specific operations perform low-level filesystem manipulation that cannot tolerate concurrent access from a running server instance.

Lifecycle Commands That Require a Server Shutdown

Three specific lifecycle operations must be executed only after stopping the ai-memory server process. These commands modify the underlying storage directly and require exclusive filesystem access, enforced by a sysinfo guard that detects running sibling processes.

reset --confirm

The reset --confirm command removes the entire wiki, database, and raw directories. As documented in docs/lifecycle-ops.md (lines 22-24), this operation refuses to run if any sibling ai-memory process is alive. The sysinfo guard actively prevents data corruption by verifying no other instances are running before destroying the data store.

restore --from

The restore --from <tarball> command restores a full backup (wiki plus SQLite database) by overwriting the data directory. According to docs/lifecycle-ops.md (lines 9-11), it performs a sysinfo check and aborts immediately if another ai-memory process is detected, ensuring atomic restoration without concurrent write conflicts.

reindex

The reindex command rebuilds the SQLite index from the markdown wiki files. Because this operation requires the writer actor to be idle, it also checks that no ai-memory process is alive before proceeding, as noted in docs/lifecycle-ops.md (lines 24-26).

Safe Lifecycle Operations (Server Can Remain Running)

All other lifecycle commands are safe to execute while the server is running because they route through the admin HTTP API and respect the writer-actor concurrency model. These include:

• purge-project
• purge-session
• handoffs --expire-all
• rename-project
• move-project
• move-session
• backup
• checkpoints
• restore-page

Implementation: The Sysinfo Guard and Direct-Disk Protection

The requirement to stop the server is enforced at the code level. According to docs/lifecycle-ops.md, the safety matrix explicitly marks these three commands as requiring the server to be stopped because they bypass the HTTP admin API.

The enforcement mechanism resides in crates/ai-memory-mcp/src/admin.rs, which implements the sysinfo guard. This component checks for running sibling ai-memory processes before allowing destructive direct-disk operations to proceed. Additionally, the README.md highlights this requirement in its "Read before running purge / rename / backup / restore / reset / reindex / restore-page" section, and AGENTS.md lists the "Live-process check before direct-disk lifecycle ops" as a formal invariant.

Step-by-Step Workflow for Destructive Operations

When performing reset, restore, or reindex operations, follow this strict sequence:

# 1. Stop the server (Docker example)

docker compose -f ~/deploy/ai-memory/docker-compose.yml down

# 2. Reset the entire data store

ai-memory reset --confirm

# 3. Restore from a backup tarball

ai-memory restore --from /tmp/ai-memory-backup.tar.gz --data-dir /var/opt/ai-memory/data --force

# 4. Re-index the SQLite database from wiki files

ai-memory reindex --data-dir /var/opt/ai-memory/data

After completing the operation, restart the server with docker compose up -d or your equivalent deployment command.

Summary

• Three commands require downtime: reset --confirm, restore --from, and reindex must only be run after stopping the server.
• Direct-disk access: These operations need exclusive filesystem access and cannot use the HTTP admin API.
• Sysinfo protection: The crates/ai-memory-mcp/src/admin.rs guard prevents execution if sibling processes are detected.
• All other commands are safe: Operations like backup, purge-project, and rename-project work through the admin API while the server runs.

Frequently Asked Questions

Can I run backup operations without stopping the server?

Yes. The backup command and other administrative operations like purge-project, rename-project, and checkpoints route through the HTTP admin API and are designed to run safely while the server is active. Only the three direct-disk operations require exclusive access.

What happens if I attempt to reset while the server is running?

The command will abort immediately. The sysinfo guard in crates/ai-memory-mcp/src/admin.rs detects the running process and prevents the reset --confirm operation from executing to avoid data corruption. You must stop the server before retrying.

Why does reindex require stopping the server while restore-page does not?

reindex performs a full rebuild of the SQLite database from the filesystem, requiring the writer actor to be completely idle and exclusive access to the database files. In contrast, restore-page is a targeted operation that routes through the admin HTTP API, which manages concurrency internally without requiring a full shutdown.

How can I verify no ai-memory processes are running before executing destructive commands?

You can check for running processes using standard system monitoring tools like ps aux | grep ai-memory or pgrep ai-memory. The ai-memory CLI automatically performs this verification via the sysinfo guard before allowing reset, restore, or reindex operations to proceed.

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