Summary

bm mcp spends most of its startup time importing the local FastAPI app and every v2 router, even when the server will never serve the local API (for example, when BASIC_MEMORY_FORCE_CLOUD=true routes every tool call to cloud). When several MCP clients start servers at the same moment, those CPU-bound imports compete for cores, and startup can exceed the client's MCP connect timeout. Claude Code's default is about 30 s, and when it is exceeded the client reports MCP servers failed to connect: basic-memory.

Root cause

src/basic_memory/api/__init__.py imports the app eagerly:

from .app import app

So the import chain at MCP startup is:

basic_memory.mcp.tools
  -> mcp.tools.basic_memory_diagnostics   (from basic_memory.mcp.server import mcp)
    -> basic_memory.mcp.server            (from basic_memory.api.container import ApiContainer, installed_container)
      -> basic_memory.api                 (package __init__: from .app import app)
        -> basic_memory.api.app
          -> basic_memory.api.v2.routers  (knowledge_router, prompt_router -> template_loader -> pybars/pymeta grammar, ...)

api/container.py itself is cheap (about 1.6 ms of its own). The cost comes entirely from the package __init__ pulling in .app.

Measurements

Upstream main @ 872f574 (Apple M5 Pro, Python from uv sync, mcp 2.0.0, fastmcp 4.0.3), python -X importtime -c "import basic_memory.cli.main, basic_memory.mcp.tools, basic_memory.mcp.prompts, basic_memory.mcp.resources":

import time:       161 |    1061892 | basic_memory.mcp.tools
import time:       908 |    1016645 |     basic_memory.mcp.server
import time:         8 |     672159 |       basic_memory.api.container
import time:       254 |     672098 |           basic_memory.api.app
import time:       229 |     631944 |                 basic_memory.api.v2.routers
import time:    181183 |     181272 |                   basic_memory.api.v2.routers.knowledge_router
import time:     12357 |     188264 |                   basic_memory.api.v2.routers.prompt_router
import time:     61091 |     174139 |                         pybars._compiler
import time:    112563 |     113004 |                           pymeta.grammar

About 0.67 s of the 1.06 s for basic_memory.mcp.tools is basic_memory.api.app, roughly 63%. A warm import of the full set took 1.7 s, and a cold one 5.5 s.

On a slower machine (Apple M1, 4 performance + 4 efficiency cores; a 0.22.x checkout with the same chain), I timed bm mcp --project main with BASIC_MEMORY_FORCE_CLOUD=true and BASIC_MEMORY_EXPLICIT_ROUTING=true, from spawn to the initialize / tools/list response, with N servers started at once:

• About 10 s of the 11 s solo start comes before the first log line (MCP server constrained to project). That time is imports. /usr/bin/time showed it as CPU (user about 10 s), not I/O. api.app and its routers account for about 4.9 s.
• DB init, project reconciliation and the watcher take 0.3–1.4 s at every N. Setting BASIC_MEMORY_INDEX_CHANGES=false did not change the N = 5 result (19.8 / 20.2 s), so SQLite and watcher contention are not the cause.
• In real bursts, where the MCP client itself is also starting, 3 concurrent sessions took about 35 s and missed a 30 s connect timeout. Raising the client timeout to 90 s works around it.

Proposed fix

1. Make basic_memory/api/__init__.py stop importing .app eagerly. Use a lazy __getattr__, or have callers import basic_memory.api.app directly, so that basic_memory.api.container no longer pulls in FastAPI and the routers.
2. Check that the MCP startup path (mcp.server and its lifespan) only imports the API app when the local API is actually needed.
3. Add a startup-time regression check, for example asserting that basic_memory.api.app is not in sys.modules after import basic_memory.mcp.tools, or a -X importtime budget.

Related

• Slow startup time #740: slow CLI startup, an eager import graph. The last comment called for a dedicated lazy-import refactor with startup benchmarks. This issue is the MCP-server slice of that.
• CLI eagerly imports embedding stack (onnxruntime/fastembed) for filter-only search-notes → slow SessionStart brief #886: an eager embedding-stack import in the CLI, an earlier fix of the same kind.
• Copilot stdio interoperability: delayed modern discovery causes legacy initialize rejection (-32022) #1713: a client gives up during delayed MCP startup. Faster readiness would also make that window smaller.