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

## Description

`headroom/memory/budget.py` (`MemoryBudgetManager`, `BudgetConfig`,
`BudgetReport`) ranks, prunes and merges exported memories against a
token budget. It came in with the agent memory writers in 0fd6dfca, and
product code has never imported it. This PR removes it and its tests.

It meets none of the public-API criteria:
- it has no `__all__`;
- it is not re-exported from `headroom.memory` or any lazy map;
- it is not documented;
- no consumer repo imports it.

Evidence: `grep -rnE
'memory\.budget|MemoryBudgetManager|BudgetConfig|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`.

Refs #4136

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Delete `headroom/memory/budget.py` (302 lines).
- Delete `tests/test_memory/test_budget.py` (215 lines).

## Testing

- [x] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_memory
===================== 600 passed, 1000 warnings in 54.16s ======================
$ grep -rnE 'memory\.budget|MemoryBudgetManager|BudgetConfig|BudgetReport' headroom tests
(no output)
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, repo .venv, branch checkout at
a89ea78e (base a9815bbb), temp HOME / HEADROOM_WORKSPACE_DIR /
CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran a direct script with DeprecationWarning promoted to an error. It
resolves every name in `headroom.memory.__all__`, including the lazy
exports, and checks that the budget module is gone.
  - Ran the full `tests/test_memory` package.
- Observed result:
  - Both proxy requests return HTTP 200 with savings.
- All 48 `headroom.memory` exports resolve, and `headroom.memory.budget`
no longer exists.
  - 600 passed.
- Not tested: No runtime path imported the module.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-memory-budget @ a89ea78e
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -u -W error::DeprecationWarning -c "<getattr(headroom.memory, n) for n in __all__; find_spec('headroom.memory.budget')>"
headroom.memory: resolved all 48 names in __all__
headroom.memory.budget spec -> None
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; dead-code removal.
- Stable/default behavior changed: No.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- This is a pure deletion of two whole files, so ruff and mypy have
nothing to check.
- The agent memory writers that this module used are deprecated, not
deleted, in a separate PR, because they are listed in the package
`__all__`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Tejas Chopra
2026-10-10 08:58:59 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 5c72d824f4
commit e7ac6ca6f8
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