feat: add anonymous usage telemetry (Homebrew-style opt-out) (#478)

Signed-off-by: phernandez <[email protected]>
Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: phernandez

README.md

@@ -466,6 +466,39 @@ tail -f ~/.basic-memory/basic-memory.log
 BASIC_MEMORY_CLOUD_MODE=true uvicorn basic_memory.api.app:app
 ```
 
+## Telemetry
+
+Basic Memory collects anonymous usage statistics to help improve the software. This follows the [Homebrew model](https://docs.brew.sh/Analytics) - telemetry is on by default with easy opt-out.
+
+**What we collect:**
+- App version, Python version, OS, architecture
+- Feature usage (which MCP tools and CLI commands are used)
+- Error types (sanitized - no file paths or personal data)
+
+**What we NEVER collect:**
+- Note content, file names, or paths
+- Personal information
+- IP addresses
+
+**Opting out:**
+```bash
+# Disable telemetry
+basic-memory telemetry disable
+
+# Check status
+basic-memory telemetry status
+
+# Re-enable
+basic-memory telemetry enable
+```
+
+Or set the environment variable:
+```bash
+export BASIC_MEMORY_TELEMETRY_ENABLED=false
+```
+
+For more details, see the [Telemetry documentation](https://basicmemory.com/telemetry).
+
 ## Development
 
 ### Running Tests

pyproject.toml

@@ -41,6 +41,7 @@ dependencies = [
     "mdformat>=0.7.22",
     "mdformat-gfm>=0.3.7",
     "mdformat-frontmatter>=2.0.8",
+    "openpanel>=0.0.1",  # Anonymous usage telemetry (Homebrew-style opt-out)
 ]
 
 

src/basic_memory/cli/app.py

@@ -15,6 +15,7 @@
 import typer  # noqa: E402
 
 from basic_memory.config import ConfigManager, init_cli_logging  # noqa: E402
+from basic_memory.telemetry import show_notice_if_needed, track_app_started  # noqa: E402
 
 
 def version_callback(value: bool) -> None:
@@ -46,6 +47,13 @@ def app_callback(
     # Initialize logging for CLI (file only, no stdout)
     init_cli_logging()
 
+    # Show telemetry notice and track CLI startup
+    # Skip for 'mcp' command - it handles its own telemetry in lifespan
+    # Skip for 'telemetry' command - avoid issues when user is managing telemetry
+    if ctx.invoked_subcommand not in {"mcp", "telemetry"}:
+        show_notice_if_needed()
+        track_app_started("cli")
+
     # Run initialization for commands that don't use the API
     # Skip for 'mcp' command - it has its own lifespan that handles initialization
     # Skip for API-using commands (status, sync, etc.) - they handle initialization via deps.py

src/basic_memory/cli/commands/__init__.py

@@ -1,7 +1,7 @@
 """CLI commands for basic-memory."""
 
 from . import status, db, import_memory_json, mcp, import_claude_conversations
-from . import import_claude_projects, import_chatgpt, tool, project, format
+from . import import_claude_projects, import_chatgpt, tool, project, format, telemetry
 
 __all__ = [
     "status",
@@ -14,4 +14,5 @@
     "tool",
     "project",
     "format",
+    "telemetry",
 ]

src/basic_memory/cli/commands/telemetry.py

@@ -0,0 +1,79 @@
+"""Telemetry commands for basic-memory CLI."""
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+# Create telemetry subcommand group
+telemetry_app = typer.Typer(help="Manage anonymous telemetry settings")
+app.add_typer(telemetry_app, name="telemetry")
+
+
+@telemetry_app.command("enable")
+def enable() -> None:
+    """Enable anonymous telemetry.
+
+    Telemetry helps improve Basic Memory by collecting anonymous usage data.
+    No personal data, note content, or file paths are ever collected.
+    """
+    config_manager = ConfigManager()
+    config = config_manager.config
+    config.telemetry_enabled = True
+    config_manager.save_config(config)
+    console.print("[green]Telemetry enabled[/green]")
+    console.print("[dim]Thank you for helping improve Basic Memory![/dim]")
+
+
+@telemetry_app.command("disable")
+def disable() -> None:
+    """Disable anonymous telemetry.
+
+    You can re-enable telemetry anytime with: bm telemetry enable
+    """
+    config_manager = ConfigManager()
+    config = config_manager.config
+    config.telemetry_enabled = False
+    config_manager.save_config(config)
+    console.print("[yellow]Telemetry disabled[/yellow]")
+
+
+@telemetry_app.command("status")
+def status() -> None:
+    """Show current telemetry status and what's collected."""
+    from basic_memory.telemetry import get_install_id, TELEMETRY_DOCS_URL
+
+    config = ConfigManager().config
+
+    status_text = "[green]enabled[/green]" if config.telemetry_enabled else "[yellow]disabled[/yellow]"
+
+    console.print(f"\nTelemetry: {status_text}")
+    console.print(f"Install ID: [dim]{get_install_id()}[/dim]")
+    console.print()
+
+    what_we_collect = """
+[bold]What we collect:[/bold]
+  - App version, Python version, OS, architecture
+  - Feature usage (which MCP tools and CLI commands)
+  - Sync statistics (entity count, duration)
+  - Error types (sanitized, no file paths)
+
+[bold]What we NEVER collect:[/bold]
+  - Note content, file names, or paths
+  - Personal information
+  - IP addresses
+"""
+
+    console.print(
+        Panel(
+            what_we_collect.strip(),
+            title="Telemetry Details",
+            border_style="blue",
+            expand=False,
+        )
+    )
+    console.print(f"[dim]Details: {TELEMETRY_DOCS_URL}[/dim]")

src/basic_memory/cli/main.py

@@ -13,6 +13,7 @@
     mcp,
     project,
     status,
+    telemetry,
     tool,
 )
 

src/basic_memory/config.py

@@ -221,6 +221,17 @@ class BasicMemoryConfig(BaseSettings):
         description="Cloud project sync configuration mapping project names to their local paths and sync state",
     )
 
+    # Telemetry configuration (Homebrew-style opt-out)
+    telemetry_enabled: bool = Field(
+        default=True,
+        description="Send anonymous usage statistics to help improve Basic Memory. Disable with: bm telemetry disable",
+    )
+
+    telemetry_notice_shown: bool = Field(
+        default=False,
+        description="Whether the one-time telemetry notice has been shown to the user",
+    )
+
     @property
     def cloud_mode_enabled(self) -> bool:
         """Check if cloud mode is enabled.

src/basic_memory/mcp/server.py

@@ -12,6 +12,7 @@
 from basic_memory import db
 from basic_memory.config import ConfigManager
 from basic_memory.services.initialization import initialize_app, initialize_file_sync
+from basic_memory.telemetry import show_notice_if_needed, track_app_started
 
 
 @asynccontextmanager
@@ -20,12 +21,17 @@ async def lifespan(app: FastMCP):
 
     Handles:
     - Database initialization and migrations
+    - Telemetry notice and tracking
     - File sync in background (if enabled and not in cloud mode)
     - Proper cleanup on shutdown
     """
     app_config = ConfigManager().config
     logger.info("Starting Basic Memory MCP server")
 
+    # Show telemetry notice (first run only) and track startup
+    show_notice_if_needed()
+    track_app_started("mcp")
+
     # Track if we created the engine (vs test fixtures providing it)
     # This prevents disposing an engine provided by test fixtures when
     # multiple Client connections are made in the same test

src/basic_memory/mcp/tools/build_context.py

@@ -9,6 +9,7 @@
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
+from basic_memory.telemetry import track_mcp_tool
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import (
     GraphContext,
@@ -87,6 +88,7 @@ async def build_context(
     Raises:
         ToolError: If project doesn't exist or depth parameter is invalid
     """
+    track_mcp_tool("build_context")
     logger.info(f"Building context from {url} in project {project}")
 
     # Convert string depth to integer if needed

src/basic_memory/mcp/tools/canvas.py

@@ -13,6 +13,7 @@
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put, call_post, resolve_entity_id
+from basic_memory.telemetry import track_mcp_tool
 
 
 @mcp.tool(
@@ -94,6 +95,7 @@ async def canvas(
     Raises:
         ToolError: If project doesn't exist or folder path is invalid
     """
+    track_mcp_tool("canvas")
     async with get_client() as client:
         active_project = await get_active_project(client, project, context)