Made by@usagemetricsRetention cohorts
@usagemetrics/retention-cohorts
Build weekly or monthly retention cohorts for users or accounts from an events CSV. Writes the cohort table, a size-weighted average curve, where the curve flattens, and the best and worst cohorts, as markdown, CSV, and JSON.
- Activity
- New: be the first to try it
- Installs
- 0 installs
- Likes
- 0 likes
- Clones
- 0 clones
- 1---
- 2name: retention-cohorts
- 3description: Build retention cohort tables (weekly or monthly, by user or by account) from a product events export, with a size-weighted average retention curve, where it flattens, and the best and worst cohorts. Use when the user asks about retention, cohort analysis, "do users come back", "is retention getting better", logo retention by signup month, or wants a cohort triangle or heatmap for a board deck or product review.
- 4license: MIT
- 5---
- 7# Retention cohorts
- 9The classic retention triangle, done right: cohorts by first activity, incomplete periods left blank instead of shown as drops, and an average curve weighted by cohort size so one tiny cohort cannot swing it.
- 11## Inputs
- 13An events CSV in `data/` with `timestamp`, `account_id`, `user_id`, `event` (the same file the `saas-usage-dashboard` kit uses). Decide with the user:
- 151. **Period:** `month` for B2B tools used a few times a month; `week` for products used weekly or more. Default month.
- 162. **Entity:** `user` (do people come back?) or `account` (do customers keep using it?). Account retention is usually what leadership means by "logo retention" in usage terms.
- 173. **What counts as active:** by default any event. Logins and page views flatter retention, so suggest a list of meaningful events, for example `--active-events ran_query,created_report`. The cohort is still the first period with any event.
- 19## Steps
- 211. Check the date range. You need at least 4 complete periods; 12 is better.
- 222. Run:
- 24 ```bash
- 25 node scripts/cohorts.mjs data/events.csv --period month --entity user --active-events ran_query,created_report --out out/retention
- 26 ```
- 28 Other options: `--periods 12` (how many cohorts and columns), `--as-of 2026-10-31`, and `--include-current` to show the partial current period (off by default, since it always looks like a drop).
- 293. Read `out/retention.md` and report:
- 30 - Period 1 retention on average (M1 or W1) and the trend across recent cohorts.
- 31 - Where the curve flattens, if it does. A curve that flattens is the sign of product-market fit for that segment; one that keeps sliding is not.
- 32 - Best and worst cohorts, and a question about what was different then (launch, pricing change, a big customer onboarding, a holiday).
- 334. If the user wants a chart, `out/retention.csv` drops straight into a spreadsheet heatmap, or run `saas-usage-dashboard` for the weekly heatmap in HTML.
- 345. Offer a split: rerun on a filtered file (for example one plan or one acquisition channel) saved as `data/events-<segment>.csv`, and compare M1 and M3 side by side.
- 36## Reading the numbers
- 38- Cohorts under 10 entities are noisy. Say so instead of drawing conclusions from them.
- 39- Users can come back after a gap, so a later period can be higher than an earlier one. That is real, not a bug.
- 40- Retention by events is usage retention, not revenue retention. For revenue, use `arr-waterfall` from the Ledgerly account.
- 42## Output template
- 44```markdown
- 45**Monthly user retention (active = ran_query or created_report)**
- 46M1 58% on average, M3 45%, still sliding about 5 points a month after M3.
- 47Best recent cohort: 2026-06 (78% M1). Worst: 2025-11 (27% M1). What changed in June?
- 48| Cohort | Size | M0 | M1 | M2 | M3 | ...
- 49```
- 51## Guardrails
- 53- Never fill blank cells with zeros or estimates. Blank means "not observable yet".
- 54- Exclude internal and test users before running; ask how to recognize them (email domain, a test account ID).
- 55- Do not paste user IDs into chat.