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
Cross-agent memory: OpenAI + Gemini handlers, project-scoped DB, auto user_id
chopratejascd1f0a2b9acd
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex 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.pyindex 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 defaultcache_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.pyindex 212d4668f..137abcb49 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -9,6 +9,7 @@ import asyncioimport copyimport jsonimport logging+import osimport timefrom datetime import datetimefrom 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 = Noneif 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 = Falsediff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.pyindex 2ec0d6522..1f26bc46f 100644--- a/headroom/proxy/handlers/gemini.py+++ b/headroom/proxy/handlers/gemini.py@@ -7,6 +7,7 @@ from __future__ import annotationsimport jsonimport logging+import osimport timefrom 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 optimizedif 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.pyindex 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 limitingif 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_messagesif tools is not None:body["tools"] = tools@@ -603,6 +638,7 @@ class OpenAIHandlerMixin:total_input_tokens = optimized_tokens # fallbackoutput_tokens = 0cache_read_tokens = 0+ resp_json = Nonetry: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}")+# Cacheif self.cache and response.status_code == 200:await self.cache.set(diff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.pyindex 2c3b10600..332185113 100644--- a/headroom/proxy/memory_handler.py+++ b/headroom/proxy/memory_handler.py@@ -133,12 +133,43 @@ class MemoryHandler:returnif 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.pyindex fc581f0dc..c9a837ac7 100644--- a/headroom/proxy/models.py+++ b/headroom/proxy/models.py@@ -173,7 +173,7 @@ class ProxyConfig:# Memory Systemmemory_enabled: bool = Falsememory_backend: Literal["local", "qdrant-neo4j"] = "local"- memory_db_path: str = "headroom_memory.db"+ memory_db_path: str = "" # Empty = auto: {cwd}/.headroom/memory.dbmemory_inject_tools: bool = Truetraffic_learning_enabled: bool = Falsetraffic_learning_agent_type: str = "unknown" # Which agent is being wrappeddiff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 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 = Noneif 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,