Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(memory): resolve Qdrant connection from HEADROOM_QDRANT_* env vars (#31)
ipapapad3c37d709841
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7b82118cd..47b83c3b4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -98,6 +98,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0LIKE on the raw JSON string, so rows survive metadata rewrites.### Added+- **`HEADROOM_QDRANT_*` environment variables for memory Qdrant configuration**+ (#31) — `Memory(backend="qdrant-neo4j")`, `Mem0Config`, `MemoryConfig`, and+ `ProxyConfig` now resolve their Qdrant connection from+ `HEADROOM_QDRANT_URL`, `HEADROOM_QDRANT_HOST`, `HEADROOM_QDRANT_PORT`,+ `HEADROOM_QDRANT_API_KEY`, `HEADROOM_QDRANT_HTTPS`,+ `HEADROOM_QDRANT_PREFER_GRPC`, and `HEADROOM_QDRANT_GRPC_PORT`. Explicit+ constructor arguments still win; unset env keeps the existing+ `localhost:6333` defaults. Adds matching `--memory-qdrant-{url,host,port,api-key}`+ CLI flags. Enables hosted Qdrant (Qdrant Cloud) and shared/remote Qdrant+ stacks without code changes. New helper:+ [`headroom/memory/qdrant_env.py`](headroom/memory/qdrant_env.py).- **Telemetry stack & install-mode identity fields** — anonymous beacon nowreports `headroom_stack` (how Headroom is invoked: `proxy`, `wrap_claude`,`adapter_ts_openai`, ...) and `install_mode` (`wrapped` / `persistent` /diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex 738d7d8e4..4b587ef98 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -2,6 +2,7 @@import osimport sys+from typing import Anyimport click@@ -190,6 +191,37 @@ from .main import maindefault=10,help="Number of memories to inject as context (default: 10)",)+ "--memory-qdrant-url",+ default=None,+ help=(+ "Full Qdrant URL for the qdrant-neo4j backend "+ "(e.g. https://xyz.cloud.qdrant.io:6333). When set, takes precedence over "+ "--memory-qdrant-host/--memory-qdrant-port. "+ "Also reads HEADROOM_QDRANT_URL."+ ),+)+ "--memory-qdrant-host",+ default=None,+ help=(+ "Qdrant host for the qdrant-neo4j backend "+ "(default: localhost, also reads HEADROOM_QDRANT_HOST)"+ ),+)+ "--memory-qdrant-port",+ type=int,+ default=None,+ help=(+ "Qdrant port for the qdrant-neo4j backend (default: 6333, also reads HEADROOM_QDRANT_PORT)"+ ),+)+ "--memory-qdrant-api-key",+ default=None,+ help=("API key for hosted Qdrant (e.g. Qdrant Cloud). Also reads HEADROOM_QDRANT_API_KEY."),+)# Traffic Learning (live pattern extraction from proxy traffic)@click.option("--learn",@@ -294,6 +326,10 @@ def proxy(no_memory_tools: bool,no_memory_context: bool,memory_top_k: int,+ memory_qdrant_url: str | None,+ memory_qdrant_host: str | None,+ memory_qdrant_port: int | None,+ memory_qdrant_api_key: str | None,learn: bool,no_learn: bool,backend: str,@@ -392,6 +428,19 @@ def proxy(# License key for managed/enterprise deployments (optional)license_key = os.environ.get("HEADROOM_LICENSE_KEY")+ # Qdrant connection for the qdrant-neo4j backend. CLI flags default+ # to None; when omitted we let ProxyConfig's default_factory resolve+ # HEADROOM_QDRANT_* env vars. Explicit CLI values win over env.+ qdrant_overrides: dict[str, Any] = {}+ if memory_qdrant_url is not None:+ qdrant_overrides["memory_qdrant_url"] = memory_qdrant_url+ if memory_qdrant_host is not None:+ qdrant_overrides["memory_qdrant_host"] = memory_qdrant_host+ if memory_qdrant_port is not None:+ qdrant_overrides["memory_qdrant_port"] = memory_qdrant_port+ if memory_qdrant_api_key is not None:+ qdrant_overrides["memory_qdrant_api_key"] = memory_qdrant_api_key+config = ProxyConfig(host=host,port=port,@@ -431,6 +480,7 @@ def proxy(memory_inject_tools=not no_memory_tools,memory_inject_context=not no_memory_context,memory_top_k=memory_top_k,+ **qdrant_overrides,# Traffic Learning: only with --learn, never with --no-learn# Stateless mode disables learning (requires filesystem)traffic_learning_enabled=False if is_stateless else (learn and not no_learn),diff --git a/headroom/memory/backends/direct_mem0.py b/headroom/memory/backends/direct_mem0.pyindex d972b69ba..c086ef012 100644--- a/headroom/memory/backends/direct_mem0.py+++ b/headroom/memory/backends/direct_mem0.py@@ -51,10 +51,11 @@ import asyncioimport hashlibimport loggingimport uuid-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom datetime import datetime, timezonefrom typing import Any+from headroom.memory import qdrant_envfrom headroom.memory.models import Memoryfrom headroom.memory.ports import MemorySearchResult@@ -70,13 +71,23 @@ def _utcnow() -> datetime:class Mem0Config:"""Configuration for Direct Mem0 adapter.+ Qdrant connection fields default to values read from ``HEADROOM_QDRANT_*``+ environment variables (see :mod:`headroom.memory.qdrant_env`). Passing an+ explicit value to the constructor always wins over the environment.+Attributes:mode: Operating mode - "local" for embedded services.neo4j_uri: Neo4j connection URI for local mode.neo4j_user: Neo4j username for local mode.neo4j_password: Neo4j password for local mode.+ qdrant_url: Full Qdrant URL (e.g. ``https://xyz.cloud.qdrant.io:6333``).+ When set, takes precedence over ``qdrant_host``/``qdrant_port``.qdrant_host: Qdrant host for local mode.qdrant_port: Qdrant port for local mode.+ qdrant_api_key: API key for hosted Qdrant (e.g. Qdrant Cloud).+ qdrant_https: Force HTTPS on/off. ``None`` lets the Qdrant client decide.+ qdrant_prefer_grpc: Use gRPC transport instead of HTTP.+ qdrant_grpc_port: gRPC port (only used when ``qdrant_prefer_grpc`` is True).embedder_model: Embedding model for vector search.collection_name: Name of the collection in Qdrant.enable_graph: Whether to enable graph storage (Neo4j).@@ -90,9 +101,14 @@ class Mem0Config:neo4j_user: str = "neo4j"neo4j_password: str = "password"- # Qdrant settings- qdrant_host: str = "localhost"- qdrant_port: int = 6333+ # Qdrant settings (defaults resolve from HEADROOM_QDRANT_* env vars)+ qdrant_url: str | None = field(default_factory=qdrant_env.qdrant_env_url)+ qdrant_host: str = field(default_factory=qdrant_env.qdrant_env_host)+ qdrant_port: int = field(default_factory=qdrant_env.qdrant_env_port)+ qdrant_api_key: str | None = field(default_factory=qdrant_env.qdrant_env_api_key)+ qdrant_https: bool | None = field(default_factory=qdrant_env.qdrant_env_https)+ qdrant_prefer_grpc: bool = field(default_factory=qdrant_env.qdrant_env_prefer_grpc)+ qdrant_grpc_port: int = field(default_factory=qdrant_env.qdrant_env_grpc_port)# Embedding settingsembedder_model: str = "text-embedding-3-small"@@ -163,10 +179,16 @@ class DirectMem0Adapter:try:from qdrant_client import QdrantClient- self._qdrant_client = QdrantClient(+ client_kwargs = qdrant_env.build_qdrant_client_kwargs(+ url=self._config.qdrant_url,host=self._config.qdrant_host,port=self._config.qdrant_port,+ api_key=self._config.qdrant_api_key,+ https=self._config.qdrant_https,+ prefer_grpc=self._config.qdrant_prefer_grpc,+ grpc_port=self._config.qdrant_grpc_port,)+ self._qdrant_client = QdrantClient(**client_kwargs)except ImportError:raise ImportError("qdrant-client not installed. Install with: pip install qdrant-client"@@ -189,14 +211,21 @@ class DirectMem0Adapter:try:from mem0 import Memory as Mem0Memory+ 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+ if self._config.qdrant_api_key:+ qdrant_provider_cfg["api_key"] = self._config.qdrant_api_key+mem0_config: dict[str, Any] = {"vector_store": {"provider": "qdrant",- "config": {- "host": self._config.qdrant_host,- "port": self._config.qdrant_port,- "collection_name": self._config.collection_name,- },+ "config": qdrant_provider_cfg,},"llm": {"provider": "openai",diff --git a/headroom/memory/backends/mem0.py b/headroom/memory/backends/mem0.pyindex 54a2c3821..7aefce0f6 100644--- a/headroom/memory/backends/mem0.py+++ b/headroom/memory/backends/mem0.py@@ -13,10 +13,11 @@ from __future__ import annotationsimport asyncioimport uuid-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom datetime import datetime, timezonefrom typing import Any+from headroom.memory import qdrant_envfrom headroom.memory.models import Memoryfrom headroom.memory.ports import MemoryFilter, VectorFilter, VectorSearchResult@@ -25,14 +26,24 @@ from headroom.memory.ports import MemoryFilter, VectorFilter, VectorSearchResultclass Mem0Config:"""Configuration for Mem0 backend.+ Qdrant connection fields default to values read from ``HEADROOM_QDRANT_*``+ environment variables (see :mod:`headroom.memory.qdrant_env`). Passing an+ explicit value to the constructor always wins over the environment.+Attributes:mode: Operating mode - "local" for embedded or "cloud" for Mem0 API.- api_key: API key for cloud mode.+ api_key: API key for Mem0 cloud mode.neo4j_uri: Neo4j connection URI for local mode.neo4j_user: Neo4j username for local mode.neo4j_password: Neo4j password for local mode.+ qdrant_url: Full Qdrant URL (e.g. ``https://xyz.cloud.qdrant.io:6333``).+ When set, takes precedence over ``qdrant_host``/``qdrant_port``.qdrant_host: Qdrant host for local mode.qdrant_port: Qdrant port for local mode.+ qdrant_api_key: API key for hosted Qdrant (e.g. Qdrant Cloud).+ qdrant_https: Force HTTPS on/off. ``None`` lets the Qdrant client decide.+ qdrant_prefer_grpc: Use gRPC transport instead of HTTP.+ qdrant_grpc_port: gRPC port (only used when ``qdrant_prefer_grpc`` is True).llm_model: LLM model for entity extraction.embedder_model: Embedding model for vector search.collection_name: Name of the collection/namespace in Mem0.@@ -47,8 +58,14 @@ class Mem0Config:neo4j_uri: str = "neo4j://localhost:7687"neo4j_user: str = "neo4j"neo4j_password: str = "password"- qdrant_host: str = "localhost"- qdrant_port: int = 6333+ # Qdrant settings (defaults resolve from HEADROOM_QDRANT_* env vars)+ qdrant_url: str | None = field(default_factory=qdrant_env.qdrant_env_url)+ qdrant_host: str = field(default_factory=qdrant_env.qdrant_env_host)+ qdrant_port: int = field(default_factory=qdrant_env.qdrant_env_port)+ qdrant_api_key: str | None = field(default_factory=qdrant_env.qdrant_env_api_key)+ qdrant_https: bool | None = field(default_factory=qdrant_env.qdrant_env_https)+ qdrant_prefer_grpc: bool = field(default_factory=qdrant_env.qdrant_env_prefer_grpc)+ qdrant_grpc_port: int = field(default_factory=qdrant_env.qdrant_env_grpc_port)# Common settingsllm_model: str = "gpt-4o-mini" # For entity extraction@@ -117,14 +134,21 @@ class Mem0Backend: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+ if self._config.qdrant_api_key:+ qdrant_provider_cfg["api_key"] = self._config.qdrant_api_key+config: dict[str, Any] = {"vector_store": {"provider": "qdrant",- "config": {- "host": self._config.qdrant_host,- "port": self._config.qdrant_port,- "collection_name": self._config.collection_name,- },+ "config": qdrant_provider_cfg,},"llm": {"provider": "openai",diff --git a/headroom/memory/easy.py b/headroom/memory/easy.pyindex 737137b17..2ad109f9e 100644--- a/headroom/memory/easy.py+++ b/headroom/memory/easy.py@@ -73,32 +73,52 @@ class Memory:- "qdrant-neo4j": External Qdrant + Neo4j. Requires Docker.db_path: Path for local database (only for "local" backend).Defaults to ~/.headroom/memory.db- qdrant_host: Qdrant host (only for "qdrant-neo4j" backend).+ qdrant_url: Full Qdrant URL (only for "qdrant-neo4j" backend). When set,+ takes precedence over ``qdrant_host``/``qdrant_port``. Useful for+ hosted Qdrant (Qdrant Cloud) and non-default container stacks.+ Defaults to the ``HEADROOM_QDRANT_URL`` env var if unset.+ qdrant_host: Qdrant host (only for "qdrant-neo4j" backend). Defaults+ to the ``HEADROOM_QDRANT_HOST`` env var or ``localhost``.+ qdrant_port: Qdrant port (only for "qdrant-neo4j" backend). Defaults+ to the ``HEADROOM_QDRANT_PORT`` env var or ``6333``.+ qdrant_api_key: API key for hosted Qdrant. Defaults to+ ``HEADROOM_QDRANT_API_KEY`` if unset.neo4j_uri: Neo4j URI (only for "qdrant-neo4j" backend).Examples:# Simplest usage - no config neededmemory = Memory()await memory.save("User likes Python", user_id="alice")- results = await memory.search("programming", user_id="alice")# With custom database pathmemory = Memory(db_path="./my_app.db")- # Production mode with Docker services+ # Production mode with local Docker servicesmemory = Memory(backend="qdrant-neo4j")++ # Hosted Qdrant via URL + API key (or set HEADROOM_QDRANT_URL /+ # HEADROOM_QDRANT_API_KEY in the environment)+ memory = Memory(+ backend="qdrant-neo4j",+ qdrant_url="https://xyz.cloud.qdrant.io:6333",+ qdrant_api_key="...",+ )"""def __init__(self,backend: str = "local",db_path: str | Path | None = None,- qdrant_host: str = "localhost",- qdrant_port: int = 6333,+ qdrant_url: str | None = None,+ qdrant_host: str | None = None,+ qdrant_port: int | None = None,+ qdrant_api_key: str | None = None,neo4j_uri: str = "neo4j://localhost:7687",neo4j_user: str = "neo4j",neo4j_password: str = "password",) -> None:+ from headroom.memory import qdrant_env+self._backend_type = backendself._backend: Any = Noneself._initialized = False@@ -113,9 +133,16 @@ class Memory:db_path = default_dbself._db_path = Path(db_path)- # Config for qdrant-neo4j backend- self._qdrant_host = qdrant_host- self._qdrant_port = qdrant_port+ # Config for qdrant-neo4j backend.+ # ``None`` sentinels fall back to HEADROOM_QDRANT_* env vars so that+ # ``Memory(backend="qdrant-neo4j")`` picks up hosted/custom Qdrant+ # deployments without any code changes. Explicit values always win.+ self._qdrant_url = qdrant_url if qdrant_url is not None else qdrant_env.qdrant_env_url()+ self._qdrant_host = qdrant_host if qdrant_host is not None else qdrant_env.qdrant_env_host()+ self._qdrant_port = qdrant_port if qdrant_port is not None else qdrant_env.qdrant_env_port()+ self._qdrant_api_key = (+ qdrant_api_key if qdrant_api_key is not None else qdrant_env.qdrant_env_api_key()+ )self._neo4j_uri = neo4j_uriself._neo4j_user = neo4j_userself._neo4j_password = neo4j_password@@ -139,8 +166,10 @@ class Memory:)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,diff --git a/headroom/memory/qdrant_env.py b/headroom/memory/qdrant_env.pynew file mode 100644index 000000000..c6c001f8c--- /dev/null+++ b/headroom/memory/qdrant_env.py@@ -0,0 +1,151 @@+"""Resolve Qdrant connection settings from environment variables.++Provides a single source of truth for ``HEADROOM_QDRANT_*`` env vars so that+``Memory``, ``Mem0Config``, ``DirectMem0Config``, and the proxy all pick up+the same defaults when the caller does not pass an explicit value.++Supported environment variables:++- ``HEADROOM_QDRANT_URL`` Full URL (e.g. ``https://xyz.cloud.qdrant.io:6333``).+ When set, takes precedence over host/port.+- ``HEADROOM_QDRANT_HOST`` Hostname. Default: ``localhost``.+- ``HEADROOM_QDRANT_PORT`` HTTP port. Default: ``6333``.+- ``HEADROOM_QDRANT_API_KEY`` API key for hosted Qdrant (e.g. Qdrant Cloud).+- ``HEADROOM_QDRANT_HTTPS`` ``true``/``false``. Forces HTTPS on/off.+- ``HEADROOM_QDRANT_PREFER_GRPC````true``/``false``. Use gRPC instead of HTTP.+- ``HEADROOM_QDRANT_GRPC_PORT`` gRPC port. Default: ``6334``.++Explicit constructor arguments always win over environment values; the env+vars only fill in defaults when the caller passes ``None`` (or omits the+argument on a dataclass that uses ``field(default_factory=...)``).+"""++from __future__ import annotations++import os++DEFAULT_QDRANT_HOST = "localhost"+DEFAULT_QDRANT_PORT = 6333+DEFAULT_QDRANT_GRPC_PORT = 6334++_TRUTHY = frozenset({"1", "true", "yes", "y", "on"})+_FALSY = frozenset({"0", "false", "no", "n", "off"})+++def _strip_env(name: str) -> str | None:+ """Return the trimmed env var value, or ``None`` if unset/empty."""+ raw = os.environ.get(name)+ if raw is None:+ return None+ stripped = raw.strip()+ return stripped or None+++def _parse_bool(raw: str | None) -> bool | None:+ """Parse a bool env value. Returns ``None`` if unset, else True/False.++ Unknown strings raise ``ValueError`` so misconfiguration is visible.+ """+ if raw is None:+ return None+ lowered = raw.lower()+ if lowered in _TRUTHY:+ return True+ if lowered in _FALSY:+ return False+ raise ValueError(f"Invalid boolean value {raw!r}; expected one of {sorted(_TRUTHY | _FALSY)}")+++def _parse_port(raw: str | None, var_name: str) -> int | None:+ """Parse a port env value. Returns ``None`` if unset."""+ if raw is None:+ return None+ try:+ port = int(raw)+ except ValueError as exc:+ raise ValueError(f"{var_name}={raw!r} is not a valid integer port") from exc+ if not 1 <= port <= 65535:+ raise ValueError(f"{var_name}={port} is outside the valid port range 1-65535")+ return port+++def qdrant_env_url() -> str | None:+ """Return ``HEADROOM_QDRANT_URL`` or ``None`` if unset."""+ return _strip_env("HEADROOM_QDRANT_URL")+++def qdrant_env_host() -> str:+ """Return ``HEADROOM_QDRANT_HOST`` or the ``localhost`` default."""+ return _strip_env("HEADROOM_QDRANT_HOST") or DEFAULT_QDRANT_HOST+++def qdrant_env_port() -> int:+ """Return ``HEADROOM_QDRANT_PORT`` or the ``6333`` default."""+ return (+ _parse_port(_strip_env("HEADROOM_QDRANT_PORT"), "HEADROOM_QDRANT_PORT")+ or DEFAULT_QDRANT_PORT+ )+++def qdrant_env_api_key() -> str | None:+ """Return ``HEADROOM_QDRANT_API_KEY`` or ``None`` if unset."""+ return _strip_env("HEADROOM_QDRANT_API_KEY")+++def qdrant_env_https() -> bool | None:+ """Return ``HEADROOM_QDRANT_HTTPS`` parsed as bool, or ``None`` if unset."""+ return _parse_bool(_strip_env("HEADROOM_QDRANT_HTTPS"))+++def qdrant_env_prefer_grpc() -> bool:+ """Return ``HEADROOM_QDRANT_PREFER_GRPC`` parsed as bool. Default: ``False``."""+ return _parse_bool(_strip_env("HEADROOM_QDRANT_PREFER_GRPC")) or False+++def qdrant_env_grpc_port() -> int:+ """Return ``HEADROOM_QDRANT_GRPC_PORT`` or the ``6334`` default."""+ return (+ _parse_port(_strip_env("HEADROOM_QDRANT_GRPC_PORT"), "HEADROOM_QDRANT_GRPC_PORT")+ or DEFAULT_QDRANT_GRPC_PORT+ )+++def build_qdrant_client_kwargs(+ *,+ url: str | None = None,+ host: str | None = None,+ port: int | None = None,+ api_key: str | None = None,+ https: bool | None = None,+ prefer_grpc: bool | None = None,+ grpc_port: int | None = None,+) -> dict[str, object]:+ """Build a kwargs dict suitable for ``qdrant_client.QdrantClient(**kwargs)``.++ URL takes precedence over host/port: if ``url`` is a non-empty string the+ returned dict contains ``url`` and omits ``host``/``port``. Otherwise+ ``host``/``port`` are populated (falling back to ``localhost:6333``).++ Optional fields (``api_key``, ``https``, ``prefer_grpc``, ``grpc_port``)+ are only included when they have a value, so callers that don't need them+ don't accidentally pass ``None`` into Qdrant client options that would+ override sensible library defaults.+ """+ kwargs: dict[str, object] = {}++ effective_url = url if url else None+ if effective_url:+ kwargs["url"] = effective_url+ else:+ kwargs["host"] = host or DEFAULT_QDRANT_HOST+ kwargs["port"] = port or DEFAULT_QDRANT_PORT++ if api_key:+ kwargs["api_key"] = api_key+ if https is not None:+ kwargs["https"] = https+ if prefer_grpc:+ kwargs["prefer_grpc"] = True+ kwargs["grpc_port"] = grpc_port or DEFAULT_QDRANT_GRPC_PORT++ return kwargsdiff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.pyindex ba7086d28..b57dc50d0 100644--- a/headroom/proxy/memory_handler.py+++ b/headroom/proxy/memory_handler.py@@ -33,6 +33,8 @@ from datetime import datetime, timezonefrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Literal+from headroom.memory import qdrant_env+if TYPE_CHECKING:from headroom.memory.backends.local import LocalBackend@@ -59,7 +61,12 @@ STARTUP_INIT_TIMEOUT_SECONDS = 30.0@dataclassclass MemoryConfig:- """Configuration for memory handler."""+ """Configuration for memory handler.++ Qdrant connection fields default to values read from ``HEADROOM_QDRANT_*``+ environment variables (see :mod:`headroom.memory.qdrant_env`). Passing an+ explicit value to the constructor always wins over the environment.+ """enabled: bool = Falsebackend: Literal["local", "qdrant-neo4j"] = "local"@@ -71,9 +78,11 @@ class MemoryConfig:# Native memory tool (Anthropic's built-in memory_20250818)use_native_tool: bool = Falsenative_memory_dir: str = "" # Directory for native memory files (default: ~/.headroom/memories)- # Qdrant+Neo4j config- qdrant_host: str = "localhost"- qdrant_port: int = 6333+ # Qdrant+Neo4j config (Qdrant defaults resolve from HEADROOM_QDRANT_* env vars)+ qdrant_url: str | None = field(default_factory=qdrant_env.qdrant_env_url)+ qdrant_host: str = field(default_factory=qdrant_env.qdrant_env_host)+ qdrant_port: int = field(default_factory=qdrant_env.qdrant_env_port)+ qdrant_api_key: str | None = field(default_factory=qdrant_env.qdrant_env_api_key)neo4j_uri: str = "neo4j://localhost:7687"neo4j_user: str = "neo4j"neo4j_password: str = "password"@@ -275,8 +284,10 @@ class MemoryHandler:)mem0_config = Mem0Config(+ qdrant_url=self.config.qdrant_url,qdrant_host=self.config.qdrant_host,qdrant_port=self.config.qdrant_port,+ qdrant_api_key=self.config.qdrant_api_key,neo4j_uri=self.config.neo4j_uri,neo4j_user=self.config.neo4j_user,neo4j_password=self.config.neo4j_password,@@ -284,10 +295,10 @@ class MemoryHandler:)self._backend = DirectMem0Adapter(mem0_config)await self._backend.ensure_initialized()- logger.info(- f"Memory: Initialized Qdrant+Neo4j backend "- f"({self.config.qdrant_host}:{self.config.qdrant_port})"+ 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}. "diff --git a/headroom/proxy/models.py b/headroom/proxy/models.pyindex 43ffa26f2..89b58d93a 100644--- a/headroom/proxy/models.py+++ b/headroom/proxy/models.py@@ -10,6 +10,7 @@ from dataclasses import dataclass, fieldfrom datetime import datetimefrom typing import Any, Literal+from headroom.memory import qdrant_envfrom headroom.providers.registry import ProviderApiOverrides# =============================================================================@@ -200,8 +201,11 @@ class ProxyConfig:memory_inject_context: bool = Truememory_top_k: int = 10memory_min_similarity: float = 0.3- memory_qdrant_host: str = "localhost"- memory_qdrant_port: int = 6333+ # Qdrant connection (defaults resolve from HEADROOM_QDRANT_* env vars)+ memory_qdrant_url: str | None = field(default_factory=qdrant_env.qdrant_env_url)+ memory_qdrant_host: str = field(default_factory=qdrant_env.qdrant_env_host)+ memory_qdrant_port: int = field(default_factory=qdrant_env.qdrant_env_port)+ memory_qdrant_api_key: str | None = field(default_factory=qdrant_env.qdrant_env_api_key)memory_neo4j_uri: str = "neo4j://localhost:7687"memory_neo4j_user: str = "neo4j"memory_neo4j_password: str = "password"diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 256776c70..22f201b95 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -484,8 +484,10 @@ class HeadroomProxy(inject_context=config.memory_inject_context,top_k=config.memory_top_k,min_similarity=config.memory_min_similarity,+ qdrant_url=config.memory_qdrant_url,qdrant_host=config.memory_qdrant_host,qdrant_port=config.memory_qdrant_port,+ qdrant_api_key=config.memory_qdrant_api_key,neo4j_uri=config.memory_neo4j_uri,neo4j_user=config.memory_neo4j_user,neo4j_password=config.memory_neo4j_password,diff --git a/tests/test_memory/test_qdrant_env.py b/tests/test_memory/test_qdrant_env.pynew file mode 100644index 000000000..a3f355d9d--- /dev/null+++ b/tests/test_memory/test_qdrant_env.py@@ -0,0 +1,317 @@+"""Tests for Qdrant environment-variable resolution.++Covers:+- Env var readers (host/port/url/api_key/https/prefer_grpc/grpc_port)+- Type coercion and validation (port range, bool parsing)+- ``build_qdrant_client_kwargs`` precedence (URL > host/port)+- Dataclass defaults reading env at construction time+- Explicit kwargs winning over env vars+- Public ``Memory`` class picking up env vars in ``qdrant-neo4j`` mode+"""++from __future__ import annotations++import pytest++from headroom.memory import qdrant_env+from headroom.memory.qdrant_env import (+ DEFAULT_QDRANT_GRPC_PORT,+ DEFAULT_QDRANT_HOST,+ DEFAULT_QDRANT_PORT,+ build_qdrant_client_kwargs,+ qdrant_env_api_key,+ qdrant_env_grpc_port,+ qdrant_env_host,+ qdrant_env_https,+ qdrant_env_port,+ qdrant_env_prefer_grpc,+ qdrant_env_url,+)++# All HEADROOM_QDRANT_* vars are cleared before every test so that the host+# environment (e.g. a developer's local ``direnv``) cannot leak into unit tests.+_QDRANT_ENV_VARS = (+ "HEADROOM_QDRANT_URL",+ "HEADROOM_QDRANT_HOST",+ "HEADROOM_QDRANT_PORT",+ "HEADROOM_QDRANT_API_KEY",+ "HEADROOM_QDRANT_HTTPS",+ "HEADROOM_QDRANT_PREFER_GRPC",+ "HEADROOM_QDRANT_GRPC_PORT",+)++[email protected](autouse=True)+def _clear_qdrant_env(monkeypatch: pytest.MonkeyPatch) -> None:+ for var in _QDRANT_ENV_VARS:+ monkeypatch.delenv(var, raising=False)+++# =============================================================================+# Env var readers+# =============================================================================+++class TestEnvReaders:+ def test_host_defaults_when_unset(self) -> None:+ assert qdrant_env_host() == DEFAULT_QDRANT_HOST++ def test_host_reads_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_HOST", "qdrant.internal")+ assert qdrant_env_host() == "qdrant.internal"++ def test_host_trims_whitespace(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_HOST", " qdrant.example ")+ assert qdrant_env_host() == "qdrant.example"++ def test_host_empty_string_falls_back_to_default(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_HOST", "")+ assert qdrant_env_host() == DEFAULT_QDRANT_HOST++ def test_port_defaults_when_unset(self) -> None:+ assert qdrant_env_port() == DEFAULT_QDRANT_PORT++ def test_port_reads_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "7333")+ assert qdrant_env_port() == 7333++ def test_port_rejects_non_numeric(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "not-a-port")+ with pytest.raises(ValueError, match="HEADROOM_QDRANT_PORT"):+ qdrant_env_port()++ def test_port_rejects_out_of_range(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "70000")+ with pytest.raises(ValueError, match="valid port range"):+ qdrant_env_port()++ def test_port_rejects_zero(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "0")+ with pytest.raises(ValueError, match="valid port range"):+ qdrant_env_port()++ def test_url_none_when_unset(self) -> None:+ assert qdrant_env_url() is None++ def test_url_reads_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_URL", "https://qdrant.cloud:6333")+ assert qdrant_env_url() == "https://qdrant.cloud:6333"++ def test_api_key_none_when_unset(self) -> None:+ assert qdrant_env_api_key() is None++ def test_api_key_reads_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_API_KEY", "secret-token")+ assert qdrant_env_api_key() == "secret-token"++ def test_https_none_when_unset(self) -> None:+ assert qdrant_env_https() is None++ @pytest.mark.parametrize("truthy", ["1", "true", "TRUE", "yes", "y", "on"])+ def test_https_truthy_values(self, monkeypatch: pytest.MonkeyPatch, truthy: str) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_HTTPS", truthy)+ assert qdrant_env_https() is True++ @pytest.mark.parametrize("falsy", ["0", "false", "FALSE", "no", "n", "off"])+ def test_https_falsy_values(self, monkeypatch: pytest.MonkeyPatch, falsy: str) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_HTTPS", falsy)+ assert qdrant_env_https() is False++ def test_https_rejects_garbage(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_HTTPS", "maybe")+ with pytest.raises(ValueError, match="Invalid boolean value"):+ qdrant_env_https()++ def test_prefer_grpc_defaults_false(self) -> None:+ assert qdrant_env_prefer_grpc() is False++ def test_prefer_grpc_reads_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_PREFER_GRPC", "true")+ assert qdrant_env_prefer_grpc() is True++ def test_grpc_port_defaults(self) -> None:+ assert qdrant_env_grpc_port() == DEFAULT_QDRANT_GRPC_PORT++ def test_grpc_port_reads_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_QDRANT_GRPC_PORT", "9999")+ assert qdrant_env_grpc_port() == 9999+++# =============================================================================+# build_qdrant_client_kwargs+# =============================================================================+++class TestBuildClientKwargs:+ def test_defaults_to_localhost(self) -> None:+ kwargs = build_qdrant_client_kwargs()+ assert kwargs == {"host": "localhost", "port": 6333}++ def test_explicit_host_and_port(self) -> None:+ kwargs = build_qdrant_client_kwargs(host="qdrant.internal", port=7333)+ assert kwargs == {"host": "qdrant.internal", "port": 7333}++ def test_url_takes_precedence_over_host_port(self) -> None:+ kwargs = build_qdrant_client_kwargs(+ url="https://xyz.cloud.qdrant.io:6333",+ host="ignored",+ port=9999,+ )+ assert kwargs == {"url": "https://xyz.cloud.qdrant.io:6333"}++ def test_empty_url_falls_back_to_host_port(self) -> None:+ kwargs = build_qdrant_client_kwargs(url="", host="h", port=1234)+ assert kwargs == {"host": "h", "port": 1234}++ def test_api_key_included_when_set(self) -> None:+ kwargs = build_qdrant_client_kwargs(api_key="secret")+ assert kwargs["api_key"] == "secret"++ def test_api_key_omitted_when_empty(self) -> None:+ kwargs = build_qdrant_client_kwargs(api_key="")+ assert "api_key" not in kwargs++ def test_https_passed_through_when_set(self) -> None:+ assert build_qdrant_client_kwargs(https=True)["https"] is True+ assert build_qdrant_client_kwargs(https=False)["https"] is False++ def test_https_omitted_when_none(self) -> None:+ kwargs = build_qdrant_client_kwargs(https=None)+ assert "https" not in kwargs++ def test_grpc_enables_only_when_preferred(self) -> None:+ kwargs = build_qdrant_client_kwargs(prefer_grpc=True, grpc_port=6334)+ assert kwargs["prefer_grpc"] is True+ assert kwargs["grpc_port"] == 6334++ def test_grpc_omitted_when_not_preferred(self) -> None:+ kwargs = build_qdrant_client_kwargs(prefer_grpc=False, grpc_port=6334)+ assert "prefer_grpc" not in kwargs+ assert "grpc_port" not in kwargs+++# =============================================================================+# Dataclass defaults+# =============================================================================+++def test_direct_mem0_config_defaults_read_env(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Mem0Config (direct_mem0) should resolve env vars via default_factory."""+ from headroom.memory.backends.direct_mem0 import Mem0Config++ monkeypatch.setenv("HEADROOM_QDRANT_HOST", "custom.example")+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "7777")+ monkeypatch.setenv("HEADROOM_QDRANT_URL", "https://cloud.example:6333")+ monkeypatch.setenv("HEADROOM_QDRANT_API_KEY", "my-api-key")++ cfg = Mem0Config()+ assert cfg.qdrant_host == "custom.example"+ assert cfg.qdrant_port == 7777+ assert cfg.qdrant_url == "https://cloud.example:6333"+ assert cfg.qdrant_api_key == "my-api-key"+++def test_direct_mem0_config_explicit_wins_over_env(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from headroom.memory.backends.direct_mem0 import Mem0Config++ monkeypatch.setenv("HEADROOM_QDRANT_HOST", "env-host")+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "7777")++ cfg = Mem0Config(qdrant_host="explicit-host", qdrant_port=5555)+ assert cfg.qdrant_host == "explicit-host"+ assert cfg.qdrant_port == 5555+++def test_mem0_config_defaults_read_env(monkeypatch: pytest.MonkeyPatch) -> None:+ """Mem0Config (backends.mem0) should resolve env vars via default_factory."""+ from headroom.memory.backends.mem0 import Mem0Config++ monkeypatch.setenv("HEADROOM_QDRANT_URL", "https://tenant.qdrant.io")+ monkeypatch.setenv("HEADROOM_QDRANT_API_KEY", "k")++ cfg = Mem0Config()+ assert cfg.qdrant_url == "https://tenant.qdrant.io"+ assert cfg.qdrant_api_key == "k"+++def test_proxy_memory_config_defaults_read_env(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from headroom.proxy.memory_handler import MemoryConfig++ monkeypatch.setenv("HEADROOM_QDRANT_HOST", "proxy.qdrant")+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "8888")++ cfg = MemoryConfig()+ assert cfg.qdrant_host == "proxy.qdrant"+ assert cfg.qdrant_port == 8888+++def test_proxy_config_defaults_read_env(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from headroom.proxy.models import ProxyConfig++ monkeypatch.setenv("HEADROOM_QDRANT_URL", "https://shared.qdrant")+ cfg = ProxyConfig()+ assert cfg.memory_qdrant_url == "https://shared.qdrant"+++# =============================================================================+# Memory.easy public API+# =============================================================================+++def test_memory_easy_picks_up_env(monkeypatch: pytest.MonkeyPatch) -> None:+ """Memory() should pick up env vars for qdrant-neo4j backend kwargs."""+ from headroom.memory.easy import Memory++ monkeypatch.setenv("HEADROOM_QDRANT_URL", "https://hosted.qdrant.io:6333")+ monkeypatch.setenv("HEADROOM_QDRANT_API_KEY", "xoxp-1234")++ # backend="local" never touches qdrant, so we can instantiate without Docker.+ # We only verify the stored Qdrant settings, not the backend initialization.+ mem = Memory(backend="local")+ assert mem._qdrant_url == "https://hosted.qdrant.io:6333"+ assert mem._qdrant_api_key == "xoxp-1234"+++def test_memory_easy_explicit_args_override_env(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from headroom.memory.easy import Memory++ monkeypatch.setenv("HEADROOM_QDRANT_HOST", "env-host")+ monkeypatch.setenv("HEADROOM_QDRANT_PORT", "1234")++ mem = Memory(backend="local", qdrant_host="explicit", qdrant_port=9999)+ assert mem._qdrant_host == "explicit"+ assert mem._qdrant_port == 9999+++def test_memory_easy_defaults_when_no_env() -> None:+ from headroom.memory.easy import Memory++ mem = Memory(backend="local")+ assert mem._qdrant_host == "localhost"+ assert mem._qdrant_port == 6333+ assert mem._qdrant_url is None+ assert mem._qdrant_api_key is None+++# =============================================================================+# Module-level public API+# =============================================================================+++def test_module_exports_readers() -> None:+ """Sanity check: helper functions are importable from the module."""+ assert callable(qdrant_env.qdrant_env_host)+ assert callable(qdrant_env.qdrant_env_port)+ assert callable(qdrant_env.qdrant_env_url)+ assert callable(qdrant_env.qdrant_env_api_key)+ assert callable(qdrant_env.build_qdrant_client_kwargs)