{"record":{"id":"4b0e7faad52d3a88","repo":"headroomlabs-ai/headroom","slug":"qdrant-neo4j-backend-requires-additional-packages","errorCode":null,"errorMessage":"qdrant-neo4j backend requires additional packages. Install with: pip install 'headroom-ai[memory-stack]'\nAnd start Docker services: docker compose up -d qdrant neo4j","messagePattern":"qdrant-neo4j backend requires additional packages\\. Install with: pip install 'headroom-ai\\[memory-stack\\]'\nAnd start Docker services: docker compose up -d qdrant neo4j","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/memory/easy.py","lineNumber":180,"sourceCode":"            try:\n                from headroom.memory.backends.direct_mem0 import (\n                    DirectMem0Adapter,\n                    Mem0Config,\n                )\n\n                mem0_config = Mem0Config(\n                    qdrant_url=self._qdrant_url,\n                    qdrant_host=self._qdrant_host,\n                    qdrant_port=self._qdrant_port,\n                    qdrant_api_key=self._qdrant_api_key,\n                    neo4j_uri=self._neo4j_uri,\n                    neo4j_user=self._neo4j_user,\n                    neo4j_password=self._neo4j_password,\n                    enable_graph=True,\n                )\n                self._backend = DirectMem0Adapter(mem0_config)\n            except ImportError as e:\n                raise ImportError(\n                    \"qdrant-neo4j backend requires additional packages. \"\n                    \"Install with: pip install 'headroom-ai[memory-stack]'\\n\"\n                    \"And start Docker services: docker compose up -d qdrant neo4j\"\n                ) from e\n        else:\n            raise ValueError(f\"Unknown backend: {self._backend_type}\")\n\n        self._initialized = True\n\n    async def save(\n        self,\n        content: str,\n        user_id: str,\n        importance: float = 0.5,\n        facts: list[str] | None = None,\n        entities: list[dict[str, str]] | None = None,\n        relationships: list[dict[str, str]] | None = None,\n        metadata: dict[str, Any] | None = None,","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/easy.py#L162-L198","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["pip install 'headroom-ai[memory-stack]'","Start the services: docker compose up -d qdrant neo4j (needed after imports succeed)","Check the chained exception (__cause__) to see exactly which module was missing if the install still fails","If you just want a quick start with no external services, select the sqlite/local backend instead"],"exampleFix":"# before\npip install headroom-ai\neasy = MemoryEasy(backend='qdrant-neo4j')\nawait easy.save('x')  # ImportError: qdrant-neo4j backend requires additional packages...\n\n# after\npip install 'headroom-ai[memory-stack]'\ndocker compose up -d qdrant neo4j\neasy = MemoryEasy(backend='qdrant-neo4j')\nawait easy.save('x')","handlingStrategy":"validation","validationCode":"import importlib.util\n\nmissing = [m for m in ('openai', 'qdrant_client', 'mem0', 'neo4j')\n           if importlib.util.find_spec(m) is None]\nif missing:\n    raise SystemExit(f'Missing {missing}; pip install \"headroom-ai[memory-stack]\"')\n# also verify services are up before init\nimport socket\nfor host, port in [('localhost', 6333), ('localhost', 7687)]:\n    with socket.create_connection((host, port), timeout=2):\n        pass","typeGuard":null,"tryCatchPattern":"try:\n    easy = MemoryEasy(backend='qdrant-neo4j')\n    await easy.initialize()  # surface ImportError now, not mid-request\nexcept ImportError as e:\n    logger.error('backend deps missing (%s); falling back to sqlite', e.__cause__)\n    easy = MemoryEasy(backend='sqlite')","preventionTips":["Install the [memory-stack] extra and run docker compose up -d qdrant neo4j as part of setup scripts","Initialize the easy client eagerly at startup to fail before serving traffic","Keep a dependency-free backend (sqlite) configured as an explicit fallback for local dev"],"tags":["python","import","dependency","mem0","qdrant","neo4j","docker","memory-stack"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}