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 DirectMem0Adapter._ensure_initialized() when the 'mem0' package is missing. After openai and qdrant-client come up, the backend builds a mem0 config and calls Mem0Memory.from_config; an ImportError in that block is re-raised with this message pointing at the headroom-ai[memory-stack] extra, which bundles the whole memory stack.

Source

Thrown at headroom/memory/backends/direct_mem0.py:255

                "embedder": {
                    "provider": "openai",
                    "config": {"model": self._config.embedder_model},
                },
            }

            if self._config.enable_graph:
                mem0_config["graph_store"] = {
                    "provider": "neo4j",
                    "config": {
                        "url": self._config.neo4j_uri,
                        "username": self._config.neo4j_user,
                        "password": self._config.neo4j_password,
                    },
                }

            self._mem0_client = await asyncio.to_thread(Mem0Memory.from_config, mem0_config)
        except ImportError:
            raise ImportError(
                "mem0 package not installed. Install with: pip install 'headroom-ai[memory-stack]'"
            ) from None

        self._initialized = True

    async def ensure_initialized(self) -> None:
        """Public initialization hook for callers that need readiness guarantees."""
        await self._ensure_initialized()

    def _embed(self, text: str) -> list[float]:
        """Generate embedding for text using OpenAI."""
        response = self._openai_client.embeddings.create(
            input=text,
            model=self._config.embedder_model,
        )
        return list(response.data[0].embedding)

    def _generate_id(self, content: str, user_id: str) -> str:

View on GitHub (pinned to 322425c43b)

Solutions

pip install 'headroom-ai[memory-stack]'
Verify mem0 imports cleanly: python -c 'from mem0 import Memory' — if this fails with a different ImportError, reinstall mem0 to fix the broken transitive dependency
Use the plain sqlite backend if you do not need mem0 semantics

Example fix

# before
pip install openai qdrant-client  # mem0 missing
await adapter.save('x', user_id='u')  # ImportError: mem0 package not installed

# after
pip install 'headroom-ai[memory-stack]'
await adapter.save('x', user_id='u')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

required = ['openai', 'qdrant_client', 'mem0', 'neo4j']
missing = [m for m in required if importlib.util.find_spec(m) is None]
if missing:
    raise SystemExit(f'Missing packages {missing}; run: pip install "headroom-ai[memory-stack]"')

Try / catch

try:
    await backend.save(content, user_id='u1')
except ImportError as e:
    logger.error('memory stack incomplete: %s', e)
    raise

Prevention

Prefer the bundled extra over hand-picked packages so mem0, openai, and qdrant-client stay version-aligned
Verify 'from mem0 import Memory' works in the deployment image as a CI step
Initialize the backend explicitly at startup (await backend.ensure_initialized()) to surface errors before requests

When it happens

Trigger: First memory operation on DirectMem0Adapter when openai and qdrant-client are present but mem0 is not; also reached when 'from mem0 import Memory as Mem0Memory' inside the init block fails (e.g. broken mem0 install raising ImportError internally).

Common situations: Hand-picking dependencies instead of using the extra; a corrupted mem0 install whose sub-imports raise ImportError; upgrading headroom without reinstalling extras.

Related errors

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