> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Forget memories matching a prompt/query

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



## OpenAPI

````yaml https://api.supermemory.ai/v3/openapi post /v4/memories/forget-matching
openapi: 3.1.0
info:
  title: supermemory API
  description: The Memory API for the AI era
  version: 3.0.0
servers:
  - description: Production Server
    url: https://api.supermemory.ai
security:
  - bearerAuth: []
tags:
  - name: Ingest
    description: Ingest documents, files, URLs, conversations, and other content
  - name: Recall (Search)
    description: >-
      Semantic recall across your content — supports memories, hybrid, and
      documents modes
  - name: Profiles
    description: >-
      Entity profiles for users, participants, or any entity — includes profile
      search
  - name: Content Management
    description: List, get, update, and delete content and memories
  - name: Spaces
    description: Organize content into spaces (container tags)
  - name: Knowledge Graph
    description: Knowledge graph and entity relationships
  - name: Connections
    description: External service integrations
  - name: Settings
    description: Organization settings
  - name: Analytics
    description: Usage analytics and insights
  - name: Documents
    description: List, get, and search documents
paths:
  /v4/memories/forget-matching:
    post:
      tags:
        - Content Management
      summary: Forget memories matching a prompt/query
      description: >-
        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.
      operationId: postV4MemoriesForgetMatching
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: >-
                    Natural-language instruction ('forget everything about
                    Project Titan') or a bare topic ('Project Titan'). An agent
                    searches the container's memories and selects matches to
                    forget.
                  example: forget everything about Project Titan
                containerTag:
                  type: string
                  maxLength: 100
                  pattern: ^[a-zA-Z0-9_:-]+$
                  description: Container tag / space the forget operation is scoped to.
                  example: user_123
                dryRun:
                  default: false
                  description: >-
                    When true, returns the memories that WOULD be forgotten
                    without mutating anything. Defaults to false (forgets for
                    real).
                  example: false
                  type: boolean
                threshold:
                  default: 0.5
                  description: >-
                    Minimum cosine similarity a memory must have to be
                    considered. Lower = wider net. Defaults to 0.5.
                  example: 0.5
                  type: number
                  minimum: 0
                  maximum: 1
                maxForget:
                  default: 100
                  description: >-
                    Maximum number of memories this call may forget. Defaults to
                    100, max 500.
                  example: 100
                  type: integer
                  minimum: 1
                  maximum: 500
                reason:
                  description: Optional reason stored as forgetReason on each memory.
                  example: project cancelled
                  type: string
              required:
                - query
                - containerTag
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  dryRun:
                    type: boolean
                    description: Whether this was a preview (no mutation) or a real forget
                  count:
                    type: number
                    description: Number of memories selected / forgotten
                  forgetBatchId:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      ID tagged on every memory forgotten in this call (null on
                      dryRun)
                  summary:
                    type: string
                    description: The agent's one-line summary of what it did
                  candidates:
                    description: 'On dryRun: the memories that would be forgotten'
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Memory ID
                        memory:
                          type: string
                          description: Memory content
                        score:
                          type: number
                          description: Similarity score against the forget query
                      required:
                        - id
                        - memory
                        - score
                  forgotten:
                    description: 'On apply: the memories that were forgotten'
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Memory ID
                        memory:
                          type: string
                          description: Memory content
                        score:
                          type: number
                          description: Similarity score against the forget query
                      required:
                        - id
                        - memory
                        - score
                required:
                  - dryRun
                  - count
                  - forgetBatchId
                  - summary
                description: Response after an agentic mass-forget
          description: Forget operation completed (or previewed)
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  details:
                    description: Additional error details
                    example: Query must be at least 1 character long
                    type: string
                  error:
                    type: string
                    description: Error message
                    example: Invalid request parameters
                required:
                  - error
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  details:
                    description: Additional error details
                    example: Query must be at least 1 character long
                    type: string
                  error:
                    type: string
                    description: Error message
                    example: Invalid request parameters
                required:
                  - error
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                type: object
                properties:
                  details:
                    description: Additional error details
                    example: Query must be at least 1 character long
                    type: string
                  error:
                    type: string
                    description: Error message
                    example: Invalid request parameters
                required:
                  - error
          description: Server error
components:
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````