[BUG] Fatal crash on startup when python.org Python 3.12 is present alongside Homebrew on macOS

[egoes]

Bug Description

When macOS has python.org Python 3.12 installed alongside Homebrew, uvx picks it up instead of downloading its own CPython. python.org's Python is compiled without enable_load_extension, which causes basic-memory's semantic search initialization to crash fatally before the MCP handshake completes. Claude Desktop never connects.

The server does recover gracefully if given enough time (falling back to keyword search on second startup), but Claude Desktop's connection window is too short — it sees the initial crash and gives up permanently until restarted.

The same configuration works correctly on a machine where python.org Python was never installed, where uvx downloads its own CPython instead.

This issue was diagnosed with the assistance of Claude (Anthropic).

---

Steps To Reproduce

1. Have macOS with python.org Python 3.12 installed at /Library/Frameworks/Python.framework/Versions/3.12/
2. Install Homebrew and basic-memory: brew tap basicmachines-co/basic-memory && brew install basic-memory
3. Configure Claude Desktop with the official documented config:

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": ["basic-memory", "mcp"]
    }
  }
}

4. Launch Claude Desktop
5. See MCP connection error: Server transport closed unexpectedly

---

Expected Behavior

Basic-memory MCP server starts and connects to Claude Desktop. If enable_load_extension is unavailable, the server should fall back to keyword search and remain running — which it already does on second startup, just too late for Claude Desktop's connection window.

---

Actual Behavior

Server crashes during initialization with:

AttributeError: 'sqlite3.Connection' object has no attribute 'enable_load_extension'

Full traceback points to:

basic_memory/repository/sqlite_search_repository.py:370
await driver_connection.enable_load_extension(True)

Claude Desktop logs:

Server transport closed unexpectedly, this is likely due to the process exiting early.
Server disconnected.

The pyvenv.cfg of the uvx-built environment confirms the wrong Python was used:

home = /Library/Frameworks/Python.framework/Versions/3.12/bin
implementation = CPython
version_info = 3.12.0

On a working machine (no python.org Python installed), uvx correctly uses its own downloaded CPython:

home = /Users/en/.local/share/uv/python/cpython-3.12.9-macos-aarch64-none/bin

---

Environment

• OS: macOS 26.4 / 25E246 (Apple Silicon, aarch64)
• python.org Python version: 3.12.0 (installed at /Library/Frameworks/Python.framework/)
• Basic Memory version: 0.20.3
• Installation method: Homebrew + uvx (official documented method)
• Claude Desktop version: 1.2.234 (2d1855) 2026-04-01T07:58:22.000Z

---

Additional Context

Workaround: Explicitly setting PATH in the Claude Desktop MCP config forces uvx to find Homebrew Python first:

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": ["basic-memory", "mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Why not uninstall python.org Python: The python.org Python installation had legitimate packages (Flask, gunicorn, mistralai, etc.) so removing it would break other things.

Note: Claude Desktop launches GUI apps with a minimal PATH that doesn't include /opt/homebrew/bin, so shell-level PATH fixes (.zshrc, .zprofile) do not propagate to Claude Desktop or uvx.

---

Possible Solution

Two options, either or both:

1. Make semantic search initialization non-fatal at startup. The server already recovers gracefully on second startup (logs show it falls back to keyword search with Semantic embeddings missing — backfill will run in background). Making this happen on first startup — before the MCP handshake — would prevent the crash entirely.

2. Document the python.org Python conflict. Add a note to the troubleshooting guide that if enable_load_extension errors appear, the likely cause is python.org Python being present on the system, and that the fix is adding an explicit PATH to the Claude Desktop MCP config.

[phernandez]

Thanks @egoes for the detailed description. We'll take a look

[egoes]

This bug is probably not affecting many, but after over two hours today trying to figure out why the MCP wasn’t loading in Claude Desktop, I thought I would share my findings.

As a side note, this happened on a Mac that I didn’t use for two months since end of January (I was away). Basic Memory was running fine back then. Therefore, maybe a regression was introduced in an update somewhere. I don’t know.