headroomlabs-ai/headroom · error · ValueError

Unknown memory backend: {self.config.backend}

Error message

Unknown memory backend: {self.config.backend}

What it means

Error "Unknown memory backend: {self.config.backend}" thrown in headroomlabs-ai/headroom.

Source

Thrown at headroom/proxy/memory_handler.py:443

                    neo4j_uri=self.config.neo4j_uri,
                    neo4j_user=self.config.neo4j_user,
                    neo4j_password=self.config.neo4j_password,
                    enable_graph=True,
                )
                self._backend = DirectMem0Adapter(mem0_config)
                await self._backend.ensure_initialized()
                qdrant_target = (
                    self.config.qdrant_url or f"{self.config.qdrant_host}:{self.config.qdrant_port}"
                )
                logger.info(f"Memory: Initialized Qdrant+Neo4j backend ({qdrant_target})")
            except ImportError as e:
                logger.error(
                    f"Memory: Failed to import qdrant-neo4j dependencies: {e}. "
                    "Install with: pip install 'headroom-ai[memory-stack]'"
                )
                raise
        else:
            raise ValueError(f"Unknown memory backend: {self.config.backend}")

        self._initialized = True

        # Auto-import from Memory Bridge if configured
        if self.config.bridge_enabled and self.config.bridge_auto_import:
            await self._init_and_import_bridge()

    async def _init_and_import_bridge(self) -> None:
        """Initialize the Memory Bridge and run auto-import."""
        if self._bridge is not None:
            return
        try:
            from headroom.memory.bridge import MemoryBridge
            from headroom.memory.bridge_config import BridgeConfig, MarkdownFormat

            bridge_config = BridgeConfig(
                md_paths=[Path(p) for p in self.config.bridge_md_paths],
                md_format=MarkdownFormat(self.config.bridge_md_format),

View on GitHub (pinned to 322425c43b)

Solutions

1. Set the memory backend config to a supported backend name
2. Check the backend value '{self.config.backend}' for typos against the documented list
3. If using an external backend, ensure it is registered before the handler starts

When it happens

Trigger: Raised when the proxy memory handler is configured with a backend name it does not recognize.

Common situations: See trigger scenarios.

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