forget

Verify a deletion

Re-run the search that previously returned the memory. Deletion is only confirmed when the entry no longer appears.

search_memory({ query: "<the removed content>", limit: 5 })
// -> the removed entry must be absent

Public MCP tool

forget

Purpose

Delete a selected memory, TODO, or Ledger-backed record through the user-owned control boundary. The public contract covers soft and hard deletion only; use redact_memory to replace content in place.

When to use

A user explicitly asks to remove a reviewed record and supplies an exact reference when possible.
The caller needs recoverable deletion, which is the default public behavior, or an explicitly confirmed permanent delete.
A known TODO or Ledger transaction ID must be removed through the same governed lifecycle.

When NOT to use

Do not use it to redact or replace content: public forget rejects replacement_content; call redact_memory instead.
Do not use a guessed query to bulk-clean data; resolve and review an exact target first.
Do not use mode=hard unless the user explicitly confirms permanent, irreversible deletion.
Do not use it to revise a memory's content; use an update/correction workflow when available.
The REST API accepts a wider field set than the public MCP tool; see /docs/api/memory for scope, bucket, team and provenance filters.

Required scope

Public forget requires memory:write; deployment policy may require an additional destructive capability for hard deletion.
The caller must be authorized for the target's owner/team/scope boundary.

Parameters

Name	Type	Description
`memory_id`	string	Exact reference of the record to remove. Preferred over target.
`target`	string	Descriptive target when no exact reference is available.
`mode`	string · default: soft	'soft' (default, recoverable) or 'hard' (permanent, requires explicit user confirmation first). The 'soft_delete' and 'hard_delete' aliases are accepted, and an empty value means soft. Any other value is rejected.
`reason`	string	Short audit reason recorded with the deletion.

Return schema

Success text reports the affected opaque reference and lifecycle status. Soft deletion remains recoverable through the restore path; hard deletion does not.

Examples

Recoverably remove an exact record

forget({
  target: "memory-id-from-recall",
  mode: "soft",
  reason: "User requested removal"
})

Errors

Validation failure: a mode other than 'soft'/'soft_delete'/'hard'/'hard_delete' is supplied, or replacement_content is set (use redact_memory).
401/403: the token lacks the required write/delete capability or cannot access the target.
Ambiguous target: query_hint matches multiple records or no exact target can be established.
Invalid mode: hard deletion is not inferred, and unsupported modes are rejected on the public surface.
Not found or lifecycle conflict: the selected memory, TODO, or Ledger record is already absent or changed.

search_memory — Find a strict, authorized result before destructive action.
remember — Create a new durable record only when it is actually needed.
todos — Manage task state directly; use forget only for a reviewed delete.
ledger — Manage financial records through the governed Ledger dispatcher.

Source: Memory Console controls