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}'
{
"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"
}
{
"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"
}
{
"detail": "Missing session token. Use X-Session-Token header."
}
Expiry Policy
Purge Expired Memories
Permanently delete memories expired longer than the purge window.
POST
/
api
/
v2
/
agents
/
{agent_id}
/
policy
/
purge
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}'
{
"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"
}
{
"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"
}
{
"detail": "Missing session token. Use X-Session-Token header."
}
Overview
Permanently deletes memories that have already been expired for longer than the policy’spurge_expired_after window.
This is the only destructive step in the memory lifecycle and it cannot be undone.
Purged memories are removed from the backend —
Restore Memory will not bring them back.
Always preview with
dry_run: true first.purge_expired_after; when disabled the endpoint
returns enabled: false and deletes nothing.
Authentication
API clients do not send an API key orAuthorization header.
string
required
Session token from Activate Agent. Must match
agent_id.string
required
Must be
application/jsonPath Parameters
string
required
The unique identifier of the agent.
Body
boolean
default:"false"
When
true, report what would be deleted without deleting anything.
The body may be omitted entirely to accept the default.Response Fields
boolean
false when the policy leaves purge_expired_after at never. Everything
else is zeroed in that case.integer
Expired memories older than the purge window.
integer
Memories actually deleted. Always
0 on a dry run.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}'
{
"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"
}
{
"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"
}
{
"detail": "Missing session token. Use X-Session-Token header."
}
Notes
purge_expired_afteris not a retention setting.retentiondecides what becomesexpired; this decides when an already-expired memory is destroyed. The two act on different populations, so Apply Expiry Policy reportingmatched: 0says 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_atstamp has no defensible purge date and is never purged.
Next Steps
- Set Expiry Policy to change the purge window
- Apply Expiry Policy for the non-destructive sweep