Retention cohorts

Retention cohorts

The 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.

Inputs

An events CSV in data/ with timestamp, account_id, user_id, event (the same file the saas-usage-dashboard kit uses). Decide with the user:

1. Period: month for B2B tools used a few times a month; week for products used weekly or more. Default month.
2. 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.
3. 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.

Steps

1. Check the date range. You need at least 4 complete periods; 12 is better.

2. Run:

   node scripts/cohorts.mjs data/events.csv --period month --entity user --active-events ran_query,created_report --out out/retention

   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).

3. Read out/retention.md and report:

   • Period 1 retention on average (M1 or W1) and the trend across recent cohorts.
   • 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.
   • Best and worst cohorts, and a question about what was different then (launch, pricing change, a big customer onboarding, a holiday).
4. 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.
5. 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.

Reading the numbers

• Cohorts under 10 entities are noisy. Say so instead of drawing conclusions from them.
• Users can come back after a gap, so a later period can be higher than an earlier one. That is real, not a bug.
• Retention by events is usage retention, not revenue retention. For revenue, use arr-waterfall from the Ledgerly account.

Output template

**Monthly user retention (active = ran_query or created_report)**
M1 58% on average, M3 45%, still sliding about 5 points a month after M3.
Best recent cohort: 2026-06 (78% M1). Worst: 2025-11 (27% M1). What changed in June?
| Cohort | Size | M0 | M1 | M2 | M3 | ...

Guardrails

• Never fill blank cells with zeros or estimates. Blank means "not observable yet".
• Exclude internal and test users before running; ask how to recognize them (email domain, a test account ID).
• Do not paste user IDs into chat.

Retention cohorts

Builds the retention triangle from a product events export: weekly or monthly cohorts, by user or by account, with a size-weighted average curve and a note on where it flattens. Partial periods stay blank instead of showing up as fake drops.

Who it is for: product managers, founders, and growth folks who need to answer "is retention getting better?" for a product review or board deck.

Example

Input: examples/events.csv (about 1,250 events from about 130 users over 12 months).

Output (out/retention.md):

Average curve: M1 58%, M2 48%, M3 45%, M4 40%.
Best M1: 2026-06 (78%). Worst M1: 2025-11 (27%).

Plus out/retention.csv for a spreadsheet heatmap and out/retention.json.

What it can access

• Runs node scripts/cohorts.mjs (Node built-ins only).
• Reads data/. Writes out/retention*.
• No network.

Setup

None. Export events (timestamp, account_id, user_id, event) to data/events.csv and ask Claude for retention cohorts.