Retention

Choose how long Cereal keeps session events, hook deliveries, traces, and usage.

await client.environments.update({
  update: {
    slug: "dev",
    retention: {
      sessionEventsDays: 30,
      deliveredHooksDays: 7,
      deadHooksDays: 30,
      spansDays: 14,
      usageRollupDays: 400
    }
  }
})

An omitted field in the policy means unlimited retention. {} keeps all categories without a time limit. A value of 0 makes eligible data removable on the next retention pass.

Window	Default	Data
`deliveredHooksDays`	7	Successful event-hook deliveries.
`deadHooksDays`	30	Failed deliveries that may need redelivery.
`spansDays`	90	Session traces.
`sessionEventsDays`	unlimited	A pruned session cannot be resumed: the prompt is folded from the log and nothing else.
`usageRollupDays`	unlimited	Aggregated model usage.

What it never touches

A live session. Pruning underneath a running turn would make the next model request wrong rather than merely losing history.
A pending hook delivery, however old. It is still going to be attempted, so it is still pending.
An archived environment. Archiving is what you do when you want the history kept and nothing written.

After session events are pruned, sessions.send and sessions.decide return SessionPruned (HTTP 422) with prunedAt. Start a new session to continue working. You can still interrupt the old session or update its metadata.

const session = await client.sessions.get({ id })
session.eventsPrunedAt        // an empty transcript reads as a policy, not a bug

const trace = await client.traces.forSession({ id })
trace.prunedAt

The control plane's Environments page has the five windows with a one-click "keep very little" preset for a development environment.

What it never touches

How you can tell

On this page