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
spacescope. The topics themselves are deleted, so the text is no longer readable or searchable through the API.
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.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.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.

