--- summary: "CLI reference for `openclaw memory` (status/index/search/promote/promote-explain/rem-harness/rem-backfill/session-backfill)" read_when: - 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` title: "Memory" --- # `openclaw memory` Manage semantic memory indexing, search, and promotion into `MEMORY.md`. Provided by the bundled `memory-core` plugin, available when `plugins.slots.memory` selects `memory-core` (the default). Other memory plugins expose their own CLI namespaces. Related: [Memory](/concepts/memory) concept, [Dreaming](/concepts/dreaming), [Memory config reference](/reference/memory-config), [Memory Wiki](/plugins/memory-wiki), [wiki](/cli/wiki), [Plugins](/tools/plugin). ## `memory status` ```bash openclaw memory status [--agent ] [--deep] [--index] [--fix] [--json] [--verbose] ``` Without `--agent`, runs for every agent in `agents.entries`; if no agent list is configured, falls back to the default agent. | Flag | Effect | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--deep` | Probe vector-store, embedding-provider, and semantic-search readiness (implies extra provider calls). Plain `memory status` stays fast and skips this; unknown vector/semantic state means it was not probed. QMD lexical `searchMode: "search"` always skips semantic vector probes, even with `--deep`. | | `--index` | Reindex if the store is dirty. Implies `--deep`. | | `--fix` | Repair stale recall locks and normalize promotion metadata. | | `--json` | Print JSON. | | `--verbose` | Emit detailed per-phase logs. | If the `Dreaming` line stays `off` even with `dreaming.enabled: true`, or scheduled sweeps never seem to run, the managed dreaming cron depends on the default agent's heartbeat firing to trigger reconciliation. See [Dreaming](/concepts/dreaming) for scheduling details. Status also lists any extra search paths from `memory.search.extraPaths`. ## `memory index` ```bash openclaw memory index [--agent ] [--force] [--verbose] ``` Same per-agent scoping as `status`. `--force` runs 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` ```bash openclaw memory search [query] [--query ] [--agent ] [--max-results ] [--min-score ] [--json] ``` - Query: positional `[query]` or `--query `. If both are set, `--query` wins. If neither is set, the command errors. - `--agent `: defaults to the default agent (not the full agent list). - `--max-results `: cap result count (positive integer). - `--min-score `: filter out matches below this score. ## `memory promote` Rank short-term candidates from `memory/YYYY-MM-DD.md` and optionally append top entries to `MEMORY.md`. ```bash openclaw memory promote [--agent ] [--limit ] [--min-score ] \ [--min-recall-count ] [--min-unique-queries ] [--apply] [--include-promoted] [--json] ``` | Flag | Default | Effect | | -------------------------- | ------------ | ----------------------------------------------------------------- | | `--limit ` | | Max candidates to return/apply. | | `--min-score ` | `0.75` | Minimum weighted promotion score. | | `--min-recall-count ` | `3` | Minimum recall count required. | | `--min-unique-queries ` | `3` | Minimum distinct query count required. | | `--apply` | preview only | Append selected candidates to `MEMORY.md` and mark them promoted. | | `--include-promoted` | | Include candidates already promoted in previous cycles. | | `--json` | | Print JSON. | The CLI and scheduled dreaming sweep share the deep-phase defaults below. Explicit CLI flags override them for a one-off manual run. Ranking signals: recall frequency, retrieval relevance, query diversity, temporal recency, cross-day consolidation, and derived concept richness, drawn from both memory recalls and daily-ingestion passes, plus a light/REM phase reinforcement boost for repeated dreaming revisits. Before writing, promotion re-reads the live daily note, so edits or deletions to short-term snippets since ranking are respected instead of promoting from a stale snapshot. ## `memory promote-explain` Explain one promotion candidate's score breakdown. ```bash openclaw memory promote-explain [--agent ] [--include-promoted] [--json] ``` `` matches a candidate's key (exact or substring), path, or snippet text. ## `memory rem-harness` Preview REM reflections, candidate truths, and deep-phase promotion output without writing anything. ```bash openclaw memory rem-harness [--agent ] [--path ] [--grounded] [--include-promoted] [--json] ``` - `--path `: seed the harness from historical `YYYY-MM-DD.md` daily files instead of the live workspace. - `--grounded`: also render a grounded `What Happened` / `Reflections` / `Possible Lasting Updates` preview from the historical notes. ## `memory rem-backfill` Write grounded historical REM summaries into `DREAMS.md` for UI review. Reversible. ```bash openclaw memory rem-backfill --path [--agent ] [--stage-short-term] [--json] openclaw memory rem-backfill --rollback [--rollback-short-term] [--json] ``` - `--path `: required unless `--rollback`/`--rollback-short-term` is set. Historical daily memory file(s) or directory to backfill from. - `--stage-short-term`: also seed grounded durable candidates into the live short-term promotion store so the normal deep phase can rank them. - `--rollback`: remove previously written grounded diary entries from `DREAMS.md`. - `--rollback-short-term`: remove previously staged grounded short-term candidates. ## `memory session-backfill` Distill retained session history through the same provenance and short-term staging pipeline used by dreaming. The default is a read-only preview, ordered from the oldest unprocessed day to the newest. ```bash openclaw memory session-backfill --agent [--from YYYY-MM-DD] [--to YYYY-MM-DD] \ [--limit-days ] [--archive-files ] [--rem | --apply] [--json] openclaw memory session-backfill --agent --rollback [--json] ``` | Flag | Default | Effect | | --------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | `--from YYYY-MM-DD` | | Include messages on or after this day in the dreaming timezone. | | `--to YYYY-MM-DD` | | Include messages on or before this day in the dreaming timezone. | | `--limit-days ` | `92` | Process at most this many hash-untracked days, oldest first. | | `--archive-files ` | | Also inspect foreign transcript files as untrusted input; embedded owner metadata is not accepted. | | `--rem` | | Write deterministic grounded per-day previews to `DREAMS.md` only. | | `--apply` | preview only | Stage trusted candidates and write reversible `DREAMS.md` diary blocks. | | `--rollback` | | Remove all grounded backfill candidates and shared backfill diary blocks, including `rem-backfill` artifacts. | | `--json` | | Print machine-readable per-day counts and top candidates. | The command reads the selected agent's canonical session store, including retained SQLite transcript identities from session rotation. It uses the same tracked message hashes and per-run caps as live session ingestion, so repeated `--apply` runs skip already ingested messages. Owner and agent lines from the canonical store are eligible; tool output, web or non-owner input, and turns without trustworthy owner provenance are excluded. Foreign archive files have no authenticated owner-provenance contract, so their embedded ownership fields remain untrusted and cannot be staged. `--apply` writes only the session corpus under `memory/.dreams/`, short-term staging state, and reversible diary entries in `DREAMS.md`. It never writes `MEMORY.md` or `USER.md`; durable promotion remains a separate `memory promote` or dreaming decision. `--rem` and `--apply` are mutually exclusive. Backfill rollback is intentionally shared with `memory rem-backfill`: both commands use the same grounded-only staging class and diary markers. Run `session-backfill --rollback` only when you intend to clear both commands' grounded backfill artifacts from that workspace. Rollback preserves transcript ingestion cursors and tracked message hashes, so removed messages are not automatically re-ingested. ## Dreaming Dreaming is the background memory consolidation system with three cooperative phases, run in order on one schedule: **light** (sort/stage short-term material), **REM** (reflect and surface themes), **deep** (promote durable facts into `MEMORY.md`). Only deep writes to `MEMORY.md`. - Enable with `plugins.entries.memory-core.config.dreaming.enabled: true` (default `true`); `memory-core` auto-manages the sweep cron job, no manual `openclaw cron add` required. - Toggle from chat with `/dreaming on|off`; inspect with `/dreaming status` (or `/dreaming`/`/dreaming help`). `on`/`off` requires channel owner status or gateway `operator.admin`; `status` and help stay available to anyone who can invoke the command. - Human-readable phase output goes to `DREAMS.md` (or an existing `dreams.md`). By default (`dreaming.storage.mode: "separate"`) each phase also writes a standalone report to `memory/dreaming//YYYY-MM-DD.md`; set `mode: "inline"` to fold reports into the daily memory file instead, or `"both"` for both. - Scheduled and manual `memory promote` runs share the same deep-phase ranking signals and default thresholds; explicit CLI flags remain one-run overrides. - Scheduled runs fan out across every configured agent's memory workspace. Scheduled defaults (`plugins.entries.memory-core.config.dreaming`): | Key | Default | | -------------------------------------- | ----------- | | `frequency` | `0 3 * * *` | | `phases.deep.minScore` | `0.75` | | `phases.deep.minRecallCount` | `3` | | `phases.deep.minUniqueQueries` | `3` | | `phases.deep.recencyHalfLifeDays` | `14` | | `phases.deep.maxAgeDays` | `30` | | `phases.deep.maxPromotedSnippetTokens` | `160` | ```json { "plugins": { "entries": { "memory-core": { "config": { "dreaming": { "enabled": true } } } } } } ``` Full key list and phase details: [Dreaming](/concepts/dreaming), [Memory config reference](/reference/memory-config#dreaming). ## SecretRef gateway dependency If active memory remote API key fields are configured as SecretRefs, `memory` commands resolve them from the active gateway snapshot; if the gateway is unavailable, the command fails fast. This requires a gateway supporting the `secrets.resolve` method; older gateways return an unknown-method error. ## Related - [CLI reference](/cli) - [Memory overview](/concepts/memory)