Memory

text

Copy

openclaw memory

Manage semantic memory indexing and search. Provided by the active memory plugin (default:

; set to disable).

Related:

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

Examples

bash
Copy
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

and :

• text

  Copy

  --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.
• text

  Copy

  --verbose
  : emit detailed logs during probes and indexing.

:

• text

  Copy

  --deep
  : probe vector + embedding availability. Plain
  text

  Copy

  memory status
  stays fast and does not run a live embedding ping. QMD lexical
  text

  Copy

  searchMode: "search"
  skips semantic vector probes and embedding maintenance even with
  text

  Copy

  --deep
  .
• text

  Copy

  --index
  : run a reindex if the store is dirty (implies
  text

  Copy

  --deep
  ).
• text

  Copy

  --fix
  : repair stale recall locks and normalize promotion metadata.
• text

  Copy

  --json
  : print JSON output.

If

shows , 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.

:

• text

  Copy

  --force
  : force a full reindex.

:

• Query input: pass either positional
  text

  Copy

  [query]
  or
  text

  Copy

  --query <text>
  .
• If both are provided,
  text

  Copy

  --query
  wins.
• If neither is provided, the command exits with an error.
• text

  Copy

  --agent <id>
  : scope to a single agent (default: the default agent).
• text

  Copy

  --max-results <n>
  : limit the number of results returned.
• text

  Copy

  --min-score <n>
  : filter out low-score matches.
• text

  Copy

  --json
  : print JSON results.

:

Preview and apply short-term memory promotions.

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

• text

  Copy

  --apply
  -- write promotions to
  text

  Copy

  MEMORY.md
  (default: preview only).
• text

  Copy

  --limit <n>
  -- cap the number of candidates shown.
• text

  Copy

  --include-promoted
  -- include entries already promoted in previous cycles.

Full options:

• Ranks short-term candidates from
  text

  Copy

  memory/YYYY-MM-DD.md
  using weighted promotion signals (
  text

  Copy

  frequency
  ,
  text

  Copy

  relevance
  ,
  text

  Copy

  query diversity
  ,
  text

  Copy

  recency
  ,
  text

  Copy

  consolidation
  ,
  text

  Copy

  conceptual richness
  ).
• Uses short-term signals from both memory recalls and daily-ingestion passes, plus light/REM phase reinforcement signals.
• When dreaming is enabled,
  text

  Copy

  memory-core
  auto-manages one cron job that runs a full sweep (
  text

  Copy

  light -> REM -> deep
  ) in the background (no manual
  text

  Copy

  openclaw cron add
  required).
• text

  Copy

  --agent <id>
  : scope to a single agent (default: the default agent).
• text

  Copy

  --limit <n>
  : max candidates to return/apply.
• text

  Copy

  --min-score <n>
  : minimum weighted promotion score.
• text

  Copy

  --min-recall-count <n>
  : minimum recall count required for a candidate.
• text

  Copy

  --min-unique-queries <n>
  : minimum distinct query count required for a candidate.
• text

  Copy

  --apply
  : append selected candidates into
  text

  Copy

  MEMORY.md
  and mark them promoted.
• text

  Copy

  --include-promoted
  : include already promoted candidates in output.
• text

  Copy

  --json
  : print JSON output.

:

Explain a specific promotion candidate and its score breakdown.

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

• text

  Copy

  <selector>
  : candidate key, path fragment, or snippet fragment to look up.
• text

  Copy

  --agent <id>
  : scope to a single agent (default: the default agent).
• text

  Copy

  --include-promoted
  : include already promoted candidates.
• text

  Copy

  --json
  : print JSON output.

:

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

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

• text

  Copy

  --agent <id>
  : scope to a single agent (default: the default agent).
• text

  Copy

  --include-promoted
  : include already promoted deep candidates.
• text

  Copy

  --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

), and REM (reflect and surface themes).

• Enable with
  text

  Copy

  plugins.entries.memory-core.config.dreaming.enabled: true
  .
• Toggle from chat with
  text

  Copy

  /dreaming on|off
  (or inspect with
  text

  Copy

  /dreaming status
  ).
• Dreaming runs on one managed sweep schedule (
  text

  Copy

  dreaming.frequency
  ) and executes phases in order: light, REM, deep.
• Only the deep phase writes durable memory to
  text

  Copy

  MEMORY.md
  .
• Human-readable phase output and diary entries are written to
  text

  Copy

  DREAMS.md
  (or existing
  text

  Copy

  dreams.md
  ), with optional per-phase reports in
  text

  Copy

  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
  text

  Copy

  MEMORY.md
  , so edited or deleted short-term snippets do not get promoted from stale recall-store snapshots.
• Scheduled and manual
  text

  Copy

  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:
  text

  Copy

  dreaming.frequency = 0 3 * * *
• Deep thresholds:
  text

  Copy

  minScore=0.8
  ,
  text

  Copy

  minRecallCount=3
  ,
  text

  Copy

  minUniqueQueries=3
  ,
  text

  Copy

  recencyHalfLifeDays=14
  ,
  text

  Copy

  maxAgeDays=30

Example:

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

Notes:

• text

  Copy

  memory index --verbose
  prints per-phase details (provider, model, sources, batch activity).
• text

  Copy

  memory status
  includes any extra paths configured via
  text

  Copy

  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
  text

  Copy

  secrets.resolve
  ; older gateways return an unknown-method error.
• Tune scheduled sweep cadence with
  text

  Copy

  dreaming.frequency
  . Deep promotion policy is otherwise internal; use CLI flags on
  text

  Copy

  memory promote
  when you need one-off manual overrides.
• text

  Copy

  memory rem-harness --path <file-or-dir> --grounded
  previews grounded
  text

  Copy

  What Happened
  ,
  text

  Copy

  Reflections
  , and
  text

  Copy

  Possible Lasting Updates
  from historical daily notes without writing anything.
• text

  Copy

  memory rem-backfill --path <file-or-dir>
  writes reversible grounded diary entries into
  text

  Copy

  DREAMS.md
  for UI review.
• text

  Copy

  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.
• text

  Copy

  memory rem-backfill --rollback
  removes previously written grounded diary entries, and
  text

  Copy

  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