Skip to content

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.

feat(memory): resolve Qdrant connection from HEADROOM_QDRANT_* env vars (#31)

ipapapad3c37d709841
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.0
LIKE 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 now
reports `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.py
index 738d7d8e4..4b587ef98 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -2,6 +2,7 @@
import os
import sys
+from typing import Any
import click
@@ -190,6 +191,37 @@ from .main import main
default=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.py
index d972b69ba..c086ef012 100644
--- a/headroom/memory/backends/direct_mem0.py
+++ b/headroom/memory/backends/direct_mem0.py
@@ -51,10 +51,11 @@ import asyncio
import hashlib
import logging
import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any
+from headroom.memory import qdrant_env
from headroom.memory.models import Memory
from 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 settings
embedder_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.py
index 54a2c3821..7aefce0f6 100644
--- a/headroom/memory/backends/mem0.py
+++ b/headroom/memory/backends/mem0.py
@@ -13,10 +13,11 @@ from __future__ import annotations
import asyncio
import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any
+from headroom.memory import qdrant_env
from headroom.memory.models import Memory
from headroom.memory.ports import MemoryFilter, VectorFilter, VectorSearchResult
@@ -25,14 +26,24 @@ from headroom.memory.ports import MemoryFilter, VectorFilter, VectorSearchResult
class 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 settings
llm_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.py
index 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 needed
memory = Memory()
await memory.save("User likes Python", user_id="alice")
- results = await memory.search("programming", user_id="alice")
# With custom database path
memory = Memory(db_path="./my_app.db")
- # Production mode with Docker services
+ # Production mode with local Docker services
memory = 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 = backend
self._backend: Any = None
self._initialized = False
@@ -113,9 +133,16 @@ class Memory:
db_path = default_db
self._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_uri
self._neo4j_user = neo4j_user
self._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.py
new file mode 100644
index 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 kwargs
diff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.py
index ba7086d28..b57dc50d0 100644
--- a/headroom/proxy/memory_handler.py
+++ b/headroom/proxy/memory_handler.py
@@ -33,6 +33,8 @@ from datetime import datetime, timezone
from pathlib import Path
from 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
@dataclass
class 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 = False
backend: Literal["local", "qdrant-neo4j"] = "local"
@@ -71,9 +78,11 @@ class MemoryConfig:
# Native memory tool (Anthropic's built-in memory_20250818)
use_native_tool: bool = False
native_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.py
index 43ffa26f2..89b58d93a 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -10,6 +10,7 @@ from dataclasses import dataclass, field
from datetime import datetime
from typing import Any, Literal
+from headroom.memory import qdrant_env
from headroom.providers.registry import ProviderApiOverrides
# =============================================================================
@@ -200,8 +201,11 @@ class ProxyConfig:
memory_inject_context: bool = True
memory_top_k: int = 10
memory_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.py
index 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.py
new file mode 100644
index 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)