---
title: "Forget memories matching a prompt/query"
method: POST
path: "/v4/memories/forget-matching"
tags: ["Content Management"]
---

# Forget memories matching a prompt/query

`POST /v4/memories/forget-matching`

Agentic mass-forget. Given a prompt or query, a tool-calling agent searches the container's memories and soft-deletes everything matching the target. Use dryRun to preview first.

## Request body

- object
  - `query` string — Natural-language instruction ('forget everything about Project Titan') or a bare topic ('Project Titan'). The service searches the container's memories and selects matches to forget. Provide either query or ids.
  - `ids` string[] — Forget exactly these memory ids, with no semantic search. Ids are validated against the containerTag, so unknown or out-of-scope ids are ignored. Provide either query or ids.
  - `containerTag` string, required — Container tag / space the forget operation is scoped to.
  - `dryRun` boolean — When true, returns the memories that WOULD be forgotten without mutating anything. Defaults to false (forgets for real).
  - `threshold` number — Minimum cosine similarity a memory must have to be considered. Lower = wider net. Defaults to 0.5.
  - `maxForget` integer — Maximum number of memories this call may forget. Defaults to 100, max 500.
  - `reason` string — Optional reason stored as forgetReason on each memory.

## Response `200`

Forget operation completed (or previewed)

- object — Response after an agentic mass-forget
  - `dryRun` boolean, required — Whether this was a preview (no mutation) or a real forget
  - `count` number, required — Number of memories selected / forgotten
  - `forgetBatchId` string, nullable, required — ID tagged on every memory forgotten in this call (null on dryRun)
  - `summary` string, required — The agent's one-line summary of what it did
  - `candidates` object[] — On dryRun: the memories that would be forgotten
    - `id` string, required — Memory ID
    - `memory` string, required — Memory content
    - `score` number, required — Similarity score against the forget query
  - `forgotten` object[] — On apply: the memories that were forgotten
    - `id` string, required — Memory ID
    - `memory` string, required — Memory content
    - `score` number, required — Similarity score against the forget query

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `500` — Server error

---

[API](https://skmtc.dev/supermemory/apis/supermemory-api.md) · [All operations](https://skmtc.dev/supermemory/apis/supermemory-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/supermemory/supermemory-api/revisions/b8c2dbc8f2b5/schema)