fix(core): reuse a single embedding provider per process

Defensive hardening for a reported 25+ GB memory leak in long-running
'basic-memory mcp' servers (Refs #872). onnxruntime's CPU memory arena
never returns memory to the OS, so any duplicate FastEmbed/ONNX model
load leaks tens of GB.

Three independent fixes, each shippable on its own:

1. Inject one cached provider into every search repository. The
   create_search_repository factory now resolves a single provider via
   create_embedding_provider() and passes it into the SQLite/Postgres
   repos (the embedding_provider param already existed but no caller used
   it). This covers the per-request, per-sync, and watcher paths, which
   all route through the factory. Behavior is unchanged when semantic
   search is disabled.

2. Make the provider cache key stable. The key previously included
   CPU-count-derived thread/parallel knobs, which can drift between calls
   in a container/cgroup and silently mint a fresh key -> a fresh model
   load. The key now contains only model-identity fields; thread/parallel
   knobs are still applied to the provider, just not part of the key.

3. Disable onnxruntime's CPU memory arena. FastEmbed 0.8.0 exposes
   enable_cpu_mem_arena via TextEmbedding session-option kwargs, so the
   FastEmbed provider now passes enable_cpu_mem_arena=False to let any
   transient extra load return memory to the OS.

Also logs a WARNING when a second distinct provider cache key is created
in one process, so future cache bypasses are visible.

Root-cause confirmation is still pending the reporter's logs (already
requested on the issue); these changes are defensive and safe to ship
regardless.

Refs #872

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/repository/embedding_provider_factory.py

@@ -3,9 +3,19 @@
 import os
 from threading import Lock
 
+from loguru import logger
+
 from basic_memory.config import BasicMemoryConfig, default_fastembed_cache_dir
 from basic_memory.repository.embedding_provider import EmbeddingProvider
 
+# Cache key fields are limited to values that change the *identity* of the loaded
+# model (provider, model_name, dimensions, LiteLLM role/input-type/forward-dimension
+# settings, batch/request knobs that affect the LiteLLM identity, and the resolved
+# cache dir). Thread/parallel knobs are deliberately excluded — they change ONNX
+# *execution* only, not the loaded weights. Including them caused #872: in a
+# container/cgroup the CPU-derived thread count can drift between calls, producing
+# a fresh cache key and reloading the ~2.3GB model into a CPU arena that never
+# returns memory to the OS.
 type ProviderCacheKey = tuple[
     str,
     str,
@@ -16,8 +26,6 @@
     str | None,
     str | None,
     str,
-    int | None,
-    int | None,
 ]
 
 _EMBEDDING_PROVIDER_CACHE: dict[ProviderCacheKey, EmbeddingProvider] = {}
@@ -78,13 +86,16 @@ def _resolve_fastembed_runtime_knobs(
 
 
 def _provider_cache_key(app_config: BasicMemoryConfig) -> ProviderCacheKey:
-    """Build a stable cache key from provider-relevant semantic embedding config.
+    """Build a stable cache key from model-identity semantic embedding config.
 
     Uses the *resolved* cache dir — not the raw config field — so different
     FASTEMBED_CACHE_PATH values produce distinct cache keys even when the
     config field itself is unset.
+
+    Deliberately excludes the FastEmbed thread/parallel knobs: they tune ONNX
+    execution, not which model weights are loaded, and resolving them from the
+    runtime CPU budget makes the key drift between calls in a container (#872).
     """
-    resolved_threads, resolved_parallel = _resolve_fastembed_runtime_knobs(app_config)
     return (
         app_config.semantic_embedding_provider.strip().lower(),
         app_config.semantic_embedding_model,
@@ -95,8 +106,6 @@ def _provider_cache_key(app_config: BasicMemoryConfig) -> ProviderCacheKey:
         app_config.semantic_embedding_document_input_type,
         app_config.semantic_embedding_query_input_type,
         _resolve_cache_dir(app_config),
-        resolved_threads,
-        resolved_parallel,
     )
 
 
@@ -190,5 +199,19 @@ def create_embedding_provider(app_config: BasicMemoryConfig) -> EmbeddingProvide
     with _EMBEDDING_PROVIDER_CACHE_LOCK:
         if cached_provider := _EMBEDDING_PROVIDER_CACHE.get(cache_key):
             return cached_provider
+        # Trigger: a distinct cache key is being inserted while the cache already
+        # holds entries for other keys.
+        # Why: the provider is meant to be a process-wide singleton (#872). A second
+        # key means something bypassed reuse — a real config change, or a regression
+        # that reintroduces volatile fields into the key — and each new key reloads
+        # the ~2.3GB ONNX model into a CPU arena that never releases memory.
+        # Outcome: surface the bypass so future leaks are diagnosable from logs.
+        if _EMBEDDING_PROVIDER_CACHE:
+            logger.warning(
+                "Creating a second distinct embedding provider in this process; "
+                "the model will be loaded again. existing_keys={existing} new_key={new}",
+                existing=list(_EMBEDDING_PROVIDER_CACHE.keys()),
+                new=cache_key,
+            )
         _EMBEDDING_PROVIDER_CACHE[cache_key] = provider
         return provider

src/basic_memory/repository/fastembed_provider.py

@@ -73,17 +73,20 @@ def _create_model() -> "TextEmbedding":
                         "pip install -U basic-memory"
                     ) from exc
                 resolved_model_name = self._MODEL_ALIASES.get(self.model_name, self.model_name)
-                if self.cache_dir is not None and self.threads is not None:
-                    return TextEmbedding(
-                        model_name=resolved_model_name,
-                        cache_dir=self.cache_dir,
-                        threads=self.threads,
-                    )
+                # Constraint: onnxruntime's CPU memory arena grows to fit peak usage
+                # and never returns that memory to the OS. If a model is ever loaded
+                # more than once in a long-running process it leaks tens of GB (#872).
+                # FastEmbed exposes enable_cpu_mem_arena via its session-option kwargs,
+                # so we disable the arena to let any transient extra load free memory.
+                model_kwargs: dict = {
+                    "model_name": resolved_model_name,
+                    "enable_cpu_mem_arena": False,
+                }
                 if self.cache_dir is not None:
-                    return TextEmbedding(model_name=resolved_model_name, cache_dir=self.cache_dir)
+                    model_kwargs["cache_dir"] = self.cache_dir
                 if self.threads is not None:
-                    return TextEmbedding(model_name=resolved_model_name, threads=self.threads)
-                return TextEmbedding(model_name=resolved_model_name)
+                    model_kwargs["threads"] = self.threads
+                return TextEmbedding(**model_kwargs)
 
             self._model = await asyncio.to_thread(_create_model)
             logger.info(

src/basic_memory/repository/search_repository.py

@@ -13,6 +13,7 @@
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from basic_memory.config import BasicMemoryConfig, ConfigManager, DatabaseBackend
+from basic_memory.repository.embedding_provider_factory import create_embedding_provider
 from basic_memory.repository.postgres_search_repository import PostgresSearchRepository
 from basic_memory.repository.search_index_row import SearchIndexRow
 from basic_memory.repository.search_repository_base import VectorSyncBatchResult
@@ -120,19 +121,37 @@ def create_search_repository(
     Returns:
         SearchRepository: Backend-appropriate search repository instance
     """
-    # Prefer explicit parameter; fall back to ConfigManager for backwards compatibility
+    # Resolve config once so backend detection and the shared embedding provider
+    # come from the same source. Prefer the explicit arg; fall back to ConfigManager
+    # for backwards compatibility.
+    config = app_config or ConfigManager().config
     if database_backend is None:
-        config = app_config or ConfigManager().config
         database_backend = config.database_backend
 
+    # Trigger: every request, sync batch, and project builds its own search repo.
+    # Why: each repo __init__ would otherwise call create_embedding_provider(), and
+    # the process-wide cache can be bypassed if its key ever drifts (#872), reloading
+    # the ~2.3GB ONNX model and leaking memory in onnxruntime's CPU arena.
+    # Outcome: resolve the cached singleton here once and inject it, so the provider
+    # is the single source of truth across all callers of this factory.
+    embedding_provider = None
+    if config.semantic_search_enabled:
+        embedding_provider = create_embedding_provider(config)
+
     if database_backend == DatabaseBackend.POSTGRES:  # pragma: no cover
         return PostgresSearchRepository(  # pragma: no cover
             session_maker,
             project_id=project_id,
             app_config=app_config,
+            embedding_provider=embedding_provider,
         )
     else:
-        return SQLiteSearchRepository(session_maker, project_id=project_id, app_config=app_config)
+        return SQLiteSearchRepository(
+            session_maker,
+            project_id=project_id,
+            app_config=app_config,
+            embedding_provider=embedding_provider,
+        )
 
 
 __all__ = [

test-int/semantic/test_embedding_provider_reuse.py

@@ -0,0 +1,111 @@
+"""Integration tests for process-wide embedding provider reuse (#872).
+
+A long-running ``basic-memory mcp`` server constructs a new search repository per
+request, per sync batch, and per project. Each repository used to derive its own
+embedding provider via ``create_embedding_provider()``. If the provider cache key
+ever drifted, that reloaded the ~2.3GB FastEmbed/ONNX model and leaked memory in
+onnxruntime's CPU arena (which never returns memory to the OS).
+
+These tests use the *real* composition paths — ``create_embedding_provider``, the
+``create_search_repository`` factory, and the FastAPI deps function
+``get_search_repository`` — with a real FastEmbed provider. FastEmbed loads the
+ONNX model lazily on first embed, so constructing providers/repositories here is
+cheap and never touches the native model.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+import pytest
+
+from basic_memory.config import BasicMemoryConfig, DatabaseBackend, ProjectEntry
+from basic_memory.deps.repositories import get_search_repository
+from basic_memory.repository.embedding_provider_factory import (
+    create_embedding_provider,
+    reset_embedding_provider_cache,
+)
+from basic_memory.repository.fastembed_provider import FastEmbedEmbeddingProvider
+from basic_memory.repository.search_repository import create_search_repository
+from basic_memory.repository.sqlite_search_repository import SQLiteSearchRepository
+
+
+def _semantic_config(config_home) -> BasicMemoryConfig:
+    """Build a semantic-enabled FastEmbed config rooted at the test home."""
+    return BasicMemoryConfig(
+        env="test",
+        projects={"test-project": ProjectEntry(path=str(config_home))},
+        default_project="test-project",
+        database_backend=DatabaseBackend.SQLITE,
+        semantic_search_enabled=True,
+        semantic_embedding_provider="fastembed",
+    )
+
+
+@pytest.fixture(autouse=True)
+def _reset_provider_cache():
+    reset_embedding_provider_cache()
+    yield
+    reset_embedding_provider_cache()
+
+
+def test_factory_resolves_single_provider_across_repositories(config_home, engine_factory):
+    """The factory must inject one cached provider into every search repository."""
+    _engine, session_maker = engine_factory
+    config = _semantic_config(config_home)
+
+    expected_provider = create_embedding_provider(config)
+    assert isinstance(expected_provider, FastEmbedEmbeddingProvider)
+
+    # Two repositories, mimicking per-request / per-sync construction.
+    repo_a = cast(
+        SQLiteSearchRepository,
+        create_search_repository(session_maker, project_id=1, app_config=config),
+    )
+    repo_b = cast(
+        SQLiteSearchRepository,
+        create_search_repository(session_maker, project_id=2, app_config=config),
+    )
+
+    # Both repos reuse the exact same cached provider object — no second model load.
+    assert repo_a._embedding_provider is expected_provider
+    assert repo_b._embedding_provider is expected_provider
+
+
+@pytest.mark.asyncio
+async def test_deps_path_reuses_cached_provider(config_home, engine_factory):
+    """The real FastAPI deps function must reuse the cached provider, not rebuild it."""
+    _engine, session_maker = engine_factory
+    config = _semantic_config(config_home)
+
+    expected_provider = create_embedding_provider(config)
+
+    repo = cast(
+        SQLiteSearchRepository,
+        await get_search_repository(
+            session_maker=session_maker,
+            project_id=1,
+            app_config=config,
+        ),
+    )
+
+    assert repo._embedding_provider is expected_provider
+
+
+def test_factory_skips_provider_when_semantic_disabled(config_home, engine_factory):
+    """With semantic search off, no provider is created and none is injected."""
+    _engine, session_maker = engine_factory
+    config = BasicMemoryConfig(
+        env="test",
+        projects={"test-project": ProjectEntry(path=str(config_home))},
+        default_project="test-project",
+        database_backend=DatabaseBackend.SQLITE,
+        semantic_search_enabled=False,
+    )
+
+    repo = cast(
+        SQLiteSearchRepository,
+        create_search_repository(session_maker, project_id=1, app_config=config),
+    )
+
+    assert repo._embedding_provider is None