memind/docs/local-analytics.md

Local Memind + Umami analytics

The integration is local-only by default. Memind proxies /analytics/* to the local Umami service at http://127.0.0.1:3100; it does not contact 103/105.

1. Start /Users/john/Project/memind-analytics and verify:

   curl --fail http://127.0.0.1:3100/api/heartbeat
   

2. Create two Umami Websites: one for generated pages and one for the Memind product shell. Keeping them separate prevents chat, MindSpace, and feedback navigation from inflating generated-page views. Do not create a Website per page or per user.

3. Put the Website ID and a local-only identity secret in Memind's .env:

   MEMIND_ANALYTICS_ENABLED=true
   MEMIND_ANALYTICS_URL=http://127.0.0.1:3100
   MEMIND_ANALYTICS_WEBSITE_ID=<website-id>
   MEMIND_ANALYTICS_ID_SECRET=<random-local-secret>
   MEMIND_ANALYTICS_IDENTITY_MODE=raw
   MEMIND_ANALYTICS_DOMAINS=127.0.0.1,localhost
   MEMIND_PRODUCT_ANALYTICS_ENABLED=true
   MEMIND_PRODUCT_ANALYTICS_WEBSITE_ID=<product-website-id>
   

4. Restart the local Memind server. Full generated HTML pages will receive a same-origin /analytics/script.js tracker. The tracker identifies the visitor with the stable Memind user ID when IDENTITY_MODE=raw before sending a standard Umami page view, so Users and Pageviews are populated. The Identify properties include username, plan, channel, identity mode and current public page URL. Generated-page events also retain page_id and the precise generated_at timestamp. Omit the identity-mode setting outside an explicitly approved first-party environment to keep the pseudonymous default.

5. The product shell loads its tracker from the same-origin /analytics/script.js endpoint. It records one standard page view per SPA route transition, product_click for links/buttons, and 10/30-second route engagement events. Query strings are restricted to a small allowlist and click labels never copy arbitrary chat or generated-page text. Authenticated product events use the same configured identity as generated pages, while remaining in the separate product Website.

The integration is fail-open: missing configuration, disabled analytics, or a down Umami service leaves page generation and page delivery unchanged. User facing analytics must be queried through a future Memind API that filters by the authenticated owner; do not expose the Umami dashboard directly to users.