Add anonymous usage telemetry (Homebrew-style opt-out)

[phernandez]

Summary

Add anonymous usage telemetry to Basic Memory using OpenPanel. Following the Homebrew analytics model: on by default with easy opt-out.

Motivation

We want to understand:

• What versions are in use
• What features are being used (MCP tools, CLI commands)
• What errors users encounter
• OS/Python version distribution

PyPI stats are unreliable, and we have no visibility into actual usage patterns.

Design Decisions

Decision	Choice	Rationale
Backend	OpenPanel Cloud	Open source, privacy-first, Python SDK, $20/mo for 5K-100K events
Default	ON (opt-out)	Homebrew model - get meaningful data, easy to disable
Identification	Random UUID	Stored locally at ~/.basic-memory/.install_id, user can delete
First run	One-time notice	Not a prompt - just inform, then never show again

What We'll Track

Events

Event	Properties	Purpose
app_started	mode: "cli" | "mcp"	Active usage
mcp_tool_called	tool: str	Feature popularity
cli_command	command: str	CLI usage patterns
sync_completed	entity_count, duration_ms	Performance baseline
error	type, message (sanitized)	Bug prioritization
import_completed	source: str	Import feature usage

Global Properties (every event)

• app_version
• python_version
• os (darwin/linux/windows)
• arch (arm64/x86_64)
• install_id (random UUID)

What We NEVER Collect

• Note content
• File names or paths
• Personal information
• IP addresses (OpenPanel doesn't store these)

User Experience

First Run Notice (shown once)

Basic Memory collects anonymous usage statistics to help improve the software.
This includes: version, OS, feature usage, and errors. No personal data or note content.
To opt out: bm telemetry disable
Details: https://memory.basicmachines.co/telemetry

CLI Commands

bm telemetry disable  # opt out
bm telemetry enable   # opt back in  
bm telemetry status   # show current state + what's collected

Environment Variable

export BASIC_MEMORY_TELEMETRY_ENABLED=false  # disable via env

Implementation

Files to Create

File	Description
src/basic_memory/telemetry.py	Core telemetry module (client, track function, notice)
src/basic_memory/cli/commands/telemetry.py	CLI commands (enable/disable/status)
tests/test_telemetry.py	Unit tests

Files to Modify

File	Changes
pyproject.toml	Add openpanel dependency
src/basic_memory/config.py	Add telemetry_enabled (default True), telemetry_notice_shown fields
src/basic_memory/cli/commands/__init__.py	Register telemetry module
src/basic_memory/cli/main.py	Import telemetry commands
src/basic_memory/mcp/server.py	Add startup tracking + show notice
src/basic_memory/cli/app.py	Add startup tracking + show notice
MCP tool files	Add track() calls
CLI command files	Add track() calls

Core Module (telemetry.py)

"""Anonymous telemetry for Basic Memory (Homebrew-style opt-out)."""

import platform
import uuid
from pathlib import Path

from openpanel import OpenPanel

from basic_memory import __version__
from basic_memory.config import ConfigManager

_client: OpenPanel | None = None

def get_install_id() -> str:
    """Get or create anonymous installation ID."""
    id_file = Path.home() / ".basic-memory" / ".install_id"
    if id_file.exists():
        return id_file.read_text().strip()
    install_id = str(uuid.uuid4())
    id_file.parent.mkdir(parents=True, exist_ok=True)
    id_file.write_text(install_id)
    return install_id

def track(event: str, properties: dict | None = None) -> None:
    """Track an event. Fire-and-forget, never raises."""
    try:
        get_client().track(event, properties or {})
    except Exception:
        pass  # Telemetry must never break the app

Documentation

Create a page at https://memory.basicmachines.co/telemetry documenting:

• Exactly what we collect
• What we never collect
• How to disable
• How to delete your data (delete ~/.basic-memory/.install_id)

Testing Strategy

1. Unit tests for telemetry module (mock OpenPanel client)
2. Verify opt-out disables tracking
3. Verify notice only shows once
4. Test env var override works
5. Integration test for CLI commands

References

• OpenPanel Python SDK
• Homebrew Analytics
• Original discussion in Claude conversation

[claude]

Claude finished @phernandez's task in 4m 43s —— View job • claude/issue-477-20251225-0250

---

Implementing Issue #477: Add Anonymous Usage Telemetry ✅

Issue Classification

• Type: Feature request / Enhancement
• Components: CLI, MCP, Configuration
• Complexity: Medium (multiple file changes, new module, testing required)
• Priority: Medium (quality-of-life improvement for product analytics)

Implementation Tasks

• Analyze issue and classify
• Update pyproject.toml with openpanel dependency
• Update src/basic_memory/config.py for telemetry settings
• Create src/basic_memory/telemetry.py core module
• Create src/basic_memory/cli/commands/telemetry.py CLI commands
• Register telemetry commands in CLI
• Add telemetry to MCP server startup
• Add telemetry to CLI app startup
• Create comprehensive unit tests
• Commit and push changes
• Provide PR creation link

Implementation Summary

I've successfully implemented anonymous usage telemetry for Basic Memory following the Homebrew analytics model as specified in the issue.

Core Features Implemented:

• ✅ Anonymous telemetry system with Homebrew-style opt-out (on by default)
• ✅ Random UUID installation ID stored at ~/.basic-memory/.install_id
• ✅ Telemetry notice shown once on first run
• ✅ Environment variable override: BASIC_MEMORY_TELEMETRY_ENABLED
• ✅ Fire-and-forget tracking (telemetry errors never break the app)
• ✅ Global properties sent with every event (version, OS, architecture, install_id)

CLI Commands:

• bm telemetry enable - Enable telemetry
• bm telemetry disable - Disable telemetry
• bm telemetry status - Show current status and what's collected

Integration Points:

• CLI app startup tracking with command name
• MCP server startup tracking
• Configurable via config file (telemetry_enabled) and environment variable

Testing:

• Comprehensive unit tests covering all telemetry functions (15 test cases)
• Tests for config integration, environment variables, and error handling
• Tests for first-run notice behavior
• Tests for exception handling (telemetry never breaks the app)

Files Changed:

• pyproject.toml: Added openpanel dependency
• src/basic_memory/config.py: Added telemetry configuration fields
• src/basic_memory/telemetry.py: Core telemetry module (170 lines)
• src/basic_memory/cli/commands/telemetry.py: CLI commands (105 lines)
• src/basic_memory/cli/app.py: Added CLI startup tracking
• src/basic_memory/mcp/server.py: Added MCP startup tracking
• tests/test_telemetry.py: Comprehensive unit tests (365 lines)

Next Steps

Remaining Tasks (can be done in follow-up PRs):

1. Add tracking calls to individual MCP tools (e.g., track("mcp_tool_called", {"tool": "write_note"}))
2. Add tracking calls to CLI commands (e.g., track("cli_command", {"command": "import"}))
3. Add error tracking with sanitized error messages
4. Add performance tracking for sync operations
5. Configure OpenPanel credentials via environment variables in production
6. Create documentation page at https://memory.basicmachines.co/telemetry

Testing Note:
The implementation includes comprehensive unit tests. Full integration testing will require:

• Installing openpanel package: pip install openpanel>=1.0.0
• Running the test suite with appropriate permissions
• Testing with actual OpenPanel credentials in a development environment

Create PR

---

| Branch: claude/issue-477-20251225-0250