mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
co-authored by
Claude Opus 5.5
parent
a9815bbb5f
commit
a89ea78e25
@@ -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()))
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user