Final phase of #399 — flips the user-visible behaviour the prior two
PRs only set up. Stacks on #400 (Phase 1 plumbing) + #410 (Phase 2
handler migration).

What changes

app_lifespan no longer eagerly calls ensure_initialized and no
longer constructs the FileWatcher / ConsolidationScheduler /
PolicyScheduler / HealthWatchdog itself. Component construction
and the background-loop start move into
AppContext.ensure_initialized, which now also owns their lifetime
— ctx.close() stops them in reverse-allocation order before tearing
the components down.

Concretely:

• Lifespan (≈40 lines smaller): load env → set up logging → build
  optional WebhookManager → allocate AppContext → yield. None of
  these touch ~/.memtomem/. On shutdown: webhook.close() first
  (drops outstanding network state — same rationale as server lifespan: resource leak if watcher/scheduler/policy_scheduler/watchdog startup raises before yield (#400 follow-up) #404), then
  ctx.close().
• AppContext.ensure_initialized: keeps the _init_lock /
  cached-Components / failure-rollback semantics from Phase 1, and
  additionally allocates the watcher + (optional) schedulers + (optional)
  watchdog. Same degraded-mode gate as before — embedding_broken set
  → watcher constructed but start() skipped, schedulers/watchdog not
  even built, so MCP server should degrade gracefully on embedding mismatch instead of fail-fast crash #349 recovery via mem_embedding_reset is unchanged.
• AppContext.close: stops watchdog → policy → consolidation →
  watcher → components, each through a new _stop_quietly helper that
  logs+continues on Exception and re-raises CancelledError
  (preserves PR server lifespan: resource leak if watcher/scheduler/policy_scheduler/watchdog startup raises before yield (#400 follow-up) #404 / fix(server): tear down startup resources on lifespan failure (closes #404) #406 invariants).
• Removed: _teardown_startup_resources (its order/idempotency
  invariants now live on AppContext.close) and set_health_watchdog
  (lifespan no longer hands a watchdog to ctx — ctx builds it).

User-facing behaviour change

rm -rf ~/.memtomem
claude mcp add memtomem -s user -- uvx --from memtomem memtomem-server
claude mcp list                # before #399: ~/.memtomem/memtomem.db appears
                               # after #399 phase 3: directory stays absent

The DB is created on the first tool call (mem_search, mem_add,
mem_status, …) instead of on the MCP handshake.

Accepted regressions (please call out in changelog)

1. MCP server should degrade gracefully on embedding mismatch instead of fail-fast crash #349 startup-warning visibility moves to first tool call. The
   "Embedding dimension mismatch detected at startup — entering degraded mode" warning previously fired on memtomem-server
   stderr at boot. With lazy init it fires when
   ensure_initialized runs, i.e. on the first tool call. Recovery
   tools (mem_embedding_reset, mem_status, mem_stats,
   mem_list, mem_read) stay callable; the user just learns about
   the mismatch from the first response rather than the boot stderr.
2. Background scheduler-on-idle removed. Previously, an idle
   server (editor opened in evening, no tool calls until morning)
   still ran consolidation / policy / health-watchdog every interval.
   With lazy init those start on the first tool call. An MCP client
   that connects but never calls a tool will not see any scheduler
   ticks — consistent with "no DB to maintain" but worth flagging for
   anyone whose maintenance schedule assumed background-without-tool-calls.

Both are documented in the issue's open-questions section as accepted
trade-offs.

Acceptance

Mapped from #399's acceptance checklist:

• handshake-only lifespan leaves the DB absent
  (test_handshake_only_leaves_db_absent)
• first ensure_initialized creates the DB
  (test_first_ensure_initialized_creates_db)
• concurrent first-callers share a single
  create_components invocation
  (test_concurrent_first_calls_invoke_create_components_once +
  pre-existing test_ensure_initialized_concurrent_calls_invoke_factory_once)
• watcher/scheduler/watchdog skipped in degraded mode
  (test_ensure_initialized_skips_watcher_in_degraded_mode —
  same gate as the pre-Phase-3 code, just relocated)
• ctx.close() stops everything
  ensure_initialized started
  (test_close_stops_started_watcher +
  test_lifespan_closes_webhook_before_ctx)
• watcher-start failure rolls back components
  (test_ensure_initialized_rolls_back_components_when_watcher_start_fails)
• Background .server.pid + ~/.memtomem/ mkdir at module
  import is still eager — out of scope for this PR (open
  question 1 in Lazy DB init: defer ~/.memtomem/memtomem.db creation until first tool call #399, ties into mm uninstall liveness check only sees MCP server pid — silently ignores mm web and other DB writers #384/memtomem-server leaves stale .server.pid on exit — risks mm uninstall liveness false-positive via PID recycling #387 $XDG_RUNTIME_DIR
  relocation)

Smoke test

$ HOME=/tmp/mm-phase3-smoke MEMTOMEM_INDEXING__MEMORY_DIRS='[]' \
  MEMTOMEM_EMBEDDING__PROVIDER=none uv run python -c "..."
Pre-lifespan: db exists=False
In lifespan (no tool call): db exists=False components=None
-- now calling ensure_initialized --
After ensure_initialized: db exists=True components is not None=True
Post-lifespan: db exists=True

Test plan

• uv run ruff check packages/memtomem/src && uv run ruff format --check packages/memtomem/src — clean
• uv run mypy packages/memtomem/src/memtomem/server/{context,lifespan}.py — clean (advisory)
• uv run pytest -m "not ollama" — 2177 passed, 46 deselected
• Manual claude mcp add + claude mcp list against built
  branch in fresh ~/.memtomem (reviewer: please confirm DB
  stays absent on your machine too)

🤖 Generated with Claude Code