headroomlabs-ai/headroom · error · ImportError

qdrant-neo4j backend requires additional packages. Install w

Error message

qdrant-neo4j backend requires additional packages. Install with: pip install 'headroom-ai[memory-stack]'
And start Docker services: docker compose up -d qdrant neo4j

What it means

ImportError raised by the easy-init layer (MemoryEasy, backend 'qdrant-neo4j') when constructing DirectMem0Adapter triggers any ImportError — i.e. the memory-stack extra packages (mem0/openai/qdrant-client/neo4j) are missing. The message also reminds you the backend needs the Qdrant and Neo4j services running via docker compose; the chained cause (from e) carries the specific missing module.

Source

Thrown at headroom/memory/easy.py:180

            try:
                from headroom.memory.backends.direct_mem0 import (
                    DirectMem0Adapter,
                    Mem0Config,
                )

                mem0_config = Mem0Config(
                    qdrant_url=self._qdrant_url,
                    qdrant_host=self._qdrant_host,
                    qdrant_port=self._qdrant_port,
                    qdrant_api_key=self._qdrant_api_key,
                    neo4j_uri=self._neo4j_uri,
                    neo4j_user=self._neo4j_user,
                    neo4j_password=self._neo4j_password,
                    enable_graph=True,
                )
                self._backend = DirectMem0Adapter(mem0_config)
            except ImportError as e:
                raise ImportError(
                    "qdrant-neo4j backend requires additional packages. "
                    "Install with: pip install 'headroom-ai[memory-stack]'\n"
                    "And start Docker services: docker compose up -d qdrant neo4j"
                ) from e
        else:
            raise ValueError(f"Unknown backend: {self._backend_type}")

        self._initialized = True

    async def save(
        self,
        content: str,
        user_id: str,
        importance: float = 0.5,
        facts: list[str] | None = None,
        entities: list[dict[str, str]] | None = None,
        relationships: list[dict[str, str]] | None = None,
        metadata: dict[str, Any] | None = None,

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install 'headroom-ai[memory-stack]'
2. Start the services: docker compose up -d qdrant neo4j (needed after imports succeed)
3. Check the chained exception (__cause__) to see exactly which module was missing if the install still fails
4. If you just want a quick start with no external services, select the sqlite/local backend instead

Example fix

# before
pip install headroom-ai
easy = MemoryEasy(backend='qdrant-neo4j')
await easy.save('x')  # ImportError: qdrant-neo4j backend requires additional packages...

# after
pip install 'headroom-ai[memory-stack]'
docker compose up -d qdrant neo4j
easy = MemoryEasy(backend='qdrant-neo4j')
await easy.save('x')

import importlib.util

missing = [m for m in ('openai', 'qdrant_client', 'mem0', 'neo4j')
           if importlib.util.find_spec(m) is None]
if missing:
    raise SystemExit(f'Missing {missing}; pip install "headroom-ai[memory-stack]"')
# also verify services are up before init
import socket
for host, port in [('localhost', 6333), ('localhost', 7687)]:
    with socket.create_connection((host, port), timeout=2):
        pass

try:
    easy = MemoryEasy(backend='qdrant-neo4j')
    await easy.initialize()  # surface ImportError now, not mid-request
except ImportError as e:
    logger.error('backend deps missing (%s); falling back to sqlite', e.__cause__)
    easy = MemoryEasy(backend='sqlite')

When it happens

Trigger: MemoryEasy with backend='qdrant-neo4j' during lazy initialization when any of the memory-stack imports fails; services not yet started surface later as connection errors, but missing packages fail here first.

Common situations: pip install headroom-ai without extras; fresh clone where docker compose services were never started; partial installs where only some of mem0/openai/qdrant-client/neo4j are present.

Related errors

• qdrant-client not installed. Install with: pip install qdran
• mem0 package not installed. Install with: pip install 'headr
• openai package not installed. Install with: pip install open
• mem0 package not installed. Install with: pip install 'headr
• Magika is required for ML-based content detection. Install w

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