headroomlabs-ai/headroom · error · ImportError

mem0 package not installed. Install with: pip install 'headr

Error message

mem0 package not installed. Install with: pip install 'headroom-ai[memory-stack]'

What it means

Raised by Mem0Backend._ensure_client() when 'from mem0 import Memory' fails. Unlike the direct adapter (222), this is the standard mem0 backend wrapper; it initializes its client lazily on the first operation and only needs the mem0 package (cloud or local mode), not the full memory-stack.

Source

Thrown at headroom/memory/backends/mem0.py:126

        """
        self._config = config or Mem0Config()
        self._client: Any = None
        self._initialized = False

    async def _ensure_client(self) -> Any:
        """Ensure Mem0 client is initialized.

        Returns:
            The initialized Mem0 Memory client.

        Raises:
            ImportError: If mem0 package is not installed.
        """
        if self._client is None:
            try:
                from mem0 import Memory as Mem0Memory
            except ImportError:
                raise ImportError(
                    "mem0 package not installed. Install with: pip install 'headroom-ai[memory-stack]'"
                ) from None

            if self._config.mode == "cloud":
                if not self._config.api_key:
                    raise ValueError("api_key is required for cloud mode")
                # Cloud mode - use API key
                self._client = await asyncio.to_thread(Mem0Memory, api_key=self._config.api_key)
            else:
                # Local mode with configuration
                qdrant_provider_cfg: dict[str, Any] = {
                    "collection_name": self._config.collection_name,
                }
                if self._config.qdrant_url:
                    qdrant_provider_cfg["url"] = self._config.qdrant_url
                else:
                    qdrant_provider_cfg["host"] = self._config.qdrant_host
                    qdrant_provider_cfg["port"] = self._config.qdrant_port

View on GitHub (pinned to 322425c43b)

Solutions

pip install 'headroom-ai[memory-stack]'
Or the minimal fix: pip install mem0ai
Verify in the app venv: python -c 'from mem0 import Memory'
Consider the sqlite/local backend if you want zero external packages

Example fix

# before
backend = Mem0Backend(Mem0Config(mode='cloud', api_key=...))
await backend.save('note')  # ImportError: mem0 package not installed

# after
pip install 'headroom-ai[memory-stack]'
await backend.save('note')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec('mem0') is None:
    raise SystemExit('mem0 required for Mem0Backend; pip install "headroom-ai[memory-stack]"')

Try / catch

try:
    await backend.save('note')
except ImportError as e:
    if 'mem0 package not installed' in str(e):
        # degrade gracefully to a local backend if available
        backend = make_local_backend()
    else:
        raise

Prevention

Declare the memory-stack extra in your project's dependencies when using Mem0Backend
Probe optional imports at startup and pick a fallback backend deliberately
Add an import smoke test to CI

When it happens

Trigger: Constructing Mem0Backend with a Mem0Config and issuing the first save/search call; the lazy _ensure_client() hits the ImportError and re-raises with the extra name.

Common situations: Installing headroom-ai core without extras; CI pipelines trimming optional deps; using mem0 cloud mode where developers assume no local packages are needed but the SDK is still required.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/c4b665c469c194dc. Report an issue: GitHub.