Memory provenance and deletion

OpenClaw records source-session lineage for memories staged by automatic session ingestion and historical session backfill. openclaw memory forget uses that lineage to remove tracked entries and related artifacts, and records the selected sessions as forgotten so later ingestion does not restore them.

Two controls serve different purposes: admission policy excludes matching sessions from future dreaming ingestion and session backfill; forget removes identifiable artifacts from selected sessions. Neither is a general erasure of everything the agent has seen or written.

These controls belong to the bundled memory-core plugin. Other memory plugins may expose different commands and deletion behavior.

memory forget deletes immediately unless you pass --dry-run. It does not delete original session transcripts, every freeform memory edit, or copies outside the memory stores it scans. Review the report and the deletion boundaries before applying it.

Preview and forget a session

Use an explicit agent so you know which store you are changing. List its sessions to find the full session key or ID. Session IDs are exact and case-sensitive; an abbreviation does not select a longer ID:

openclaw sessions --agent <agent-id> --limit all --json
openclaw memory forget --agent <agent-id> --session <id-or-key> --dry-run --json

Check sessionResolutions for the intended sessions, entryKeys and mixedLineageEntryKeys for whole-entry removals, and artifacts for the affected stores. Review curatedWrites and untargetableEntryKeys separately; neither is a complete inventory of data that will remain.

When the selection is correct, repeat the same command without --dry-run:

openclaw memory forget --agent <agent-id> --session <id-or-key> --json

There is no additional confirmation prompt or --apply flag. A preview is computed from current state, not saved as a deletion plan. Pause direct agent edits and external writers during a sensitive cleanup; they do not share the memory plugin’s mutation lock. Run the preview again afterward to check for remaining attributable artifacts.

If deletion fails, resolve the reported storage or filesystem error, rerun the same command, then repeat it with --dry-run. A failure can leave partial cleanup. The purge keeps corpus and origin evidence until dependent artifacts are cleaned; do not delete that evidence manually to clear an error.

The full flags, selector semantics, and report fields are in memory forget.

What lineage is recorded

Three records serve different purposes:

Record	Granularity	Written by	Used for
Chunk provenance	Index chunk	Classification code at index time	Trust gating and recall framing
Entry origins	Tracked entry	Session ingestion, backfill, and consolidation	Finding entries derived from a selected session
Curated-write records	Memory file	The memory write observer	Identifying files to review during a purge

Chunk provenance describes the origin class and session kind. Entry origins instead associate an entry key with an agent and source session in SQLite. Promotion markers in MEMORY.md connect the visible entry to those origin rows.

When dreaming merges or supersedes tracked entries, reconciliation transfers the parents’ origins to the surviving entry. It runs in code around the model call, including for participating agents that share a workspace; the model does not own the origin rows.

Origins for replaced entries remain while retained rewrite preimages still reference their promotion markers. Backup rotation prunes those origins only when live entries, retained preimages, diary excerpts, and indexed snapshots no longer reference them.

New consolidation-history excerpts retain the replacement entry’s lineage, including its merged or superseded parents. Their origin rows remain while those excerpts remain, even after backup rotation. Diary history has no automatic expiry; long revision histories can retain growing origin sets.

When backfill coalesces the same claim from several sessions, it retains every source origin without counting the repeated claim as extra evidence. Session-backfill diary lines also carry markers tied to source origins before publication. This includes REM facts, reflections, and combined claims, even when displayed citations are shortened or a later apply step fails. Forgetting any contributing session removes the whole marked line, not unrelated diary lines. Earlier unmarked backfill diaries do not gain lineage retroactively.

Coverage is not universal. Handwritten notes, direct agent edits, and entries staged before lineage tracking may lack entry origins. The report’s untargetableEntryKeys lists promotion markers with no origins in the selected agent’s store, not all untracked prose. Such entries cannot be selected by lineage alone, although explicit session references or exact corpus quotations may still match the file scrub.

Admission: keeping sources out of memory

To keep Gmail hook sessions out of dreaming ingestion and session backfill:

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          memoryPolicy: {
            excludeSessions: {
              hookExternalContentSources: ["gmail"],
            },
          },
        },
      },
    },
  },
}

IMAP uses the exact hook source email; Gmail hooks use gmail. Include both values to exclude both sources. Generic webhooks use webhook.

You can also exclude channel/plugin identifiers (not room IDs) or chat types. Empty or omitted lists add no policy exclusions. A match in any list excludes the whole session; values match recorded session metadata, not words in the conversation.

Both paths check the policy before reading the transcript. Automatic ingestion also records the exclusion reason in its ingestion checkpoint. Removing a matching rule makes a session eligible for a later sweep, subject to the other trust and ingestion gates. A session recorded as forgotten remains excluded.

Policy is prospective: it does not erase an existing corpus, staged candidate, or promoted entry. Use memory forget for existing attributable data. See Memory config for exact matching rules and exclusion reasons.

The admission boundary

Path	Configured admission exclusions
Automatic dreaming ingestion	Applied before transcript reads
Manual session-backfill	Applied in preview, REM, and apply modes
Raw transcript indexing	Not applied
Direct writes and session hooks	Not applied

Matching requires retained session metadata; missing fields do not match a rule. Both controls honor the configured session.store, including custom and shared stores, while keeping selection scoped to the chosen agent. Older retained records may have only a coarse webhook classification; without the original exact source, OpenClaw does not infer email or webhook for matching. Select those sessions explicitly by full ID.

Automatic dreaming separately skips retained archives. To exclude an archived session from backfill and transcript indexing too, explicitly forget its full session ID. Those paths check forgotten-session records even when the former channel, chat type, or hook-source metadata is no longer available.

An excluded session can still edit MEMORY.md, USER.md, or another workspace file if its tools permit it. Restrict the relevant file, shell, and external-harness capabilities when you need to prevent those writes, and review enabled memory-writing hooks. Admission policy is not a filesystem permission. Observed writes are reported for review, not given per-entry lineage.

Deletion: purging what a session produced

Selectors identify sessions, not individual facts about a person. --participant selects sessions with that recorded actor ID; it does not search memory text for a name. --hook-source selects sessions with that recorded external-content source. Both require retained metadata. Explicit IDs and keys can also resolve retained archives.

A tracked entry with any selected origin is removed whole, even when it also has unselected origins. These removals appear in mixedLineageEntryKeys. The purge does not ask a model to subtract one person’s contribution from merged prose. Surviving sources may support a new entry later, but automatic reconstruction is not guaranteed.

The cleanup covers matching promoted entries, session-corpus lines, memory index chunks and their full-text/vector rows, cached embeddings, short-term state, ingestion deduplication state, and dreaming rewrite preimages. It also removes whole lines containing exact selected corpus snippets from scanned memory files and dream diaries. The command reference describes the counters and selection limits.

Purged sessions stay purged

A real purge records each selected session as forgotten in the selected agent’s SQLite database before removing its artifacts. Automatic ingestion, historical session backfill, and transcript indexing, including memory index --force, check these records. Automatic ingestion records the reason forgotten.

The memory plugin coordinates purges with its staging and file mutations. A pending dream narrative is skipped if its tracked source entries or prior diary context were removed before publication. This does not retroactively identify untracked paraphrases in older diary entries. Historical consolidation highlights with quoted markers also lack reliable deletion boundaries. The report warns in refusals when it recognizes remaining highlights in that format; review them manually. The warning is not an inventory of all untracked history, and missing historical lineage is not reconstructed.

Indexing checks again before publishing chunks or cached embeddings, so a result prepared before the purge cannot restore forgotten session data or a stale memory-file snapshot. An affected index run reports that its source changed; rerun openclaw memory index --agent <agent-id> to index current data.

Repeating a purge does not lift that exclusion. It applies to those session IDs in that agent’s store, not to future conversations with the same person or hook source. Keep an admission rule for future matching sessions, within the admission boundary.

What deletion does not cover

• Original transcripts and archives. Memory cleanup leaves them in the session store. Session deletion is a separate lifecycle operation and ordinarily retains a deleted-transcript archive. Do not treat either command as proof that all conversation copies have been erased.
• Untracked older memories. No origin row means no lineage-based deletion. New session backfill preserves origins, but it does not retroactively supply lineage for candidates or rewrite backups whose origins were lost in older versions. Inspect those separately; a prior purge is not automatically repaired.
• Freeform edits. curatedWrites reports recognized writes or write attempts with a relativePath and observedAt. That record alone does not delete a file or identify contributing lines. Supported write/edit/patch transcript records supplement the latest file-level observer record, but can include unsuccessful attempts. Arbitrary shell writes and external edits are not fully tracked.
• Paraphrases and other copies. Exact corpus quotations can be removed, but untracked paraphrases, exports, external backups, other plugins’ stores, and independently copied files are outside this cleanup. A reported curated file can still lose lines that match a tracked entry or exact quotation.
• Other agents. Selection and forgotten-session records are per agent. Repeat the review for each relevant agent, including agents sharing a workspace; one agent’s report does not establish that every index is clean.

An empty preview means no more artifacts were found by those selectors and matching rules. It is not a certificate that no related information remains.

Purging a person or a source end to end

For a participant, start with a preview in each relevant agent:

openclaw memory forget --agent <agent-id> --participant <actor-id> --dry-run --json

Verify the resolved session IDs before removing --dry-run. This removes tracked entries derived from any content in those sessions, not only messages authored by that participant. If participant metadata is missing from an archive, add its explicit --session <id-or-key> selector.

For a source, use its recorded hook identifier:

openclaw memory forget --agent <agent-id> --hook-source gmail --dry-run --json

After applying the reviewed selection, inspect retained files and untracked memories, handle transcript and archive retention separately, and rerun the preview. Add an admission rule if future sessions from that source should also stay out of dreaming ingestion and session backfill.

Related

• memory forget command reference
• Memory admission policy configuration
• Memory architecture
• Dreaming
• Built-in memory