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

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.

Edit this page View as Markdown Report an issue