Tab: Retention

The Retention tab configures per-agent data retention: a scheduled purge that permanently deletes conversations older than a cutoff, together with everything derived from them.

This is destructive and has no undo. A purge is a hard delete, not an archive. Export anything you need to keep before running one.

Reading the policy and the run history requires conversation:read. Saving, deleting, or running the policy requires conversation:delete.

The policy

One policy per agent. No policy means no purge — an agent’s data is kept indefinitely until a policy exists and is enabled.

• Enable — whether the scheduler runs this policy.
• Retention window — pick a preset or enter a custom number of days. Left unset, the deployment default (RETENTION_DEFAULT_DAYS) applies; the tab shows the current default.
• Cron expression and timezone — when the purge runs. The schedule is cron-only: an interval or one-shot schedule would fire once and then freeze the policy while still reading as enabled, so the API rejects it. An invalid cron expression is rejected on save.
• Preserve governance events — keeps governance_events rows for the purged conversations. Use it when governance records must outlive the conversation for legal retention.

The panel shows the policy’s next run and last run with its status. Reset deletes the policy entirely.

Cutoff and what gets deleted

The cutoff is computed once per run as now minus the retention window, and a conversation is expired when its last activity is older than that cutoff. The same cutoff is used by the audit row and the deletion, so the two never drift.

Deleting a conversation cascades, in one transaction per batch (500 conversations at a time), to:

• its messages;
• the AI-gateway call log rows and pipeline traces for it;
• tool audit logs and hook executions;
• governance events — unless Preserve governance events is on;
• memories extracted from it;
• its conversation state and its encrypted per-conversation credentials;
• the conversation row itself.

Conversations are the unit of deletion: an agent’s prompts, tools, skills, secrets, channels, and knowledge base are never touched by retention. Because only extracted memories are removed, keyword search over the remaining raw messages keeps working.

Running it

Two buttons under Execute:

• Dry run — computes the cutoff and reports how many conversations would be purged, without deleting anything. Do this first.
• Run now — purges immediately, behind a confirmation dialog. It requires a saved policy; run it after saving, not with unsaved edits on screen.

The scheduler checks for due policies every 30 seconds and catches up on runs that came due while the process was down. Due policies run one at a time — each purge is already batched and DB-heavy.

Run history

Every pass, scheduled or manual, is audited in the runs table: cutoff, trigger (scheduled or manual), dry-run flag, status, per-table deleted counts, conversations scanned, duration, and any error. The audit stores counts only — never the deleted content.

A process that dies mid-purge leaves its policy marked running until the row is reset manually; the next tick skips a policy in that state rather than purging twice.

Configuration writes and purge runs are also recorded in the management audit log with the acting operator.

See also

• Privacy — messaging opt-out.
• Conversations — deleting a single conversation by hand, same cascade.
• Compliance — snapshots and reports, which are not affected by a purge.