OpenClaw memory retention: choose what stays, how long, and how to remove it

Published May 22, 2026 · OpenClawBlog Team

OpenClaw can remember a preference, a project decision, or a detail from an old conversation. That convenience makes one question unavoidable: where did the detail go, and what will remove it later?

The answer is not a single retention setting. OpenClaw has workspace memory files, session transcripts, search indexes, embeddings, consolidation records, and provider boundaries. Each layer has a different purpose and a different deletion path.

This guide is a lifecycle decision, not a compliance policy. The commands below come from current OpenClaw documentation; they were not run against a live installation for this article. The time windows in the example are proposed choices unless a source labels them as an OpenClaw default.

Start with the data layer

The OpenClaw memory overview describes memory as Markdown in the agent workspace. USER.md is an optional user-model layer. MEMORY.md contains curated durable facts and decisions. Dated files such as memory/YYYY-MM-DD.md hold working notes and raw context. DREAMS.md is optional and can contain consolidation summaries. There is no hidden memory outside what the workflow saves to disk.

That file layer is only part of the picture. Session rows and transcripts live in runtime state, while memory search can create full-text rows, vector rows, cached embeddings, short-term candidates, and source-origin records. A session reset can produce a new conversation context while leaving the previous transcript available. An index reset can clear search data while leaving the Markdown and transcripts untouched.

The final row is an operator boundary, not an OpenClaw promise. The memory documentation lists OpenAI as the default embedding provider and documents local alternatives. “The Gateway runs on my machine” therefore does not prove that every memory operation stays on that machine. Verify model and embedding endpoints before storing sensitive notes.

Decide what deserves durable memory

Use four questions for each candidate note:

1. Will it still be useful after the current task?
2. What is its expiry condition?
3. Who owns the fact or can change it?
4. Can an operator identify and remove it later?

The memory guide recommends recording action boundaries for approvals, temporary constraints, handoffs, safe-to-act timing, authority, and expiry. It also says memory does not enforce policy. A note can remind an agent that production work needs approval; it cannot replace tool approvals, sandboxing, or scheduled-task controls.

A hypothetical durable entry might look like this:

## API migration decision
- Status: active
- Owner: project maintainer
- Observed: 2026-05-10
- Review: 2026-06-01
- Expires: when the migration ships or is cancelled
- Source: approved design note
- Safe action: use as design input; do not edit production code from this note alone

This is an editorial convention, not an OpenClaw schema. When the decision changes, supersede the old entry instead of appending a contradictory instruction. Keep raw discussion in a dated note or transcript for the shorter period it serves. Do not promote secrets, access tokens, private customer material, or unverified instructions just because they may be useful later.

Separate context freshness from data retention

“Forget” can mean three different things: start a clean prompt, stop retrieving an old memory, or remove stored data. OpenClaw treats these as different operations.

Session reset controls conversation freshness. The session configuration documents none as the default automatic-reset mode, with opt-in daily and idle policies. /new and /reset are always available. The main-session documentation says reset assigns a new live session id but keeps the previous transcript searchable under the same main-session key. A reset is useful for active-context hygiene, not proof of erasure.

Context pruning is narrower. The session-pruning reference says pruning trims old tool results from the model's context while preserving full local history. Use pruning to manage prompt size and cost. Use retention controls when the question is how long records remain on disk.

• Use a new session when old conversation context is distracting.
• Use memory policy when a fact should or should not be recalled later.
• Use session maintenance when transcripts and rows have outlived their purpose.
• Use provider, backup, or filesystem procedures for copies outside OpenClaw.

A retention profile an operator can explain

For one operator running a personal assistant, I would start with this policy:

• Keep USER.md and MEMORY.md small. Review active instructions monthly and whenever the owner or project changes.
• Keep daily notes for 14 days. Promote only reviewed, non-sensitive facts.
• Use a 30-day stale-session cutoff, then decide whether durable sessions should be archived or removed. The current configuration reference documents pruneAfter: "30d" as the default.
• Set a separate wall-clock period for reset or deleted transcript archives if required. Without a duration, those archives can remain until disk-budget eviction.
• Begin in warn mode. OpenClaw documents it as reporting age, count, and disk effects without applying cleanup. Move to enforce after reviewing the results.

A configuration shape could be:

{
  session: {
    reset: { mode: "idle", idleMinutes: 240 },
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      resetArchiveRetention: "14d",
      maxEntries: 5000,
      maxDiskBytes: "10gb"
    }
  }
}

The idle reset here creates a fresh working context after four hours without real interaction. It is not a four-hour deletion timer. The maintenance values address session state; memory-file review remains a human workflow.

Use a deletion path that matches the layer

1. Identify the agent and record

Start with the agent id, session id or key, memory file, and possible external source. The session documentation lists openclaw status for the store path, openclaw sessions --json for session rows, and /context list for the current prompt. The upstream session reference places runtime rows in per-agent SQLite state and archived transcripts in the agent's sessions directory.

Use exact ids when a command requires them. The memory CLI documents case-sensitive matching. A participant selector can select an entire session, including other participants' contributions, so preview that scope first.

2. Review curated files

For USER.md, MEMORY.md, daily notes, and DREAMS.md, inspect the actual file. Replace an expired directive with a superseding entry or remove it according to the backup policy. A reported curated write is only a review clue; it does not delete freeform edits.

3. Purge tracked memory by provenance

When a sensitive memory came from a known session, preview the affected artifacts:

openclaw memory forget --agent main --session SESSION_ID --dry-run --json

Read the report, then repeat the same selector without --dry-run and preview again. The report can identify memory files, corpus lines, index chunks, vector rows, embedding-cache rows, short-term entries, backups, and origin rows.

The memory CLI reference says the command deletes immediately without dry-run and retains the source session transcript. It records forgotten sessions so later ingestion and forced indexing do not readmit them. Mixed-lineage entries are removed as a whole. Unmarked paraphrases, old diary text, exports, backups, and provider-side copies need separate review.

4. Age out sessions deliberately

Preview maintenance with:

openclaw sessions cleanup --dry-run

Current maintenance can archive eligible durable sessions while removing disposable automation rows. Pinned, active, admitted, or otherwise protected work may remain, and the store can stay above an entry or disk target when protected rows consume the budget.

Do not delete SQLite tables, corpus files, or origin records by hand. The memory documentation says deletion is not one transaction across files and stores. If a purge fails, fix the reported storage or filesystem problem, rerun the same selectors, and preview again. Pause other memory writers because the preview is not an immutable lock.

5. Close outside copies

OpenClaw's secrets, storage, and logs guide says transcripts can contain pasted secrets, file contents, command output, and links. Redaction is always on, but it does not rewrite old backups or erase copies already sent to logs, exports, providers, or backup systems. Review the Gateway host, backup snapshots, diagnostics, shell history, and model or embedding service used by the installation.

Failure paths and limits

memory reset removed search results, but the file remains. That is expected. It clears the built-in index and embedding cache without deleting sessions, transcripts, or memory files. It is an index rebuild tool, not a privacy purge.

The old fact still appears after a purge. Check MEMORY.md, daily notes, DREAMS.md, retained transcripts, and backups. The CLI warns that an empty selection or zero counters do not prove that no related data remains.

A reset made the chat look clean, but recall finds the old conversation. That is consistent with the main-session model. Reset changes the live session while the previous transcript remains searchable.

Dreaming promoted something that should have expired. The CLI lists a 30-day maxAgeDays value for deep-phase promotion, but that is a candidate-ranking input, not a promise that existing memory text will be erased after 30 days. Check the promoted file and its lineage.

Cleanup leaves more rows than the cap. Inspect protected sessions, pins, active work, durable external pointers, and the disk budget. OpenClaw intentionally preserves some records.

The durable answer is a small register: what was saved, where it lives, who owns it, when it expires, and how a reviewer can prove removal. OpenClaw supplies the pieces, but the retention policy is still an operator decision.

Sources

Sources were accessed on 2026-09-13. The official documentation pages do not state publication dates, so those fields are empty in the source record.

1. Memory overview - OpenClaw
2. Memory CLI - OpenClaw
3. Configuration: agent sessions - OpenClaw
4. Session management - OpenClaw repository
5. Session pruning - OpenClaw
6. The main session - OpenClaw
7. Secrets, storage, and logs - OpenClaw