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

# Purge Expired Memories

> Permanently delete memories expired longer than the purge window.

## Overview

Permanently deletes memories that have **already been expired** for longer than
the policy's `purge_expired_after` window.

<Warning>
  This is the only destructive step in the memory lifecycle and it cannot be undone.
  Purged memories are removed from the backend —
  [Restore Memory](/api-reference/data/restore-memory) will not bring them back.
  Always preview with `dry_run: true` first.
</Warning>

Disabled unless the policy sets `purge_expired_after`; when disabled the endpoint
returns `enabled: false` and deletes nothing.

## Authentication

API clients do not send an API key or `Authorization` header.

<ParamField header="X-Session-Token" type="string" required>
  Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the agent.
</ParamField>

## Body

<ParamField body="dry_run" type="boolean" default="false">
  When `true`, report what would be deleted without deleting anything.
  The body may be omitted entirely to accept the default.
</ParamField>

## Response Fields

<ResponseField name="enabled" type="boolean">
  `false` when the policy leaves `purge_expired_after` at `never`. Everything
  else is zeroed in that case.
</ResponseField>

<ResponseField name="matched" type="integer">
  Expired memories older than the purge window.
</ResponseField>

<ResponseField name="purged" type="integer">
  Memories actually deleted. Always `0` on a dry run.
</ResponseField>

<RequestExample>
  ```bash cURL (preview) theme={null}
  curl -X POST "http://localhost:8000/api/v2/agents/my-agent/policy/purge" \
    -H "X-Session-Token: your_session_token" \
    -H "Content-Type: application/json" \
    -d '{"dry_run": true}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "agent_id": "my-agent",
    "dry_run": false,
    "enabled": true,
    "purge_expired_after": "365d",
    "matched": 1,
    "purged": 1,
    "memories": [
      {
        "id": "d6d622be-49d5-4f4d-921a-64140f24dc98",
        "title": "Deploys go through the release bot",
        "expired_at": "2025-08-01T15:27:00+00:00",
        "expired_by": "manual"
      }
    ],
    "errors": [],
    "evaluated_at": "2026-08-18T19:56:29.873259+00:00"
  }
  ```

  ```json 200 - OK (purging disabled) theme={null}
  {
    "agent_id": "my-agent",
    "dry_run": false,
    "enabled": false,
    "matched": 0,
    "purged": 0,
    "memories": [],
    "errors": [],
    "evaluated_at": "2026-08-18T19:56:29.873259+00:00"
  }
  ```

  ```json 401 - Unauthorized (Missing Token) theme={null}
  {
    "detail": "Missing session token. Use X-Session-Token header."
  }
  ```
</ResponseExample>

## Notes

* `purge_expired_after` is **not** a retention setting. `retention` decides what becomes `expired`; this decides when an already-expired memory is destroyed. The two act on different populations, so [Apply Expiry Policy](/api-reference/policy/apply-policy) reporting `matched: 0` says nothing about what is purgeable.
* The window is measured from `expired_at`, not from when the memory was created.
* An expired memory carrying no `expired_at` stamp has no defensible purge date and is never purged.

## Next Steps

* [Set Expiry Policy](/api-reference/policy/set-policy) to change the purge window
* [Apply Expiry Policy](/api-reference/policy/apply-policy) for the non-destructive sweep