openclaw memory CLI Reference

`openclaw memory`

Manage indexing, searching, and promoting semantic memory into MEMORY.md. This functionality comes from the memory-core plugin that ships with the product. It becomes available when plugins.slots.memory chooses memory-core, which is the default. Other memory plugins provide their own CLI namespaces.

See also: Memory concept, Dreaming, Memory config reference, Memory Wiki, wiki, Plugins.

`memory status`

openclaw memory status [--agent <id>] [--deep] [--index] [--fix] [--json] [--verbose]

Without --agent, the command targets every agent inside agents.entries. If no agent list has been configured, it falls back to the default agent.

Flag	Effect
`--deep`	Checks that the vector store, embedding provider, and semantic search are ready. This triggers extra provider calls. Plain `memory status` stays fast and skips those checks. Unknown vector or semantic state means probing has not occurred. QMD lexical `searchMode: "search"` always bypasses semantic vector probes, even when `--deep` is used.
`--index`	Triggers a reindex when the store is dirty. Implies `--deep`.
`--fix`	Fixes stale recall locks and normalizes promotion metadata.
`--json`	Outputs JSON.
`--verbose`	Provides verbose per-phase logging.

If the Dreaming line stays off even with dreaming.enabled: true enabled, or if scheduled sweeps never appear to run, note that the managed dreaming cron depends on the default agent's heartbeat firing to start reconciliation. See Dreaming for scheduling details.

The status output also lists any additional search paths from memory.search.extraPaths.

`memory index`

openclaw memory index [--agent <id>] [--force] [--verbose]

The same per-agent scoping rules apply as for status. --force performs a full reindex instead of an incremental one. --verbose prints per-agent provider, model, sources, and extra-path details before showing indexing progress.

`memory search`

openclaw memory search [query] [--query <text>] [--agent <id>] [--max-results <n>] [--min-score <n>] [--json]

Query: use positional [query] or --query <text>. When both are provided, --query takes precedence. If neither is given, the command returns an error.
--agent <id>: defaults to the default agent, not the full agent list.
--max-results <n>: limits the number of results to a positive integer.
--min-score <n>: excludes matches falling below this score.

`memory promote`

Rank short-term candidates drawn from memory/YYYY-MM-DD.md and optionally append the top entries to MEMORY.md.

openclaw memory promote [--agent <id>] [--limit <n>] [--min-score <n>] \
  [--min-recall-count <n>] [--min-unique-queries <n>] [--apply] [--include-promoted] [--json]

Flag	Default	Effect
`--limit <n>`		Maximum number of candidates to return or apply.
`--min-score <n>`	`0.75`	Lowest weighted promotion score that will be accepted.
`--min-recall-count <n>`	`3`	Minimum number of recalls required.
`--min-unique-queries <n>`	`2`	Minimum number of distinct queries required.
`--apply`	preview only	Writes selected candidates into `MEMORY.md` and marks them as promoted.
`--include-promoted`		Includes candidates that were already promoted in earlier cycles.
`--json`		Outputs JSON.

These CLI defaults are not the same as the deep-phase thresholds used by the scheduled dreaming sweep (see Dreaming below). Pass explicit flags to match sweep behavior when running a one-off manual operation.

Ranking signals include recall frequency, retrieval relevance, query diversity, temporal recency, cross-day consolidation, and derived concept richness. These come from both memory recalls and daily ingestion passes, plus a light/REM phase reinforcement boost for repeated dreaming revisits. Before writing, promotion reads the live daily note again, so any edits or deletions to short-term snippets made after ranking are honored instead of using a stale snapshot.

`memory promote-explain`

Show the score breakdown for one promotion candidate.

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

<selector> looks for a match against a candidate's key (either exact or substring), path, or snippet text.

`memory rem-harness`

See REM reflections, candidate truths, and deep phase promotion output in preview mode without committing anything.

openclaw memory rem-harness [--agent <id>] [--path <file-or-dir>] [--grounded] [--include-promoted] [--json]

--path <file-or-dir>: populate the harness using historical YYYY-MM-DD.md daily files rather than the active workspace.
--grounded: also produce a grounded What Happened / Reflections / Possible Lasting Updates preview from the historical notes.

`memory rem-backfill`

Store grounded historical REM summaries in DREAMS.md for UI inspection. This operation is reversible.

openclaw memory rem-backfill --path <file-or-dir> [--agent <id>] [--stage-short-term] [--json]
openclaw memory rem-backfill --rollback [--rollback-short-term] [--json]

--path <file-or-dir>: mandatory unless --rollback/--rollback-short-term is specified. The historical daily memory file or directory to use for backfilling.
--stage-short-term: additionally, seed grounded durable candidates into the active short term promotion store so the normal deep phase can rank them.
--rollback: delete previously written grounded diary entries from DREAMS.md.
--rollback-short-term: remove previously staged grounded short term candidates.

Dreaming

Dreaming is the background memory consolidation system composed of three cooperative phases executed sequentially on a single schedule: light (sort and stage short term material), REM (reflect and surface themes), deep (promote durable facts into MEMORY.md). Only the deep phase writes to MEMORY.md.

Enable it with plugins.entries.memory-core.config.dreaming.enabled: true (default is false); memory-core automatically manages the sweep cron job, so no manual openclaw cron add setup is needed.
Toggle it from chat using /dreaming on|off; inspect it with /dreaming status (or /dreaming//dreaming help). Using on/off requires channel owner status or gateway operator.admin; status and help remain available to anyone who can call the command.
Human readable phase output is sent to DREAMS.md (or an existing dreams.md). By default (dreaming.storage.mode: "separate") each phase also writes a standalone report to memory/dreaming/<phase>/YYYY-MM-DD.md; set mode: "inline" to embed reports in the daily memory file instead, or "both" for both.
Both scheduled and manual memory promote runs use the same deep phase ranking signals; only the default thresholds differ (see the table above versus the scheduled defaults below).
Scheduled runs spread across every configured agent's memory workspace.

Scheduled defaults (plugins.entries.memory-core.config.dreaming):

Key	Default
`frequency`	`0 3 * * *`
`phases.deep.minScore`	`0.8`
`phases.deep.minRecallCount`	`3`
`phases.deep.minUniqueQueries`	`3`
`phases.deep.recencyHalfLifeDays`	`14`
`phases.deep.maxAgeDays`	`30`
`phases.deep.maxPromotedSnippetTokens`	`160`

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

Complete key list and phase details: Dreaming, Memory config reference.

SecretRef gateway dependency

When active memory remote API key fields are set up as SecretRefs, memory commands retrieve them from the current gateway snapshot. If the gateway cannot be reached, the command stops immediately with an error. A gateway that supports the secrets.resolve method is necessary for this to work; gateways that are older will respond with an error indicating an unknown method.