Skip to main content
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.
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

Scopes

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

Purge requests are not billed.