refactor(memory): remove the unused memory budget manager

headroom/memory/budget.py (MemoryBudgetManager, BudgetConfig, BudgetReport) was added in 0fd6dfca with the agent memory writers and nothing in product code has ever imported it. Remove it and its tests.

Evidence: grep for memory.budget, MemoryBudgetManager, BudgetConfig and BudgetReport across headroom, crates, plugins, sdk, docs, wiki, scripts, benchmarks, examples, e2e, .github, pyproject.toml, tests and the consumer repos finds only the module and tests/test_memory/test_budget.py. The module has no __all__, is not re-exported from headroom.memory and is not documented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Tejas Chopra
2026-10-09 17:19:24 -07:00
co-authored by Claude Opus 5.5
parent a9815bbb5f
commit a89ea78e25
2 changed files with 0 additions and 517 deletions
-302
View File
@@ -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()))
-215
View File
@@ -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