---
title: Retention
description: How long ClawMetry keeps events, the tier caps, the override variable, and what actually gets deleted when a window expires.
keywords: agent data retention, clawmetry retention days, telemetry retention policy
eyebrow: Data & storage
---

# Retention

The store grows with your agents. Retention bounds it.

## The window

```bash
clawmetry retention
clawmetry retention --json
```

```json
{
  "tier": "cloud_pro",
  "retention_days": 90,
  "effective_retention_days": 90,
  "override_env_name": "CLAWMETRY_RETENTION_DAYS",
  "override_env_value": null
}
```

Note the two numbers: `retention_days` is the tier's cap, and
`effective_retention_days` is what is actually applied after any override.

## Tier caps

| Tier | Retention |
|---|---|
| OSS / Free | 7 days |
| Trial | 30 days |
| Starter | 30 days |
| Pro (cloud or self-hosted) | 90 days |
| Enterprise | Unlimited |

```bash
clawmetry retention --why 90    # what tier a 90-day window needs
```

## Overriding

```bash
export CLAWMETRY_RETENTION_DAYS=30
```

The override cannot exceed the tier cap. Setting it higher than the tier allows
does not extend the window; `clawmetry retention --json` shows both numbers so
you can see when that is what happened.

Setting it *lower* than the cap always works — a deliberate choice to keep less
than you are entitled to, which is a reasonable privacy position.

| Variable | Effect |
|---|---|
| `CLAWMETRY_RETENTION_DAYS` | The window, within tier limits |
| `CLAWMETRY_RETENTION_INTERVAL_HOURS` | How often the retention pass runs |
| `CLAWMETRY_EVENT_RETENTION` | Related event-level retention control |

## What gets deleted

Events past the window. **Rollups are not deleted** — the per-day, per-runtime
and per-model summaries persist, so your long-term cost history survives a short
retention window even though the individual events do not.

That is the shape you usually want: you can still answer "what did March cost"
long after you can no longer read March's transcripts.

## What retention does not do

- It does not delete anything already pushed to the cloud. Cloud retention is
  governed separately.
- It does not shrink the file on its own. Deleted rows leave dead versions
  behind until compaction runs — which is why a store can report a size well
  above its live data.

```bash
curl -s localhost:8900/api/local/health | jq '{size_bytes, live_rows}'
```

| Variable | Effect |
|---|---|
| `CLAWMETRY_AUTO_VACUUM` | Automatic compaction after a retention pass |
| `CLAWMETRY_LOCAL_MAX_GB` | Soft cap that triggers earlier cleanup |

## Choosing a window

| You want | Window |
|---|---|
| To read yesterday's session and answer cost questions | 7 days is enough |
| To debug a regression that appeared last sprint | 30 days |
| To compare quarters, or answer an audit question | 90 days or unlimited |
| To keep as little as possible | Set it low; rollups keep the totals |

If you need history beyond your window, export before it expires.
→ [Exports](/docs/data/export/)

## Deleting on demand

To remove everything:

```bash
clawmetry uninstall     # removes the store along with everything else
```

To remove the store but keep the install, stop the daemon and delete the file —
it is rebuilt from the runtimes' own stores on the next sync, which means "start
fresh" is genuinely cheap.

```bash
clawmetry sync --restart   # stop it properly first
rm ~/.clawmetry/local_store.duckdb
clawmetry sync
```

Note that this re-ingests whatever the runtimes still have, bounded by
`CLAWMETRY_FAMILY_SESSION_LIMIT` — so it is a reset, not necessarily a deletion
of history that still exists elsewhere on disk.