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.

Cross-agent memory: OpenAI + Gemini handlers, project-scoped DB, auto user_id

chopratejascd1f0a2b9acd
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index 43ab571c8..86a3d59e8 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -82,8 +82,8 @@ from .main import main
)
@click.option(
"--memory-db-path",
- default="headroom_memory.db",
- help="Path to memory database file (default: headroom_memory.db)",
+ default="",
+ help="Path to memory database file (default: {cwd}/.headroom/memory.db)",
)
@click.option("--no-memory-tools", is_flag=True, help="Disable automatic memory tool injection")
@click.option(
diff --git a/headroom/memory/backends/local.py b/headroom/memory/backends/local.py
index c79f0739c..85879e5b7 100644
--- a/headroom/memory/backends/local.py
+++ b/headroom/memory/backends/local.py
@@ -52,10 +52,13 @@ class LocalBackendConfig:
db_path: str = "memory.db"
graph_db_path: str | None = None # Derived from db_path if not specified
+ embedder_backend: str = "local" # "local" (sentence-transformers), "openai", "ollama"
embedder_model: str = field(default_factory=lambda: ML_MODEL_DEFAULTS.sentence_transformer)
vector_dimension: int = field(
default_factory=lambda: ML_MODEL_DEFAULTS.sentence_transformer_dim
)
+ openai_api_key: str | None = None # Required when embedder_backend="openai"
+ ollama_base_url: str = "http://localhost:11434" # For embedder_backend="ollama"
graph_persist: bool = True # Use SQLiteGraphStore (bounded, persistent)
graph_cache_size_kb: int = 8192 # 8MB default
cache_enabled: bool = True
@@ -123,11 +126,25 @@ class LocalBackend:
"""
if not self._initialized:
from headroom.memory import HierarchicalMemory, MemoryConfig
+ from headroom.memory.config import EmbedderBackend
+
+ # Map string embedder_backend to enum
+ embedder_backend_map = {
+ "local": EmbedderBackend.LOCAL,
+ "openai": EmbedderBackend.OPENAI,
+ "ollama": EmbedderBackend.OLLAMA,
+ }
+ embedder_backend = embedder_backend_map.get(
+ self._config.embedder_backend, EmbedderBackend.LOCAL
+ )
mem_config = MemoryConfig(
db_path=Path(self._config.db_path),
+ embedder_backend=embedder_backend,
embedder_model=self._config.embedder_model,
vector_dimension=self._config.vector_dimension,
+ openai_api_key=self._config.openai_api_key,
+ ollama_base_url=self._config.ollama_base_url,
cache_enabled=self._config.cache_enabled,
cache_max_size=self._config.cache_max_size,
)
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 212d4668f..137abcb49 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -9,6 +9,7 @@ import asyncio
import copy
import json
import logging
+import os
import time
from datetime import datetime
from pathlib import Path
@@ -408,7 +409,10 @@ class AnthropicHandlerMixin:
# Memory: Get user ID when memory is enabled (fallback to "default" for simple DevEx)
memory_user_id: str | None = None
if self.memory_handler:
- memory_user_id = headers.get("x-headroom-user-id", "default")
+ memory_user_id = headers.get(
+ "x-headroom-user-id",
+ os.environ.get("USER", os.environ.get("USERNAME", "default")),
+ )
# Check cache (non-streaming only)
cache_hit = False
diff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.py
index 2ec0d6522..1f26bc46f 100644
--- a/headroom/proxy/handlers/gemini.py
+++ b/headroom/proxy/handlers/gemini.py
@@ -7,6 +7,7 @@ from __future__ import annotations
import json
import logging
+import os
import time
from typing import TYPE_CHECKING
@@ -170,6 +171,14 @@ class GeminiHandlerMixin:
headers.pop("content-length", None)
tags = self._extract_tags(headers)
+ # Memory: Get user ID when memory is enabled
+ memory_user_id: str | None = None
+ if self.memory_handler:
+ memory_user_id = headers.get(
+ "x-headroom-user-id",
+ os.environ.get("USER", os.environ.get("USERNAME", "default")),
+ )
+
# Rate limiting (use Gemini API key)
if self.rate_limiter:
rate_key = headers.get("x-goog-api-key", "default")[:20]
@@ -280,6 +289,26 @@ class GeminiHandlerMixin:
# Query Echo: disabled — hurts prefix caching in long conversations.
+ # Memory: inject context for Gemini requests
+ if self.memory_handler and memory_user_id:
+ try:
+ if self.memory_handler.config.inject_context:
+ memory_context = await self.memory_handler.search_and_format_context(
+ memory_user_id, optimized_messages
+ )
+ if memory_context:
+ # Prepend as system message (will become systemInstruction in Gemini format)
+ optimized_messages = [
+ {"role": "system", "content": memory_context},
+ *optimized_messages,
+ ]
+ logger.info(
+ f"[{request_id}] Memory: Injected {len(memory_context)} chars "
+ f"of context for user {memory_user_id} (gemini)"
+ )
+ except Exception as e:
+ logger.warning(f"[{request_id}] Memory injection failed (gemini): {e}")
+
# Convert back to Gemini format if optimized
if optimized_messages != messages:
optimized_contents, optimized_system = self._messages_to_gemini_contents(
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index ee20da2bd..c4c2b4745 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -208,6 +208,14 @@ class OpenAIHandlerMixin:
headers.pop("content-length", None)
tags = self._extract_tags(headers)
+ # Memory: Get user ID when memory is enabled
+ memory_user_id: str | None = None
+ if self.memory_handler:
+ memory_user_id = headers.get(
+ "x-headroom-user-id",
+ os.environ.get("USER", os.environ.get("USERNAME", "default")),
+ )
+
# Rate limiting
if self.rate_limiter:
rate_key = headers.get("authorization", "default")[:20]
@@ -416,6 +424,33 @@ class OpenAIHandlerMixin:
"to preserve cache stability (openai)"
)
+ # Memory: inject context and tools for OpenAI requests
+ if self.memory_handler and memory_user_id:
+ try:
+ # Inject memory context (search similar memories, add as system message)
+ if self.memory_handler.config.inject_context:
+ memory_context = await self.memory_handler.search_and_format_context(
+ memory_user_id, optimized_messages
+ )
+ if memory_context:
+ # Prepend as system message for OpenAI format
+ optimized_messages = [
+ {"role": "system", "content": memory_context},
+ *optimized_messages,
+ ]
+ logger.info(
+ f"[{request_id}] Memory: Injected {len(memory_context)} chars "
+ f"of context for user {memory_user_id}"
+ )
+
+ # Inject memory tools
+ if self.memory_handler.config.inject_tools:
+ tools, mem_tools_injected = self.memory_handler.inject_tools(tools, "openai")
+ if mem_tools_injected:
+ logger.info(f"[{request_id}] Memory: Injected memory tools (openai)")
+ except Exception as e:
+ logger.warning(f"[{request_id}] Memory injection failed: {e}")
+
body["messages"] = optimized_messages
if tools is not None:
body["tools"] = tools
@@ -603,6 +638,7 @@ class OpenAIHandlerMixin:
total_input_tokens = optimized_tokens # fallback
output_tokens = 0
cache_read_tokens = 0
+ resp_json = None
try:
resp_json = response.json()
usage = resp_json.get("usage", {})
@@ -636,6 +672,25 @@ class OpenAIHandlerMixin:
uncached_tokens=uncached_input_tokens,
)
+ # Memory: handle memory tool calls in OpenAI response
+ if (
+ self.memory_handler
+ and memory_user_id
+ and resp_json
+ and response.status_code == 200
+ and self.memory_handler.has_memory_tool_calls(resp_json, "openai")
+ ):
+ try:
+ tool_results = await self.memory_handler.handle_memory_tool_calls(
+ resp_json, memory_user_id, "openai"
+ )
+ logger.info(
+ f"[{request_id}] Memory: Handled {len(tool_results)} "
+ f"tool call(s) for user {memory_user_id}"
+ )
+ except Exception as e:
+ logger.warning(f"[{request_id}] Memory tool handling failed: {e}")
+
# Cache
if self.cache and response.status_code == 200:
await self.cache.set(
diff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.py
index 2c3b10600..332185113 100644
--- a/headroom/proxy/memory_handler.py
+++ b/headroom/proxy/memory_handler.py
@@ -133,12 +133,43 @@ class MemoryHandler:
return
if self.config.backend == "local":
+ import os
+
from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
- backend_config = LocalBackendConfig(db_path=self.config.db_path)
+ # Auto-detect embedder: prefer OpenAI API (no torch/sentence-transformers needed)
+ # if OPENAI_API_KEY is available, else fall back to local embedder
+ embedder_backend = "local"
+ embedder_model = "all-MiniLM-L6-v2"
+ vector_dimension = 384
+ openai_api_key = os.environ.get("OPENAI_API_KEY")
+
+ if openai_api_key:
+ # Check if sentence-transformers is actually available
+ try:
+ import sentence_transformers # noqa: F401
+ except ImportError:
+ # sentence-transformers not installed — use OpenAI embeddings
+ embedder_backend = "openai"
+ embedder_model = "text-embedding-3-small"
+ vector_dimension = 1536
+ logger.info(
+ "Memory: Using OpenAI embeddings (sentence-transformers not available)"
+ )
+
+ backend_config = LocalBackendConfig(
+ db_path=self.config.db_path,
+ embedder_backend=embedder_backend,
+ embedder_model=embedder_model,
+ vector_dimension=vector_dimension,
+ openai_api_key=openai_api_key if embedder_backend == "openai" else None,
+ )
self._backend = LocalBackend(backend_config)
await self._backend._ensure_initialized()
- logger.info(f"Memory: Initialized LocalBackend at {self.config.db_path}")
+ logger.info(
+ f"Memory: Initialized LocalBackend at {self.config.db_path} "
+ f"(embedder: {embedder_backend})"
+ )
elif self.config.backend == "qdrant-neo4j":
try:
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
index fc581f0dc..c9a837ac7 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -173,7 +173,7 @@ class ProxyConfig:
# Memory System
memory_enabled: bool = False
memory_backend: Literal["local", "qdrant-neo4j"] = "local"
- memory_db_path: str = "headroom_memory.db"
+ memory_db_path: str = "" # Empty = auto: {cwd}/.headroom/memory.db
memory_inject_tools: bool = True
traffic_learning_enabled: bool = False
traffic_learning_agent_type: str = "unknown" # Which agent is being wrapped
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 1767a480d..fca1ce04a 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -422,10 +422,18 @@ class HeadroomProxy(
# Memory Handler (persistent user memory)
self.memory_handler: MemoryHandler | None = None
if config.memory_enabled:
+ # Resolve memory DB path: empty → project-scoped default
+ _mem_db_path = config.memory_db_path
+ if not _mem_db_path:
+ _mem_dir = Path.cwd() / ".headroom"
+ _mem_dir.mkdir(parents=True, exist_ok=True)
+ _mem_db_path = str(_mem_dir / "memory.db")
+ logger.info(f"Memory: Project-scoped DB at {_mem_db_path}")
+
memory_config = MemoryConfig(
enabled=True,
backend=config.memory_backend,
- db_path=config.memory_db_path,
+ db_path=_mem_db_path,
inject_tools=config.memory_inject_tools,
use_native_tool=config.memory_use_native_tool,
inject_context=config.memory_inject_context,