openclaw/docs/cli/memory.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw memory` (status/index/search/promote/promote-explain/rem-harness)	You want to index or search semantic memory You're debugging memory availability or indexing You want to promote recalled short-term memory into `MEMORY.md`	Memory

openclaw memory

Manage semantic memory indexing and search. Provided by the bundled memory-core plugin. The command is available when plugins.slots.memory selects memory-core (the default); other memory plugins expose their own CLI namespaces.

Related:

• Memory concept: Memory
• Memory wiki: Memory Wiki
• Wiki CLI: wiki
• Plugins: Plugins

Examples

openclaw memory status
openclaw memory status --deep
openclaw memory status --fix
openclaw memory index --force
openclaw memory search "meeting notes"
openclaw memory search --query "deployment" --max-results 20
openclaw memory promote --limit 10 --min-score 0.75
openclaw memory promote --apply
openclaw memory promote --json --min-recall-count 0 --min-unique-queries 0
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
openclaw memory rem-harness
openclaw memory rem-harness --json
openclaw memory status --json
openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory status --agent main
openclaw memory index --agent main --verbose

Options

memory status and memory index:

• --agent <id>: scope to a single agent. Without it, these commands run for each configured agent; if no agent list is configured, they fall back to the default agent.
• --verbose: emit detailed logs during probes and indexing.

memory status:

• --deep: probe local vector-store readiness, embedding-provider readiness, and semantic vector-search readiness. Plain memory status stays fast and does not run live embedding or provider discovery work; unknown vector-store or semantic-vector state means it was not probed in that command. QMD lexical searchMode: "search" skips semantic vector probes and embedding maintenance even with --deep.
• --index: run a reindex if the store is dirty (implies --deep).
• --fix: repair stale recall locks and normalize promotion metadata.
• --json: print JSON output.

If memory status shows Dreaming status: blocked, the managed dreaming cron is enabled but the heartbeat that drives it is not firing for the default agent. See Dreaming never runs for the two common causes.

memory index:

• --force: force a full reindex.

memory search:

• Query input: pass either positional [query] or --query <text>.
• If both are provided, --query wins.
• If neither is provided, the command exits with an error.
• --agent <id>: scope to a single agent (default: the default agent).
• --max-results <n>: limit the number of results returned.
• --min-score <n>: filter out low-score matches.
• --json: print JSON results.

memory promote:

Preview and apply short-term memory promotions.

openclaw memory promote [--apply] [--limit <n>] [--include-promoted]

• --apply -- write promotions to MEMORY.md (default: preview only).
• --limit <n> -- cap the number of candidates shown.
• --include-promoted -- include entries already promoted in previous cycles.

Full options:

• Ranks short-term candidates from memory/YYYY-MM-DD.md using weighted promotion signals (frequency, relevance, query diversity, recency, consolidation, conceptual richness).
• Uses short-term signals from both memory recalls and daily-ingestion passes, plus light/REM phase reinforcement signals.
• When dreaming is enabled, memory-core auto-manages one cron job that runs a full sweep (light -> REM -> deep) in the background (no manual openclaw cron add required).
• --agent <id>: scope to a single agent (default: the default agent).
• --limit <n>: max candidates to return/apply.
• --min-score <n>: minimum weighted promotion score.
• --min-recall-count <n>: minimum recall count required for a candidate.
• --min-unique-queries <n>: minimum distinct query count required for a candidate.
• --apply: append selected candidates into MEMORY.md and mark them promoted.
• --include-promoted: include already promoted candidates in output.
• --json: print JSON output.

memory promote-explain:

Explain a specific promotion candidate and its score breakdown.

openclaw memory promote-explain <selector> [--agent <id>] [--include-promoted] [--json]

• <selector>: candidate key, path fragment, or snippet fragment to look up.
• --agent <id>: scope to a single agent (default: the default agent).
• --include-promoted: include already promoted candidates.
• --json: print JSON output.

memory rem-harness:

Preview REM reflections, candidate truths, and deep promotion output without writing anything.

openclaw memory rem-harness [--agent <id>] [--include-promoted] [--json]

• --agent <id>: scope to a single agent (default: the default agent).
• --include-promoted: include already promoted deep candidates.
• --json: print JSON output.

Dreaming

Dreaming is the background memory consolidation system with three cooperative phases: light (sort/stage short-term material), deep (promote durable facts into MEMORY.md), and REM (reflect and surface themes).

• Enable with plugins.entries.memory-core.config.dreaming.enabled: true.
• Toggle from chat with /dreaming on|off (or inspect with /dreaming status).
• Dreaming runs on one managed sweep schedule (dreaming.frequency) and executes phases in order: light, REM, deep.
• Only the deep phase writes durable memory to MEMORY.md.
• Human-readable phase output and diary entries are written to DREAMS.md (or existing dreams.md), with optional per-phase reports in memory/dreaming/<phase>/YYYY-MM-DD.md.
• Ranking uses weighted signals: recall frequency, retrieval relevance, query diversity, temporal recency, cross-day consolidation, and derived concept richness.
• Promotion re-reads the live daily note before writing to MEMORY.md, so edited or deleted short-term snippets do not get promoted from stale recall-store snapshots.
• Scheduled and manual memory promote runs share the same deep phase defaults unless you pass CLI threshold overrides.
• Automatic runs fan out across configured memory workspaces.

Default scheduling:

• Sweep cadence: dreaming.frequency = 0 3 * * *
• Deep thresholds: minScore=0.8, minRecallCount=3, minUniqueQueries=3, recencyHalfLifeDays=14, maxAgeDays=30

Example:

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true
          }
        }
      }
    }
  }
}

Notes:

• memory index --verbose prints per-phase details (provider, model, sources, batch activity).
• memory status includes any extra paths configured via memorySearch.extraPaths.
• If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.
• Gateway version skew note: this command path requires a gateway that supports secrets.resolve; older gateways return an unknown-method error.
• Tune scheduled sweep cadence with dreaming.frequency. Deep promotion policy is otherwise internal except for dreaming.phases.deep.maxPromotedSnippetTokens, which bounds promoted snippet length while keeping provenance visible. Use CLI flags on memory promote when you need one-off manual threshold overrides.
• memory rem-harness --path <file-or-dir> --grounded previews grounded What Happened, Reflections, and Possible Lasting Updates from historical daily notes without writing anything.
• memory rem-backfill --path <file-or-dir> writes reversible grounded diary entries into DREAMS.md for UI review.
• memory rem-backfill --path <file-or-dir> --stage-short-term also seeds grounded durable candidates into the live short-term promotion store so the normal deep phase can rank them.
• memory rem-backfill --rollback removes previously written grounded diary entries, and memory rem-backfill --rollback-short-term removes previously staged grounded short-term candidates.
• See Dreaming for full phase descriptions and configuration reference.

Related

• CLI reference
• Memory overview