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.

refactor(memory): remove the unused memory budget manager (#4099)

Tejas Choprae7ac6ca6f818
diff --git a/headroom/memory/budget.py b/headroom/memory/budget.py
deleted file mode 100644
index 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.py
deleted file mode 100644
index 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