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
refactor(memory): remove the unused memory budget manager (#4099)
Tejas Choprae7ac6ca6f818
diff --git a/headroom/memory/budget.py b/headroom/memory/budget.pydeleted file mode 100644index a78d55a58..000000000--- a/headroom/memory/budget.py+++ /dev/null@@ -1,302 +0,0 @@-"""Memory file budget manager — token-optimized memory file maintenance.--Manages the token budget for agent memory files:-- Ranks memories by importance × recency × access frequency-- Prunes memories that fall below budget threshold-- Detects stale memories referencing deleted/renamed entities-- Merges similar memories to save tokens--This is Headroom's superpower applied to itself — the proxy that optimizes-LLM context also optimizes its own memory files for minimum token consumption.-"""--from __future__ import annotations--import logging-import re-import subprocess-import time-from dataclasses import dataclass, field-from pathlib import Path--from headroom._subprocess import run-from headroom.memory.writers.base import MemoryEntry, _estimate_tokens--logger = logging.getLogger(__name__)---def _jaccard(words_a: set[str], words_b: set[str]) -> float:- """Jaccard similarity between two word sets.-- Operates on already-tokenized sets so callers scanning many pairs can- tokenize each document once instead of per comparison.- """- if not words_a or not words_b:- return 0.0- intersection = len(words_a & words_b)- union = len(words_a) + len(words_b) - intersection- return intersection / union---@dataclass-class BudgetConfig:- """Configuration for memory budget management."""-- # Token budgets per agent type- agent_budgets: dict[str, int] = field(- default_factory=lambda: {- "claude": 2000, # Claude Code: 200-line MEMORY.md limit- "cursor": 3000, # Cursor: .mdc rules loaded on match- "codex": 3000, # Codex: AGENTS.md merged- "aider": 2000, # Aider: read files- "gemini": 3000, # Gemini: GEMINI.md- "generic": 3000, # Default- }- )-- # Staleness detection- staleness_decay_rate: float = 0.1 # Importance decays ~10% per day- staleness_min_importance: float = 0.15 # Below this = prunable- staleness_check_git: bool = True # Check git for deleted files-- # Deduplication- similarity_merge_threshold: float = 0.85 # Cosine sim above = merge---@dataclass-class BudgetReport:- """Report from a budget optimization pass."""-- total_memories: int = 0- kept: int = 0- pruned_staleness: int = 0- pruned_budget: int = 0- merged: int = 0- tokens_before: int = 0- tokens_after: int = 0-- @property- def tokens_saved(self) -> int:- return self.tokens_before - self.tokens_after---class MemoryBudgetManager:- """Manages token budgets for agent memory files.-- Responsible for deciding which memories to keep, prune, or merge- to stay within token budgets while maximizing information density.- """-- def __init__(- self,- project_path: Path | None = None,- config: BudgetConfig | None = None,- ) -> None:- self._project_path = project_path or Path.cwd()- self._config = config or BudgetConfig()- self._git_files_cache: set[str] | None = None-- def optimize(- self,- memories: list[MemoryEntry],- agent_type: str = "generic",- ) -> tuple[list[MemoryEntry], BudgetReport]:- """Optimize a set of memories for an agent's token budget.-- Returns the optimized list and a report of what changed.-- Args:- memories: All candidate memories.- agent_type: Target agent type (determines budget).-- Returns:- Tuple of (optimized memories, report).- """- report = BudgetReport(total_memories=len(memories))- report.tokens_before = sum(_estimate_tokens(m.content) for m in memories)-- budget = self._config.agent_budgets.get(agent_type, 3000)-- # Step 1: Apply temporal decay to importance scores- decayed = self._apply_decay(memories)-- # Step 2: Detect and flag stale memories- fresh, stale = self._detect_staleness(decayed)- report.pruned_staleness = len(stale)-- # Step 3: Merge similar memories- merged = self._merge_similar(fresh)- report.merged = len(fresh) - len(merged)-- # Step 4: Rank by score and apply budget- ranked = sorted(merged, key=lambda m: m.score, reverse=True)- budgeted: list[MemoryEntry] = []- tokens_used = 0- for m in ranked:- entry_tokens = _estimate_tokens(m.content) + 10- if tokens_used + entry_tokens > budget:- report.pruned_budget += 1- continue- tokens_used += entry_tokens- budgeted.append(m)-- report.kept = len(budgeted)- report.tokens_after = tokens_used-- return budgeted, report-- def _apply_decay(self, memories: list[MemoryEntry]) -> list[MemoryEntry]:- """Apply temporal decay to importance scores."""- now = time.time()- rate = self._config.staleness_decay_rate- min_importance = self._config.staleness_min_importance-- result: list[MemoryEntry] = []- for m in memories:- # Clamp to non-negative: a future created_at (clock skew) otherwise- # makes exp(-rate × negative) > 1 and inflates importance above 1.0,- # so a future-dated memory outranks everything. Treat it as new (no- # decay), matching memory_rank_policy.memory_recency_factor.- age_days = max(0.0, (now - m.created_at) / 86400)- # Exponential decay: importance × e^(-rate × age)- import math-- decayed_importance = m.importance * math.exp(-rate * age_days)-- # Access count counteracts decay- if m.access_count > 0:- access_boost = min(0.3, m.access_count * 0.05)- decayed_importance = min(1.0, decayed_importance + access_boost)-- if decayed_importance >= min_importance:- m.importance = decayed_importance- result.append(m)-- return result-- def _detect_staleness(- self,- memories: list[MemoryEntry],- ) -> tuple[list[MemoryEntry], list[MemoryEntry]]:- """Separate fresh memories from stale ones.-- A memory is stale if it references files/paths that no longer exist.- Uses git ls-files when available, falls back to filesystem checks.- """- git_files = self._get_git_files() if self._config.staleness_check_git else set()-- fresh: list[MemoryEntry] = []- stale: list[MemoryEntry] = []-- for m in memories:- if self._is_stale(m, git_files):- stale.append(m)- else:- fresh.append(m)-- return fresh, stale-- def _is_stale(self, memory: MemoryEntry, git_files: set[str]) -> bool:- """Check if a memory references entities that no longer exist."""- # Check entity_refs for file paths- for ref in memory.entity_refs:- if ref.startswith("/") or ref.startswith("./"):- # Absolute or relative path — check if file exists- if ref.startswith("./"):- ref = ref[2:]- # Normalize to relative- try:- rel = str(Path(ref).relative_to(self._project_path))- except ValueError:- rel = ref-- if rel not in git_files and not Path(ref).exists():- return True-- # Check content for backtick-quoted file paths- path_refs = re.findall(r"`([/\w.]+(?:/[\w.]+)+)`", memory.content)- for path_ref in path_refs:- # Only flag if it looks like a full path and is missing- if "/" in path_ref:- try:- rel = str(Path(path_ref).relative_to(self._project_path))- except ValueError:- rel = path_ref- if rel not in git_files and not Path(path_ref).exists():- return True-- return False-- def _get_git_files(self) -> set[str]:- """Get set of tracked files in the git repo."""- if self._git_files_cache is not None:- return self._git_files_cache-- try:- result = run(- ["git", "ls-files"],- capture_output=True,- text=True,- cwd=self._project_path,- timeout=5,- )- if result.returncode == 0:- self._git_files_cache = set(result.stdout.strip().split("\n"))- else:- self._git_files_cache = set()- except (subprocess.TimeoutExpired, FileNotFoundError):- self._git_files_cache = set()-- return self._git_files_cache-- def _merge_similar(self, memories: list[MemoryEntry]) -> list[MemoryEntry]:- """Merge memories with very similar content.-- Uses simple text overlap heuristic (no embeddings required).- """- if len(memories) <= 1:- return memories-- # Precompute each memory's word set once. The pairwise scan below is- # O(n^2); recomputing set(content.lower().split()) inside every- # _text_similarity call re-tokenized the same content O(n) times. With- # the sets cached, each pair is a plain set intersection/union.- word_sets = [set(m.content.lower().split()) for m in memories]- threshold = self._config.similarity_merge_threshold-- merged: list[MemoryEntry] = []- used: set[int] = set()-- for i, m1 in enumerate(memories):- if i in used:- continue-- words_i = word_sets[i]-- # Find similar memories- group = [m1]- for j in range(i + 1, len(memories)):- if j in used:- continue- if _jaccard(words_i, word_sets[j]) > threshold:- group.append(memories[j])- used.add(j)-- if len(group) == 1:- merged.append(m1)- else:- # Merge: keep highest-importance content, combine entity refs- best = max(group, key=lambda m: m.importance)- all_entities = set()- for m in group:- all_entities.update(m.entity_refs)- best.entity_refs = list(all_entities)- best.access_count = max(m.access_count for m in group)- merged.append(best)-- return merged-- @staticmethod- def _text_similarity(a: str, b: str) -> float:- """Simple Jaccard similarity on word sets."""- return _jaccard(set(a.lower().split()), set(b.lower().split()))diff --git a/tests/test_memory/test_budget.py b/tests/test_memory/test_budget.pydeleted file mode 100644index 599cf1306..000000000--- a/tests/test_memory/test_budget.py+++ /dev/null@@ -1,215 +0,0 @@-"""Tests for the Memory Budget Manager."""--from __future__ import annotations--import time-from pathlib import Path--import pytest--from headroom.memory.budget import (- BudgetConfig,- MemoryBudgetManager,-)-from headroom.memory.writers.base import MemoryEntry---def _make_entry(- content: str = "test memory",- importance: float = 0.5,- age_days: float = 0,- access_count: int = 0,- entity_refs: list[str] | None = None,- category: str = "",-) -> MemoryEntry:- return MemoryEntry(- content=content,- importance=importance,- created_at=time.time() - age_days * 86400,- access_count=access_count,- entity_refs=entity_refs or [],- category=category,- )---class TestBudgetManager:- @pytest.fixture- def manager(self, tmp_path: Path) -> MemoryBudgetManager:- config = BudgetConfig(staleness_check_git=False) # No git for unit tests- return MemoryBudgetManager(project_path=tmp_path, config=config)-- def test_basic_optimize(self, manager: MemoryBudgetManager):- entries = [_make_entry(f"Memory {i}", importance=0.5 + i * 0.1) for i in range(5)]- optimized, report = manager.optimize(entries, "generic")-- assert report.total_memories == 5- assert report.kept > 0- assert report.tokens_after <= 3000 # Default budget-- def test_budget_limits(self, manager: MemoryBudgetManager):- # Create many entries that exceed budget- entries = [- _make_entry(f"A long memory content string number {i} " * 10, importance=0.8)- for i in range(50)- ]- optimized, report = manager.optimize(entries, "claude") # 2000 token budget-- assert report.pruned_budget > 0- assert report.kept < 50-- def test_temporal_decay(self, manager: MemoryBudgetManager):- old = _make_entry("Old memory", importance=0.5, age_days=30)- new = _make_entry("New memory", importance=0.5, age_days=0)-- optimized, report = manager.optimize([old, new], "generic")-- # New should rank higher- if len(optimized) >= 2:- assert optimized[0].content == "New memory"-- def test_decay_does_not_inflate_future_timestamps(self, manager: MemoryBudgetManager):- # A future created_at (clock skew) made exp(-rate × negative) > 1, so the- # decayed importance rose above the original (and above 1.0) and the- # future memory outranked a fresh, genuinely-important one. Age is now- # clamped to >= 0, so a future memory decays like a brand-new one.- future = _make_entry("Future", importance=0.5, age_days=-30) # created 30d ahead- decayed = manager._apply_decay([future])-- assert decayed # survives the min-importance filter- assert decayed[0].importance <= 0.5 # never inflated above the original- assert decayed[0].importance <= 1.0-- def test_access_count_boost(self, manager: MemoryBudgetManager):- unused = _make_entry("Unused", importance=0.5, age_days=5, access_count=0)- used = _make_entry("Heavily used", importance=0.5, age_days=5, access_count=10)-- optimized, report = manager.optimize([unused, used], "generic")-- if len(optimized) >= 2:- # Used memory should have higher importance after decay+boost- assert optimized[0].content == "Heavily used"-- def test_merge_similar(self, manager: MemoryBudgetManager):- entries = [- _make_entry(- "Use source .venv/bin/activate && pytest for running tests", importance=0.5- ),- _make_entry(- "Use source .venv/bin/activate && pytest for running tests", importance=0.8- ),- _make_entry("Something completely different about architecture", importance=0.6),- ]- optimized, report = manager.optimize(entries, "generic")-- # The two identical ones should be merged- assert report.merged >= 1- assert report.kept <= 2-- def test_merge_groups_transitively_like_pairwise_scan(self, manager: MemoryBudgetManager):- """The precomputed word-set scan must merge exactly the pairs the- original per-pair Jaccard scan did: high-overlap entries collapse to- the highest-importance representative, distinct entries survive."""- shared = "alpha beta gamma delta epsilon zeta eta theta iota kappa"- entries = [- _make_entry(shared, importance=0.3),- _make_entry(shared, importance=0.9), # highest -> kept representative- _make_entry(shared, importance=0.5),- _make_entry("wholly unrelated content about something else", importance=0.6),- ]- merged = manager._merge_similar(list(entries))-- # Three identical-content entries collapse to one; the unrelated one stays.- assert len(merged) == 2- kept_shared = [m for m in merged if m.content == shared]- assert len(kept_shared) == 1- # The surviving representative is the highest-importance of the group.- assert kept_shared[0].importance == 0.9-- def test_text_similarity_matches_explicit_jaccard(self, manager: MemoryBudgetManager):- a = "the quick brown fox jumps"- b = "the quick brown dog runs"- wa, wb = set(a.split()), set(b.split())- expected = len(wa & wb) / len(wa | wb)- assert manager._text_similarity(a, b) == pytest.approx(expected)- # Empty side yields 0.0, not a ZeroDivisionError.- assert manager._text_similarity("", "anything") == 0.0-- def test_very_old_pruned(self, manager: MemoryBudgetManager):- """Test that very old, low-importance memories get pruned by decay."""- entries = [- _make_entry("Ancient memory", importance=0.2, age_days=100),- _make_entry("Recent memory", importance=0.5, age_days=0),- ]- optimized, report = manager.optimize(entries, "generic")-- contents = [m.content for m in optimized]- assert "Recent memory" in contents- # Ancient memory with 0.2 importance after 100 days of decay should be below threshold-- def test_report_tokens(self, manager: MemoryBudgetManager):- # Use entries large enough to trigger budget pruning- entries = [- _make_entry(f"A very long memory content entry {i} " * 30, importance=0.8)- for i in range(20)- ]- _, report = manager.optimize(entries, "claude") # 2000 token budget-- assert report.tokens_before > 0- assert report.pruned_budget > 0 # Should drop some due to budget- assert report.kept < 20---class TestStalenessDetection:- def test_stale_file_ref(self, tmp_path: Path):- """Test that memories referencing non-existent files are flagged stale."""- # Create a manager with git check disabled but file-exists check active- config = BudgetConfig(staleness_check_git=False)- manager = MemoryBudgetManager(project_path=tmp_path, config=config)-- # The entity_refs check uses Path.exists(), so non-existent paths flag stale- entries = [- _make_entry(- "File `/nonexistent/path/foo.py` has the auth logic",- importance=0.5,- entity_refs=["/nonexistent/path/foo.py"],- ),- _make_entry(- "Use pytest for tests",- importance=0.5,- ),- ]- # With git disabled, staleness only checks entity_refs via Path.exists()- optimized, report = manager.optimize(entries, "generic")-- assert report.pruned_staleness >= 1-- def test_fresh_file_kept(self, tmp_path: Path):- """Test that memories referencing existing files are kept."""- # Create the referenced file- (tmp_path / "real_file.py").write_text("# exists")-- config = BudgetConfig(staleness_check_git=False)- manager = MemoryBudgetManager(project_path=tmp_path, config=config)-- entries = [- _make_entry(- "Real file has important code",- importance=0.5,- entity_refs=[str(tmp_path / "real_file.py")],- ),- ]- optimized, report = manager.optimize(entries, "generic")-- assert report.pruned_staleness == 0- assert report.kept == 1---class TestBudgetConfig:- def test_default_budgets(self):- config = BudgetConfig()- assert config.agent_budgets["claude"] == 2000- assert config.agent_budgets["cursor"] == 3000-- def test_custom_budgets(self):- config = BudgetConfig(agent_budgets={"claude": 5000})- assert config.agent_budgets["claude"] == 5000