OpenClaw SQLite backup: create, verify, and restore agent state
An OpenClaw SQLite backup is worth making before an upgrade, a storage migration, or any repair that might touch agent state. The v2026.8.1-beta.2 release adds openclaw backup sqlite create|list|verify|restore for compact global and per-agent database artifacts. The important constraint is deliberate: restore targets must be fresh. Treat a backup as a recovery test, not as a file to drop on top of a running agent.
This guide explains the workflow and the operational choices behind it. It does not assume that every SQLite file is disposable. OpenClaw’s built-in memory engine stores per-agent indexes in SQLite, and agent state can include more than the Markdown files people usually remember to copy.
Table of contents
- What an OpenClaw SQLite backup covers
- Create, list, and verify backups
- Restore into a fresh target
- A practical recovery drill
- How this fits with regular maintenance
- FAQ
What an OpenClaw SQLite backup covers
The beta release describes the new commands as creating compact, verified artifacts for global and per-agent databases. That makes them more useful than a casual copy of one file when the goal is to preserve the state an agent actually depends on.
OpenClaw’s built-in memory engine uses a per-agent SQLite database. Its documentation names the default location as ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite; it also notes that WAL sidecars are managed through periodic and shutdown checkpoints. A raw copy taken at the wrong moment can therefore leave you guessing which related files belong together. A product-level backup command can encode that responsibility instead of pushing it onto an operator during an incident.
| Situation | What to protect | Why the distinction matters |
|---|---|---|
| Routine upgrade | Global and active-agent state | You want a known rollback point before changing binaries or configuration. |
| One agent behaves strangely | That agent’s state first | A scoped artifact keeps investigation and recovery narrow. |
| Moving hosts | Global state plus required agents | A migration needs a clean restore target and a way to prove the artifact is readable. |
| Memory search issue | Canonical Markdown and derived state | MEMORY.md and memory/*.md remain the source material; the index is derived but still operationally useful. |
For the wider architecture, see how OpenClaw works and the complete OpenClaw guide. If the incident is specifically about recall or context, OpenClaw memory configuration is the closer companion piece.
Create, list, and verify backups
The release announces four verbs: create, list, verify, and restore. Use them as a sequence rather than treating create as the finish line.
- Create a snapshot before the change you are about to make.
- List the available artifacts so you record the one you intend to use.
- Verify that artifact before you need it.
- Keep the result with the upgrade ticket, runbook, or maintenance log.
At a minimum, start by checking the CLI’s current help for the exact flags in the version you installed:
openclaw backup sqlite --help
openclaw backup sqlite create --help
openclaw backup sqlite verify --helpThat small pause matters because the cited feature first landed in a beta release. The command family is public release material, but option names and defaults can move before stable release. Do not build an unattended restore job around flags copied from a prerelease note.
Verification should happen immediately after creation and again before a planned restore. SQLite’s own online backup API exists so a backup can copy a live source without holding the source read lock for the full operation. That does not make every hand-copied database safe; it explains why a backup-aware workflow is preferable to treating an active database as an ordinary document.
Restore an OpenClaw state into a fresh target
The release notes call out a fresh-target-only restore. Read that as a safety boundary: the recovery destination should not already contain a competing OpenClaw state tree.
A cautious restore sequence looks like this:
- Stop the target Gateway or use a new test machine, container, or user profile.
- Confirm that the target has not already initialized the state you plan to restore.
- Run the restore command against the chosen verified artifact.
- Start the target and inspect its health, configured providers, agent list, and memory status.
- Send a harmless test request before switching real channels or scheduled work over.
The goal is to learn whether the artifact works without overwriting newer activity. Restoring into a live directory can turn a recoverable problem into a reconciliation problem: old configuration, current sessions, credentials, and channel queues may no longer agree.
Keep secrets separate in your plan. A database restore is not permission to export credentials into a ticket or a shared archive. The same beta release introduced exact HTTPS destination-host binding for shared-store secrets, a reminder that state recovery and secret handling need different controls.
A practical recovery drill
A backup you have never verified is only a theory. Run a small drill after a meaningful change, not during a real outage.
| Step | Evidence to keep | Failure it catches |
|---|---|---|
| Create | Artifact identifier and creation time | No restore point before maintenance |
| Verify | Successful verification output | Corrupt or incomplete artifact |
| Restore to a fresh target | Target path or isolated host | Accidental overwrite of active state |
| Start the target | Gateway health and agent status | Missing runtime prerequisites |
| Exercise one safe task | Test prompt and expected result | A backup that loads but does not support normal work |
For a personal installation, an isolated local profile is often enough. For a team or a production-like gateway, use a short-lived environment with channels disconnected. The test should prove storage and startup behavior, not send duplicate outbound messages.
Write down what is outside the snapshot’s scope in your own environment. Files you manage independently, external service credentials, reverse-proxy configuration, and host-level launch settings may need their own backup and recovery procedure. That is not a flaw in a SQLite snapshot; it is basic scope control.
How this fits with regular maintenance
The new CLI workflow complements, rather than replaces, source control and normal OpenClaw maintenance.
- Keep canonical memory files in a place you can inspect and version when appropriate.
- Create and verify a SQLite artifact before upgrades, migrations, schema changes, or invasive repair work.
- Test restore into a fresh target at an interval that matches the cost of losing agent state.
- Record the OpenClaw version with every drill, especially while using beta features.
- Review the stable release notes before standardizing a beta command in a production runbook.
OpenClaw’s memory docs distinguish canonical Markdown sources from the derived SQLite index. That distinction helps under pressure: a broken index can often be rebuilt, while the Markdown source files are the human-readable record worth protecting independently. Pair the backup workflow with OpenClaw’s security guide when your maintenance process includes credentials, nodes, or external channels.
The short version: create the snapshot before the risky change, verify it while the system is healthy, and restore only into a clean destination. That gives you an actual recovery path instead of a hopeful archive.
FAQ
Does an OpenClaw SQLite backup replace copying MEMORY.md?
No. OpenClaw documents MEMORY.md, USER.md, and memory/*.md as canonical memory sources. The SQLite index is derived state that supports search and retrieval. Protect both according to their roles.
Can I restore over an existing OpenClaw installation?
The v2026.8.1-beta.2 release describes restore as fresh-target-only. Use a new or cleared target for the recovery test rather than merging a snapshot into a live state directory.
Should I automate backups from a beta release?
Automate creation and verification only after checking the installed CLI help and testing a restore in an isolated target. Beta releases are useful for evaluating the workflow, but your runbook should pin the version and record the exact behavior it relies on.
Is a SQLite backup enough for a host migration?
Usually not by itself. Capture the relevant OpenClaw state artifact, then separately account for host configuration, secrets, network setup, and any external services your agents need. Test the complete cutover in an isolated target before retiring the original host.
Sources: OpenClaw v2026.8.1-beta.2 release notes · OpenClaw built-in memory engine · OpenClaw memory configuration reference · SQLite online backup API