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

# Purge a Memory Space

> Permanently delete all memory data in a memory space, an app or a project, in two confirmed steps

A purge permanently deletes the memory data in a whole memory space, or in one app or project inside it. When it finishes, the space is empty and ready to use again.

> [!WARNING]
>
> A purge is **permanent. There is no undo.** Unlike `/api/v2/memory/delete` and `/api/v2/memory/delete_by_ids`, which soft-delete, a purge physically removes the data, including memories that were already soft-deleted.

Purge is **Cloud-only**.

## When to Purge

| You want to remove | Use |
| - | - |
| A few specific memories | [`delete_by_ids`](https://docs.evermind.ai/api-reference/memory/soft-delete-memory-records-by-id-%5Bcloud-only%5D) |
| Everything for one user, agent or session | [`delete`](https://docs.evermind.ai/api-reference/memory/delete-memories-%5Bcloud-only%5D) |
| Everything in a memory space, an app or a project | Purge |

## Scopes

| `scope` | Deletes | Also send |
| - | - | - |
| `space` | All memory data in the memory space your API key belongs to, including its knowledge bases | nothing else |
| `app` | The memory data of one app | `app_id` |
| `project` | The memory data of one project in one app | `app_id`, `project_id` |

Each scope takes exactly the ids in its row. An extra id is rejected rather than ignored, so a request can never look narrower than the purge it starts: `"scope": "space"` with an `app_id` is a `422`.

Memory data means memories (episodes, facts, profiles, agent cases and skills), sessions, messages, memory cells, feedback and events, in every index. Two things are only deleted at `space` scope, because they belong to the whole memory space rather than to an app or project: knowledge bases (`/api/v2/knowledge_bases`) and sender records.

A knowledge base purge removes its categories, documents and topics, and every search index entry for them. What stays behind is bytes in object storage that the API can no longer reach:

* **Files you uploaded through `/api/v2/object/sign`**, at any scope. Download links already handed out keep working until they expire.
* **The stored text of knowledge base topics**, at `space` scope. The topics themselves are deleted, so the text is no longer readable or searchable through the API.

A purge empties the memory space as far as the API is concerned. It does not yet guarantee that every stored byte is gone, so do not rely on it alone for a request to erase all of a person's data.

## How a Purge Works

A purge takes two calls, so that a single mistaken request cannot wipe your data, and runs as a background job.

**1. Request the purge**

`POST /api/v2/memory/purge` with the scope. **Nothing is deleted yet.** You get back a `nonce`, its `expires_at`, and a `summary` of what the purge would delete right now.

```bash theme={null}
curl -X POST https://api.evermind.ai/api/v2/memory/purge \
  -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" \
  -d '{"scope": "project", "app_id": "my_app", "project_id": "staging"}'
```

```json theme={null}
{
  "request_id": "...",
  "data": {
    "nonce": "<nonce>",
    "expires_at": "2026-11-06T08:05:00.176879Z",
    "scope": "project",
    "app_id": "my_app",
    "project_id": "staging",
    "summary": {
      "mongo": {
        "episodes": 3, "atomic_facts": 13, "foresights": 0, "profiles": 1,
        "cases": 0, "skills": 0, "clusters": 1, "mem_scenes": 0,
        "reflection_reports": 0, "memory_events": 2, "memcells": 4,
        "raw_messages": 6, "sessions": 1
      },
      "mongo_total": 31,
      "elasticsearch_total": 16,
      "milvus_total": 16,
      "complete": true,
      "counted_at": "2026-11-06T08:00:00.197765Z",
      "comment": "Counts are taken at request time and include soft-deleted items, ...",
      "error": null
    }
  }
}
```

Check the `summary` before you confirm. It is a snapshot: data written before the purge runs is deleted too. Counts include soft-deleted records, so they can be higher than what `get` shows. If a count does not finish in time, it is `null` and `complete` is `false`; the request still succeeds.

**2. Confirm within 5 minutes**

`POST /api/v2/memory/purge/confirm` with the `nonce`, before `expires_at`. The purge is queued and you get `202` with the job.

```bash theme={null}
curl -X POST https://api.evermind.ai/api/v2/memory/purge/confirm \
  -H "Authorization: Bearer <api_key>" -H "Content-Type: application/json" \
  -d '{"nonce": "<nonce>"}'
```

The scope is the one the nonce was issued for; the confirm body cannot change it. A nonce works once, only within the same memory space and with the same API key.

**3. Poll the job**

`GET /api/v2/memory/purge/{job_id}` until `status` is `succeeded` or `failed`.

```bash theme={null}
curl https://api.evermind.ai/api/v2/memory/purge/<job_id> \
  -H "Authorization: Bearer <api_key>"
```

`status` goes `queued` → `running` → `succeeded` or `failed`. `steps` lists every store the purge touches, with its own `state` and `deleted` count. On a large memory space a purge can take minutes.

## While a Purge Runs

* **Writes are rejected.** From the moment you confirm until the job ends, every write to the memory space (add, flush, delete, update, feedback, tags, knowledge base changes) returns `409 purge_in_progress`, whatever the purge's scope. Retry after the job ends.
* **Reads keep working**, but may return partial results.
* **One purge at a time.** Confirming while a purge is queued or running returns that job instead of starting another.

## Errors and Limits

| Response | When |
| - | - |
| `404 purge_nonce_invalid` | The nonce is unknown, expired, already used, or from another memory space or API key. Nothing happens; request a new one. |
| `409 purge_in_progress` | A write reached the memory space while a purge was queued or running. |
| `422` | `scope` is missing or not one of `space`, `app`, `project`, or the ids do not match the scope (missing, or extra). |
| `429` | Each memory space can send `/purge` and `/purge/confirm` only a limited number of times per minute (10 each by default). Wait for the `Retry-After` header. Requests that are rejected do not count. |

Purge requests are not billed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.