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.

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

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

What lineage is recorded

Three records serve different purposes:

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.

When backfill coalesces the same claim from several sessions, it retains every source origin without counting the repeated claim as extra evidence.

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"],            },          },        },      },    },  },}

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

Matching requires retained session metadata; missing fields do not match a rule. 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.

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 staged by older versions. Inspect those separately.
• 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