How OpenClaw Memory Actually Works: Consolidation, Promotion & Recall

Why memory is the feature that matters

Most AI assistants are stateless. You ask, they answer, and everything is forgotten the moment the conversation ends. That worked fine when AI was a search engine with better grammar. It does not work when the AI is supposed to act like a teammate.

OpenClaw's answer is a persistent memory layer rooted in a single durable file: MEMORY.md. Over weeks of use, MEMORY.md accumulates the things your assistant has learned about you — coding style, project conventions, names of services, dates that matter, decisions you have already made. The result is an assistant whose answers improve over time instead of resetting every session.

But MEMORY.md is not magic. It is the output of a real pipeline with discrete stages, and understanding those stages is the difference between trusting the system and being surprised by it. Let's walk through it.

The four stages of OpenClaw memory

At a high level, the OpenClaw memory system is a four-stage pipeline. Information flows from left to right, getting progressively more durable at each stage.

  SESSION                CONSOLIDATION           PROMOTION              RECALL
  ───────                ─────────────           ─────────              ──────

  ┌─────────┐            ┌────────────┐          ┌───────────┐          ┌──────────┐
  │ Prompt  │            │ Candidate  │          │ MEMORY.md │          │ Context  │
  │ + reply │            │ truths     │          │ (durable) │          │ engine   │
  └────┬────┘            └─────┬──────┘          └─────┬─────┘          └─────┬────┘
       │ writes               │ scores                │ recalled              │ injects
       ▼                      ▼                       ▼                       ▼
  ┌─────────┐            ┌────────────┐          ┌───────────┐          ┌──────────┐
  │ Short-  │ ────────►  │ Confidence │ ───────► │ Long-term │ ───────► │ Recall   │
  │ term    │            │ scoring    │          │ memory    │          │ traces   │
  │ store   │            │ + dedup    │          │ store     │          │ in prompt│
  └─────────┘            └────────────┘          └───────────┘          └──────────┘

       │                      │                       │                       │
       │ session              │ background            │ across                │ per-prompt
       │ transcript           │ pass                  │ sessions              │ working set
       ▼                      ▼                       ▼                       ▼

   volatile            scored candidates       durable facts          assistant context

  Stage 1:                Stage 2:               Stage 3:               Stage 4:
  Capture                 Consolidate            Promote                Recall

Each stage has a clear job and a clear failure mode. The rest of this post breaks them down one at a time.

Stage 1: Short-term capture

Every interaction with OpenClaw produces working memory. The session transcript is written to disk as it happens, daily memory files are appended with timestamps, and the agent workspace records artifacts, edits, and tool calls. None of this is curated. It is raw, redundant, and volatile.

Where this lives, in a typical install:

~/.openclaw/
├── memory/
│   ├── MEMORY.md              # durable long-term memory (Stage 3)
│   ├── short-term/            # raw session transcripts
│   │   ├── 2026-04-08.jsonl   # daily memory file
│   │   ├── 2026-04-09.jsonl
│   │   └── ...
│   └── candidates/            # consolidation output (Stage 2)
│       └── pending.jsonl
├── workspace/                 # agent workspace, tool artifacts
└── ...

The short-term store is intentionally cheap. There is no deduplication, no promotion logic, no scoring. Its only job is to make sure nothing is lost between when it happens and when consolidation runs.

A consequence: short-term memory grows fast. A heavy user can produce hundreds of MB of session transcripts per week. This is one reason backup matters — if you only back up MEMORY.md and forget the short-term store, you lose anything that has not yet been consolidated and promoted.

Stage 2: Consolidation

Consolidation is the process of turning raw short-term observations into compact candidate truths. It runs periodically — on a background timer, when triggered by the dreaming pipeline, or when you invoke memory consolidate manually. Its job is summarisation plus deduplication plus preliminary scoring.

In practice, a single consolidation pass does roughly this:

• Read the unconsolidated range of short-term files (everything since the last consolidation watermark).
• Extract claim-shaped statements: facts about the user, decisions made, preferences expressed, project conventions, names and identifiers.
• Deduplicate claims that are semantically equivalent to existing entries already in MEMORY.md or in the candidates queue.
• Score each surviving claim based on signals: how often it appeared, whether the user explicitly confirmed it, whether the assistant relied on it in a successful action, whether it has been corroborated by another source.
• Write the scored candidates to memory/candidates/pending.jsonl for the promotion stage to evaluate.

Consolidation is also the stage where the dreaming pipeline does most of its work. During REM-like sweeps, the rem-harness runs consolidation against the recent dream window, extracts themes, and writes reflection summaries that feed promotion. We covered that pipeline at a high level when discussing dreaming — if you want the full architecture, the dedicated dreaming post in the roadmap is the place to go.

A failure in consolidation does not lose data on its own (the short-term store is still intact), but it does mean candidates stop accumulating. After a long enough outage, your assistant will appear to “not learn” from recent sessions even though the raw transcripts exist. The fix is usually to run consolidation manually and then rely on the next scheduled pass.

Stage 3: Promotion to MEMORY.md

Promotion is where a candidate truth becomes durable. The promotion stage reads the candidates queue, evaluates each entry against the promotion threshold, and writes the survivors to MEMORY.md. Once a fact is in MEMORY.md, it survives across sessions, across machines (if you sync), and across reboots. It is the “long-term memory” of the system.

The promotion threshold is not a single number — it is a composite over several signals:

The default behaviour is conservative. A claim must clear multiple signals before promotion, which is why your MEMORY.md stays small and useful even after months of use — the pipeline filters noise on the way in.

Promoted entries are written with metadata: source IDs pointing back into the consolidated history, a confidence score, and a timestamp. You can inspect them with memory explain <entry>, which prints the trail of evidence the promoter used.

Stage 4: Recall and the context engine

Recall is the read side. When you send a prompt to OpenClaw, the context engine takes that prompt and scores every entry in MEMORY.md (and a recency window of consolidated candidates) against it. The top-N entries are pulled into the working context as recall traces, where the assistant can reason over them.

Scoring uses a mix of semantic similarity (embedding lookups) and lexical signals (token overlap, identifier matches, recency weighting). The scorer is designed to be cheap enough to run on every prompt — recall has to feel instant or the feature dies of latency.

Two important properties of recall:

• Recall is read-only. It never mutates MEMORY.md. A bad recall pass cannot corrupt long-term memory; it can only return weak context. Repair is just “run the prompt again with better wording.”
• Recall is your earliest warning system. If you ask the assistant about something you know it knew last week and it draws a blank, that is the first hint that MEMORY.md may have been wiped, replaced, or restored from a bad source. The fix is to compare against your last known good backup — which we strongly recommend you have.

You can inspect what recall returned for any given prompt with memory recall --explain, which shows the scored traces, their scores, and which signals contributed.

Worked example: how a single fact becomes durable

Concrete is better than abstract. Suppose your team standardised on using pnpm last week and you want OpenClaw to stop suggesting npm install. Here is the actual lifecycle of that fact through the memory system:

Day 1, session A:
  user:  "we're using pnpm now, don't suggest npm"
  agent: noted
  ► written to short-term/2026-04-09.jsonl
  ► not yet in MEMORY.md

Day 1, end-of-day consolidation pass:
  ► extracted claim: "team uses pnpm; avoid npm"
  ► first observation, score = 0.4
  ► written to candidates/pending.jsonl
  ► not yet promoted (below threshold)

Day 2, session B:
  user:  "install zod"
  agent: "running pnpm add zod"   ← used the candidate
  ► action grounding signal +0.3
  ► candidate score now 0.7

Day 2, dream sweep (REM):
  ► grounded as candidate truth
  ► dream grounding signal +0.2
  ► candidate score now 0.9 → CROSSES THRESHOLD

Day 3, promoter run:
  ► candidate promoted to MEMORY.md
  ► entry: "Project uses pnpm. Do not suggest npm install."
  ► confidence: 0.92
  ► sources: [session-A, session-B, dream-2026-04-10]

Day 4, fresh session C:
  user:  "add a dependency"
  agent: recalls MEMORY.md entry (high score for "dependency")
  ► uses pnpm without prompting

That is roughly what the promotion threshold buys you: a piece of context that took two sessions and a dream sweep to consolidate is now permanent and recallable on demand. Without this pipeline, you would be retraining the assistant every time you started a new conversation.

What happens when MEMORY.md vanishes

Now the bad scenario. You upgrade your laptop, run a fresh OpenClaw install, and notice the assistant is suddenly stupid again. It has no idea about pnpm, no idea about your project conventions, no idea who you are. What happened?

In almost every case, the answer is the same: the durable memory store at ~/.openclaw/memory/ is gone. Either the new machine never had it, or an OS reinstall wiped it, or a misconfigured backup tool restored an empty directory over the top.

Unlike chat history, this is not recoverable from the model provider. The model provider never had your MEMORY.md — it lives entirely on your machine. The only paths back are:

• Restore from a backup taken before the loss. This is by far the cheapest fix and recovers everything: MEMORY.md, candidates, short-term store, dream diary, custom skills, the whole workspace.
• Rebuild from scratch. Spend weeks re-establishing context, re-explaining your project conventions, re-confirming preferences, re-teaching the assistant who you are.

There is no third option. There is no provider-side recovery, no “forgot my memory” flow, no support ticket. The memory layer is fully local-first, which is what makes it privacy-respecting and what makes it your responsibility to back up.

For a complete walkthrough of the recovery flow including the CLI commands, the steps in the Restore section of the docs are the canonical reference.

How MemoryClaw protects every stage of the pipeline

MemoryClaw is a backup tool that takes a snapshot of your entire ~/.openclaw/ directory and ships it to encrypted cloud storage on a schedule. It does not modify the memory pipeline. It does not interpret what is inside. It just makes sure that whatever state your memory system reaches, you can always go back to it.

What that means in practice for each stage:

Every backup is encrypted on your machine with AES-256-GCM using a passphrase only you know — we cover the exact cryptographic choices in our zero-knowledge encryption post. Backup happens on a cron schedule via the automatic backup system, so the only thing you have to do once is install the CLI and choose a passphrase.

When the bad day comes — new laptop, OS reinstall, accidental directory delete — memoryclaw pull downloads the latest encrypted snapshot, decrypts it locally, and restores the entire memory pipeline to the state it was in at the moment of the last backup.

Frequently asked questions

Is MEMORY.md the same as chat history?

No. Chat history is a per-conversation log. MEMORY.md is the consolidated, promoted-from-short-term store of facts and preferences that survive across all conversations. You can wipe chat history and your assistant will still remember you. You cannot wipe MEMORY.md without losing weeks of accumulated context.

Can I edit MEMORY.md by hand?

Yes — it is a markdown file. Edit, save, and the next recall pass will pick up your changes. You can also remove stale entries this way. Just keep a backup before you start editing in case you delete more than you meant to.

What is the promotion threshold tuned to?

Conservative by default. The pipeline is biased toward keeping MEMORY.md small and high-signal. If you find that claims you care about are not getting promoted, the easiest fix is to confirm them explicitly — explicit confirmation is a strong promotion signal.

Does dreaming write to MEMORY.md directly?

Indirectly. The dreaming pipeline runs consolidation against the dream window and produces grounded candidate truths that feed promotion. Promotion still has the final say. Dreaming does not bypass the threshold; it just produces more evidence for it.

How often should I back up MEMORY.md?

Once a day is the floor. A few times a day is comfortable. If you use OpenClaw heavily, the Free plan's 24 backups/day is plenty for one machine; the Pro plan unlocks unlimited backups across up to 10 claws. The right cadence is “more often than you can stand to lose.”