OpenClaw Memory CLI Guide: status --deep, index --force, reset, forget, and Why You Never Delete the SQLite File

Somewhere out there is a memory troubleshooting guide telling you to delete the SQLite file. Don't.

The pages that rank for openclaw memory are the official CLI reference, a handful of package mirrors serving older copies of it, and two long troubleshooting articles (around 3,200 words each) that spend most of their length on compaction and file permissions. A shorter quick-start of about 950 words covers hybrid search and ends with the advice to remove the SQLite file under the memory directory "to force a fresh start." On a current install that file is agents/<agentId>/agent/openclaw-agent.sqlite, and it also holds your stored sessions, transcripts, and other durable agent state. The docs say plainly never to delete it, or its -wal, -shm, or -journal sidecars, to reset an index. None of the ranking articles walks through what to run instead. That ladder is below, after the one rule that trips up every script.

Most memory commands want the Gateway stopped

memory search and memory session-backfill route through the local Gateway when it is running. Almost everything else (status, index, reset, forget, promote, and session backfill with --rem or --archive-files) needs the Gateway stopped, and refuses before opening any stores if a Gateway owns the state directory. Stop it through whatever owns the service, run the command, start it again.

The memory.status RPC you can call on a running Gateway returns provider health. That is a smaller answer than the CLI's index, source, embedding, and dreaming diagnostics, so a green RPC tells you less than you think.

Plain status vs status --deep

Plain openclaw memory status is fast because it skips the provider. Without --agent it runs for every agent in agents.entries. A complete persisted index shows as indexed (unprobed), which means exactly what it says: the rows are there and nobody asked the embedding provider anything.

Status diagnostics also report storage: the database file, the WAL, reusable free pages, and embedding cache bytes. These overlap. Adding them together gives you a number that means nothing.

Empty search results can be lying

memory search defaults to the default agent, not the whole list, which surprises people coming from status. If automatic indexing failed or the index identity no longer matches your embedding settings, human output warns that matches may be incomplete, and --json adds stale: true with warning and action fields. An empty results array is only trustworthy when stale is absent. If you check memory from a cron job, test for that field before you test for zero results. Disabled memory returns {"agentId":"main","status":"disabled"} with a successful exit, so check that too.

Index recovery, cheapest first

The usual trigger is changing embedding provider or model and then getting an index identity warning. This is the order I use.

# 1. What does the index say? (fast, no provider calls)
openclaw memory status --agent main

# 2. Does the provider agree with the index?
openclaw memory status --deep --agent main

# 3. Rebuild the derived index, keep everything else
openclaw memory index --force --agent main
openclaw memory status --agent main

# 4. Only if the rebuild won't take: clear index and embedding cache
openclaw memory reset --agent main --yes
openclaw memory index --agent main

Always pass --agent. Without it, index and reset run across every configured agent, and on a multi-agent box that turns a repair for one agent into a full rebuild for all of them.

reset drops and recreates only the memory-owned tables inside that database. Nothing else in the file changes, and your Markdown memory files are untouched. It needs --yes in a non-interactive terminal, it won't shrink the file on disk, and it can't bring back anything already lost by deleting the database. If indexing is busy, let it finish and retry.

Rate limits are handled for you during indexing: up to five attempts per embedding operation, with waits capped at 60 seconds each. --verbose shows every wait. The interactive memory_search tool is stingier, three attempts and no more than eight seconds of retry sleep inside its 30-second deadline. A big rebuild after an index-format upgrade can blow through that, and the agent tool will report memory as unavailable while the work finishes.

forget deletes immediately

No prompt. No --apply flag. Unless you pass --dry-run, it deletes.

openclaw memory forget --agent main --session <id-or-key> --dry-run --json
openclaw memory forget --agent main --hook-source gmail --dry-run --json
openclaw memory forget --agent main --participant <actor-id> --dry-run --json

Selectors combine with OR, so --session a --hook-source gmail covers both. A participant selector takes the whole session, including everything other people said in it. Session IDs match exactly and case-sensitively, and an ID that resolves to nothing still gets recorded as forgotten for future exclusion, which can quietly hide a typo. Read sessionResolutions in the preview for anything labeled unresolved.

Two more things worth knowing before you run it for real. Entries with mixed lineage are removed whole rather than rewritten. And any nonempty selection clears that agent's entire embedding cache, so later indexing may have to re-embed unrelated content, which costs real provider calls. Source transcripts are kept, and deleting a session ordinarily retains a deleted-transcript archive, so neither forget nor reset is an erasure of every copy. For the files on disk, the backup and migration guide is where the other copies live.

promote previews unless you say --apply

memory promote ranks short-term candidates from memory/YYYY-MM-DD.md and, with --apply, appends the winners to MEMORY.md. Defaults match the scheduled deep phase: --min-score 0.75, --min-recall-count 3, --min-unique-queries 3. Entries with untrusted or system provenance never make the list. I run it with --limit 5 and read the preview first; promote-explain <selector> breaks down a single score when something odd floats to the top. Because promotion re-reads the live daily note before writing, deleting a bad snippet from today's file is enough to keep it out.

session-backfill is preview-only by default, processes at most 92 untracked days per run, and never writes MEMORY.md or USER.md even with --apply. Its --rollback also removes rem-backfill artifacts, since the two share markers.

Dreaming says off

The sweep runs at 0 3 * * *, and it depends on the default agent's heartbeat to reconcile, so if the Dreaming line in status stays off with dreaming.enabled: true, go read the heartbeat guide before you touch memory config at all.

Final verdict

Put stale checks in anything that reads search JSON, scope every repair with --agent, and treat forget --dry-run as mandatory even though the CLI doesn't. When an index looks wrong, reach for index --force, then reset, and leave the database file alone. If you want the design side (what belongs in memory and what doesn't), the memory system deep dive covers it.