Openclaw Memory Command List

Complete reference for openclaw memory, checking embedding and vector store health, triggering reindexes, and running semantic searches over your memory files.

What does Openclaw Memory manage?

OpenClaw’s memory system reads your MEMORY.md and memory/*.md files, embeds their contents via a configured provider, and stores the resulting vectors in a local store. This is the foundational engine behind the OpenClaw Memory and Skills System, allowing agents to retrieve relevant historical context and specialized knowledge through semantic search.

The memory command gives you direct CLI access to three operations against that store: checking its health and index state, manually triggering a reindex when files change, and running a search query to verify what the agent would actually retrieve for a given topic.

Where to Start

If something feels off with agent memory retrieval, run memory status –deep first, it probes vector and embedding availability and tells you whether the index is dirty and needs a reindex. If the index is stale, follow up with memory index (or memory index –force for a clean rebuild).

To verify what’s actually in the index, use memory search with a representative query and check the scores. All three subcommands accept –agent <id> to scope to a single agent, in multi-agent setups, omitting it runs the command for every configured agent. If the Gateway is down, these commands will fail fast.

Checking Status — Memory Status

Shows index statistics and probes the availability of your memory setup. The starting point for any memory-related diagnosis.

openclaw memory status

–deep	Probes vector and embedding availability. Tests the full stack, embedding provider, model, and vector store, not just the index metadata.
–index implies –deep	Automatically runs a reindex if the store is marked as dirty. Combines the status probe with a conditional repair in one command.
–agent <id>	Scopes the status check to a single configured agent. Without this flag, runs the check for each configured agent in sequence.
–verbose	Emits detailed logs during the probe, useful for seeing exactly where in the stack a failure is occurring.
–json	Prints the output in machine-readable JSON format for scripting or monitoring pipelines.

Without –agent, this command runs against every configured agent. In large multi-agent setups, use –agent <id> to scope to the specific agent you’re diagnosing.

Indexing Memory — Memory Index

Manually triggers a reindex of the memory files (MEMORY.md and memory/*.md). Run this after editing memory files or when status –deep reports the store as dirty.

openclaw memory indexmutates index

–force	Forces a full reindex, discards the existing index and rebuilds it from scratch. Use when an incremental reindex isn’t resolving retrieval issues.
–agent <id>	Scopes the indexing to a single agent. Without this flag, runs the reindex for each configured agent.
–verbose	Emits detailed logs showing each phase of the reindex: provider, model, sources, and batch activity. Use for debugging slow or failing reindexes.

Searching Memory — Memory Search

Performs a semantic search query over your indexed memory files. Use this to verify what the agent would retrieve for a given topic, or to debug why certain memory content isn’t surfacing in agent responses.

openclaw memory search [query]

Still reading? These two are worth your time: Openclaw Models Commands Guide and Openclaw Message Commands Guide.

[query] / –query “<text>”	The search text. Pass as a positional argument or via the flag. If both are provided, the flag wins. If neither is provided, the command errors out.
–max-results <n>	Limits the number of returned matches. Useful when the default result count is more than you need to spot-check.
–min-score <n>	Filters out results that fall below the specified match score. Lower scores indicate weaker semantic matches, set a threshold to surface only confident results.
–agent <id>	Scopes the search to a single agent. Defaults to the default agent when omitted.
–json	Prints the search results in JSON format, including scores per result.

Use –json with memory search to see the raw match scores alongside each result. This helps you calibrate a good –min-score threshold for your content, scores vary by embedding model and content type.

Common Examples

Four working patterns covering the most common memory management workflows.

01 Check embedding and vector store health

openclaw memory status --deep

When to use: First step when agent memory retrieval feels wrong. Probes the full embedding + vector stack, not just index metadata.

02 Forced reindex with verbose logging for a specific agent

openclaw memory index --agent main --verbose --force

When to use: After editing memory files, or when incremental reindexing hasn’t resolved a retrieval issue. Scoped to the main agent to avoid reindexing all agents unnecessarily.

03 Search for a topic (positional and flag forms)

# Positional argument
openclaw memory search "meeting notes"

# Flag form with result limit
openclaw memory search --query "deployment" --max-results 20

Note: If both forms are provided, –query wins. Use the flag form when the query contains special characters that need quoting.

04 Auto-repair dirty index during status check

openclaw memory status --index --agent main

What this does: –index implies –deep and additionally triggers a reindex if the store is marked dirty, probe and repair in one command.

SecretRef & Gateway Dependency