feat: CLI analytics via Umami event collector

[bm-clawd]

What

Lightweight, non-blocking analytics for the CLI-to-cloud conversion funnel. Tracks promo impressions, opt-outs, and cloud login attempts/successes via Umami's event collector API.

Events Tracked

Event	When
cli-promo-shown	Promo panel displayed (first run or version bump)
cli-promo-opted-out	User ran bm cloud promo --off
cli-cloud-login-started	User initiated bm cloud login
cli-cloud-login-success	Login + subscription verified
cli-cloud-login-sub-required	Login hit subscription paywall

Also

• Learn-more URL now includes UTM tags (utm_source=bm-cli&utm_medium=promo&utm_campaign=cloud-upsell) for web attribution in Umami

Design

• Zero new dependencies — stdlib only (urllib.request + threading)
• Fire-and-forget — daemon thread, 3s timeout, silent on any failure
• Respects opt-out — honors BASIC_MEMORY_NO_PROMOS env var
• No-op by default — requires BASIC_MEMORY_UMAMI_HOST and BASIC_MEMORY_UMAMI_SITE_ID env vars to activate. Existing installs see zero change.
• No PII — only event name, BM version, and trigger type

Umami Setup Instructions

After merging, you need to configure Umami to receive these events:

1. Get your Umami website ID

• Log in to your Umami dashboard
• Go to Settings → Websites
• Click the website for basicmemory.com
• Copy the Website ID (UUID format)

2. Set environment variables

Wherever the bm CLI runs (or in your deployment/build config):

export BASIC_MEMORY_UMAMI_HOST="https://your-umami-instance.com"
export BASIC_MEMORY_UMAMI_SITE_ID="your-website-uuid-here"

For testing locally: set these in your shell before running bm status etc.

For production/distribution: these would go in the release build config or be baked into a future config file. Users without these vars set get zero analytics (the module is a complete no-op).

3. Create custom events dashboard in Umami

• Go to your website dashboard → Events tab
• After the first events flow in, you'll see them listed automatically
• Set up Goals for the conversion funnel:
  • Goal 1: Event cli-promo-shown (top of funnel)
  • Goal 2: Event cli-cloud-login-started (intent)
  • Goal 3: Event cli-cloud-login-success (conversion)
• Set up a Funnel insight:
  • Step 1: Event cli-promo-shown
  • Step 2: Event cli-cloud-login-started
  • Step 3: Event cli-cloud-login-success

4. UTM attribution

The learn-more URL now points to:

https://basicmemory.com?utm_source=bm-cli&utm_medium=promo&utm_campaign=cloud-upsell

Check Insights → UTM in Umami to see CLI-sourced web traffic.

5. Verify it works

export BASIC_MEMORY_UMAMI_HOST="https://your-umami-instance.com"
export BASIC_MEMORY_UMAMI_SITE_ID="your-website-uuid"

# This should trigger a promo-shown event (if promo conditions are met)
bm status

# Check your Umami dashboard → Events tab within a few seconds

Tests

32 tests pass including new analytics tests covering:

• Disabled/unconfigured no-op behavior
• Correct URL and payload construction
• Silent failure on network errors
• Event name constants validation

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e7c6d31b29

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Honor CLI promo opt-out before sending analytics

track() only checks _analytics_disabled() (the BASIC_MEMORY_NO_PROMOS env var), so it ignores the persisted opt-out set by bm cloud promo --off (cloud_promo_opt_out in core_commands.promo). In that state, later commands (for example bm cloud login) still emit analytics events, which contradicts the module’s stated “same opt-out mechanisms as promo messaging” behavior and leaks telemetry after an explicit opt-out. Add a config-based opt-out check (or reuse promo gating logic) before dispatching events.

Useful? React with 👍 / 👎.