feat: add live traffic learning + cross-agent memory writers (--learn flag)

Live Traffic Learner extracts patterns from proxy traffic in real-time:
- Error→recovery patterns (tool fails → next success teaches right approach)
- Environment facts (working venv paths, test commands)
- User preference signals (corrections, repeated choices)

Agent-native memory writers export learned patterns to each agent's format:
- Claude Code: MEMORY.md + per-topic files
- Cursor: .cursor/rules/headroom-memory.mdc (YAML frontmatter)
- Codex: AGENTS.md
- Generic: plain markdown (Aider, Gemini, any agent)

Memory Budget Manager handles token-optimized memory files:
- Per-agent token budgets (2K Claude, 3K Cursor/Codex)
- Temporal decay, staleness detection (git + filesystem)
- Jaccard-similarity memory merging, dedup

Opt-in via --learn flag on proxy/wrap commands:
- headroom proxy --learn
- headroom wrap claude --learn
- --learn implies --memory; --no-learn overrides
- compress() API completely unaffected (pure function)
- Default behavior unchanged (no memory, no learning)
This commit is contained in:
Tejas Chopra
2026-03-20 15:36:06 -07:00
parent b5631cdf7e
commit 0fd6dfcadb
16 changed files with 2550 additions and 11 deletions
+19 -1
View File
@@ -81,6 +81,19 @@ from .main import main
default=10,
help="Number of memories to inject as context (default: 10)",
)
# Traffic Learning (live pattern extraction from proxy traffic)
@click.option(
"--learn",
is_flag=True,
help="Enable live traffic learning: extract error→recovery patterns, environment facts, "
"and user preferences from proxy traffic. Implies --memory. "
"Learned patterns are saved to agent-native memory files (MEMORY.md, .cursor/rules, AGENTS.md).",
)
@click.option(
"--no-learn",
is_flag=True,
help="Explicitly disable traffic learning even when --memory is set.",
)
# Backend configuration
@click.option(
"--backend",
@@ -144,6 +157,8 @@ def proxy(
no_memory_tools: bool,
no_memory_context: bool,
memory_top_k: int,
learn: bool,
no_learn: bool,
backend: str,
anyllm_provider: str,
openai_api_url: str | None,
@@ -210,11 +225,14 @@ def proxy(
intelligent_context_scoring=not no_intelligent_scoring,
intelligent_context_compress_first=not no_compress_first,
# Memory System (Multi-Provider with auto-detection)
memory_enabled=memory,
# --learn implies --memory (need backend for storing patterns)
memory_enabled=memory or (learn and not no_learn),
memory_db_path=memory_db_path,
memory_inject_tools=not no_memory_tools,
memory_inject_context=not no_memory_context,
memory_top_k=memory_top_k,
# Traffic Learning: only with --learn, never with --no-learn
traffic_learning_enabled=learn and not no_learn,
# Backend (Anthropic direct, Bedrock, LiteLLM, or any-llm)
backend=backend,
bedrock_region=bedrock_region or region,
+24 -10
View File
@@ -47,7 +47,7 @@ def _get_log_path() -> Path:
return log_dir / "proxy.log"
def _start_proxy(port: int) -> subprocess.Popen:
def _start_proxy(port: int, *, learn: bool = False) -> subprocess.Popen:
"""Start Headroom proxy as a background subprocess.
Logs are written to ~/.headroom/logs/proxy.log to avoid pipe buffer
@@ -61,6 +61,10 @@ def _start_proxy(port: int) -> subprocess.Popen:
if headroom_mode:
cmd.extend(["--mode", headroom_mode])
# Forward --learn flag to proxy subprocess
if learn:
cmd.append("--learn")
log_path = _get_log_path()
log_file = open(log_path, "a") # noqa: SIM115
@@ -217,7 +221,9 @@ def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:
return True
def _ensure_proxy(port: int, no_proxy: bool) -> subprocess.Popen | None:
def _ensure_proxy(
port: int, no_proxy: bool, *, learn: bool = False
) -> subprocess.Popen | None:
"""Start or verify proxy. Returns process handle if we started it."""
if not no_proxy:
if _check_proxy(port):
@@ -226,7 +232,7 @@ def _ensure_proxy(port: int, no_proxy: bool) -> subprocess.Popen | None:
else:
click.echo(f" Starting Headroom proxy on port {port}...")
try:
proc = _start_proxy(port)
proc = _start_proxy(port, learn=learn)
click.echo(f" Proxy ready on http://127.0.0.1:{port}")
return proc
except RuntimeError as e:
@@ -285,6 +291,8 @@ def _launch_tool(
no_proxy: bool,
tool_label: str,
env_vars_display: list[str],
*,
learn: bool = False,
) -> None:
"""Common logic: start proxy, launch tool, clean up."""
proxy_holder: list[subprocess.Popen | None] = [None]
@@ -300,7 +308,7 @@ def _launch_tool(
click.echo(" ╚═══════════════════════════════════════════════╝")
click.echo()
proxy_holder[0] = _ensure_proxy(port, no_proxy)
proxy_holder[0] = _ensure_proxy(port, no_proxy, learn=learn)
click.echo()
click.echo(f" Launching {tool_label} (API routed through Headroom)...")
@@ -348,9 +356,10 @@ def wrap() -> None:
@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and hook registration")
@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
@click.option("--learn", is_flag=True, help="Enable live traffic learning (patterns saved to MEMORY.md)")
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
@click.argument("claude_args", nargs=-1, type=click.UNPROCESSED)
def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args: tuple) -> None:
def claude(port: int, no_rtk: bool, no_proxy: bool, learn: bool, verbose: bool, claude_args: tuple) -> None:
"""Launch Claude Code through Headroom proxy.
\b
@@ -384,7 +393,7 @@ def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args:
click.echo(" ╚═══════════════════════════════════════════════╝")
click.echo()
proxy_holder[0] = _ensure_proxy(port, no_proxy)
proxy_holder[0] = _ensure_proxy(port, no_proxy, learn=learn)
if not no_rtk:
click.echo(" Setting up rtk...")
@@ -423,9 +432,10 @@ def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args:
@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and AGENTS.md injection")
@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
@click.option("--learn", is_flag=True, help="Enable live traffic learning (patterns saved to AGENTS.md)")
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
@click.argument("codex_args", nargs=-1, type=click.UNPROCESSED)
def codex(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, codex_args: tuple) -> None:
def codex(port: int, no_rtk: bool, no_proxy: bool, learn: bool, verbose: bool, codex_args: tuple) -> None:
"""Launch OpenAI Codex CLI through Headroom proxy.
\b
@@ -470,6 +480,7 @@ def codex(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, codex_args: tu
no_proxy=no_proxy,
tool_label="CODEX",
env_vars_display=[f"OPENAI_BASE_URL=http://127.0.0.1:{port}/v1"],
learn=learn,
)
@@ -482,9 +493,10 @@ def codex(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, codex_args: tu
@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and conventions injection")
@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
@click.option("--learn", is_flag=True, help="Enable live traffic learning")
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
@click.argument("aider_args", nargs=-1, type=click.UNPROCESSED)
def aider(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, aider_args: tuple) -> None:
def aider(port: int, no_rtk: bool, no_proxy: bool, learn: bool, verbose: bool, aider_args: tuple) -> None:
"""Launch aider through Headroom proxy.
\b
@@ -529,6 +541,7 @@ def aider(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, aider_args: tu
f"OPENAI_API_BASE=http://127.0.0.1:{port}/v1",
f"ANTHROPIC_BASE_URL=http://127.0.0.1:{port}",
],
learn=learn,
)
@@ -541,8 +554,9 @@ def aider(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, aider_args: tu
@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and .cursorrules injection")
@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
@click.option("--learn", is_flag=True, help="Enable live traffic learning (patterns saved to .cursor/rules/)")
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
def cursor(port: int, no_rtk: bool, no_proxy: bool, verbose: bool) -> None:
def cursor(port: int, no_rtk: bool, no_proxy: bool, learn: bool, verbose: bool) -> None:
"""Start Headroom proxy for use with Cursor.
\b
@@ -572,7 +586,7 @@ def cursor(port: int, no_rtk: bool, no_proxy: bool, verbose: bool) -> None:
click.echo(" ╚═══════════════════════════════════════════════╝")
click.echo()
proxy_holder[0] = _ensure_proxy(port, no_proxy)
proxy_holder[0] = _ensure_proxy(port, no_proxy, learn=learn)
# Setup rtk for Cursor (binary + .cursorrules instructions)
if not no_rtk:
+284
View File
@@ -0,0 +1,284 @@
"""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.memory.writers.base import MemoryEntry, _estimate_tokens
logger = logging.getLogger(__name__)
@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:
age_days = (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 = subprocess.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
merged: list[MemoryEntry] = []
used: set[int] = set()
for i, m1 in enumerate(memories):
if i in used:
continue
# Find similar memories
group = [m1]
for j, m2 in enumerate(memories[i + 1 :], start=i + 1):
if j in used:
continue
if (
self._text_similarity(m1.content, m2.content)
> self._config.similarity_merge_threshold
):
group.append(m2)
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."""
words_a = set(a.lower().split())
words_b = set(b.lower().split())
if not words_a or not words_b:
return 0.0
intersection = words_a & words_b
union = words_a | words_b
return len(intersection) / len(union)
+612
View File
@@ -0,0 +1,612 @@
"""Live Traffic Pattern Learner — extracts memories from proxy traffic.
Hooks into the proxy request/response pipeline to learn patterns without
any LLM calls. Rule-based extraction from traffic the proxy already sees:
- Error → Recovery patterns (tool fails → next success teaches right approach)
- Environment facts (commands that work/fail, paths, tool availability)
- Preference signals (repeated patterns, corrections)
- Architectural decisions (file references, dependency choices)
Usage:
learner = TrafficLearner(memory_backend)
await learner.on_request(messages, agent_type="claude")
await learner.on_response(response, messages, agent_type="claude")
The learner is designed to be zero-config and zero-latency: it processes
patterns in the background and never blocks the proxy pipeline.
"""
from __future__ import annotations
import asyncio
import hashlib
import logging
import re
import time
from dataclasses import dataclass, field
from enum import Enum
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from headroom.memory.backends.local import LocalBackend
logger = logging.getLogger(__name__)
# =============================================================================
# Pattern Categories
# =============================================================================
class PatternCategory(str, Enum):
"""Categories of patterns extracted from traffic."""
ERROR_RECOVERY = "error_recovery" # Tool failed → next call succeeded
ENVIRONMENT = "environment" # Working commands, paths, tool availability
PREFERENCE = "preference" # Repeated choices, corrections
ARCHITECTURE = "architecture" # File structure, dependencies, conventions
class AgentType(str, Enum):
"""Supported coding agent types."""
CLAUDE = "claude"
CURSOR = "cursor"
CODEX = "codex"
AIDER = "aider"
GEMINI = "gemini"
UNKNOWN = "unknown"
# =============================================================================
# Extracted Pattern Model
# =============================================================================
@dataclass
class ExtractedPattern:
"""A pattern extracted from proxy traffic."""
category: PatternCategory
content: str # Human-readable memory content
importance: float # 0.0 - 1.0
evidence_count: int = 1 # How many times this pattern was observed
entity_refs: list[str] = field(default_factory=list)
metadata: dict[str, Any] = field(default_factory=dict)
content_hash: str = ""
def __post_init__(self) -> None:
if not self.content_hash:
self.content_hash = hashlib.sha256(self.content.encode()).hexdigest()[:16]
# =============================================================================
# Error Classification (reused from learn/scanner.py patterns)
# =============================================================================
_ERROR_PATTERNS: list[tuple[re.Pattern[str], str]] = [
(
re.compile(r"No such file or directory|ENOENT|FileNotFoundError|does not exist", re.I),
"file_not_found",
),
(re.compile(r"ModuleNotFoundError|ImportError|No module named", re.I), "module_not_found"),
(re.compile(r"command not found", re.I), "command_not_found"),
(re.compile(r"Permission denied|EACCES|EPERM|auto-denied", re.I), "permission_denied"),
(re.compile(r"file is too large|too many lines|exceeds.*limit", re.I), "file_too_large"),
(re.compile(r"SyntaxError|IndentationError", re.I), "syntax_error"),
(re.compile(r"Traceback \(most recent|Exception:|Error:", re.I), "runtime_error"),
(re.compile(r"timed? ?out|TimeoutError|deadline exceeded", re.I), "timeout"),
(re.compile(r"exit code|non-zero|exited with", re.I), "exit_code"),
(re.compile(r"BUILD FAILED|compilation error|compile error", re.I), "build_failure"),
]
def _classify_error(content: str) -> str | None:
"""Classify error content. Returns category or None if not an error."""
snippet = content[:2000]
for pattern, category in _ERROR_PATTERNS:
if pattern.search(snippet):
return category
return None
def _is_error(content: str) -> bool:
"""Quick check if tool output looks like an error."""
if not content or len(content) < 10:
return False
return _classify_error(content) is not None
# =============================================================================
# Tool Call Extractors
# =============================================================================
# Extract command from Bash tool calls
_COMMAND_RE = re.compile(r"^(?:source\s+\S+\s*&&\s*)?(.+)", re.I)
# Extract file paths
_FILE_PATH_RE = re.compile(r"(?:/[\w./-]+(?:\.\w+)?)")
# Extract package/module names from errors
_MODULE_RE = re.compile(r"No module named ['\"]?(\w[\w.]*)['\"]?")
_COMMAND_NF_RE = re.compile(r"(\w[\w-]*): command not found")
# =============================================================================
# Traffic Learner
# =============================================================================
class TrafficLearner:
"""Extracts learnable patterns from live proxy traffic.
Operates entirely on rule-based heuristics — no LLM calls.
Designed to be called from the proxy request/response path
with minimal overhead (async, non-blocking).
"""
def __init__(
self,
backend: LocalBackend | None = None,
user_id: str = "default",
max_history: int = 20,
dedup_window: int = 100,
min_evidence: int = 2,
) -> None:
"""Initialize the traffic learner.
Args:
backend: Memory backend to save patterns to. If None, patterns
are accumulated but not persisted until a backend is set.
user_id: Default user ID for saved memories.
max_history: Number of recent tool calls to keep for pattern matching.
dedup_window: Number of recent pattern hashes to track for dedup.
min_evidence: Minimum times a pattern must be seen before saving.
"""
self._backend = backend
self._user_id = user_id
self._max_history = max_history
self._min_evidence = min_evidence
# Recent tool call history for error→recovery matching
self._tool_history: list[dict[str, Any]] = []
# Pattern accumulator: hash → (pattern, count)
self._pattern_counts: dict[str, tuple[ExtractedPattern, int]] = {}
# Dedup: hashes of patterns already saved to DB
self._saved_hashes: set[str] = set()
self._dedup_window = dedup_window
# Stats
self._patterns_extracted = 0
self._patterns_saved = 0
self._requests_processed = 0
# Background save queue
self._save_queue: asyncio.Queue[ExtractedPattern] = asyncio.Queue(maxsize=100)
self._save_task: asyncio.Task[None] | None = None
# =========================================================================
# Public API
# =========================================================================
def set_backend(self, backend: LocalBackend) -> None:
"""Set or update the memory backend."""
self._backend = backend
async def start(self) -> None:
"""Start the background save worker."""
if self._save_task is None or self._save_task.done():
self._save_task = asyncio.create_task(self._save_worker())
async def stop(self) -> None:
"""Stop the background save worker."""
if self._save_task and not self._save_task.done():
self._save_task.cancel()
try:
await self._save_task
except asyncio.CancelledError:
pass
async def on_tool_result(
self,
tool_name: str,
tool_input: dict[str, Any],
tool_output: str,
is_error: bool,
agent_type: str = "unknown",
) -> None:
"""Process a tool call result from proxy traffic.
Called by the proxy after each tool_result block is processed.
Non-blocking — patterns are queued for async persistence.
Args:
tool_name: Name of the tool (Bash, Read, Grep, etc.)
tool_input: Tool input parameters
tool_output: Tool output content
is_error: Whether the tool call failed
agent_type: Which agent is being proxied
"""
self._requests_processed += 1
entry = {
"tool_name": tool_name,
"input": tool_input,
"output": tool_output[:2000], # Cap for memory
"is_error": is_error,
"error_category": _classify_error(tool_output) if is_error else None,
"timestamp": time.time(),
"agent_type": agent_type,
}
# Check for error→recovery pattern BEFORE adding to history
if not is_error and self._tool_history:
patterns = self._extract_error_recovery(entry)
for pattern in patterns:
await self._accumulate(pattern)
# Extract environment patterns
env_patterns = self._extract_environment(entry)
for pattern in env_patterns:
await self._accumulate(pattern)
# Add to history (bounded)
self._tool_history.append(entry)
if len(self._tool_history) > self._max_history:
self._tool_history.pop(0)
async def on_messages(
self,
messages: list[dict[str, Any]],
agent_type: str = "unknown",
) -> None:
"""Process message content for preference/architecture patterns.
Called with the messages array from a proxy request.
Extracts patterns from user corrections, assistant decisions, etc.
Args:
messages: The messages array from the API request
agent_type: Which agent is being proxied
"""
for msg in messages[-3:]: # Only look at recent messages
role = msg.get("role", "")
content = msg.get("content", "")
if isinstance(content, list):
# Extract text from content blocks
content = " ".join(
block.get("text", "")
for block in content
if isinstance(block, dict) and block.get("type") == "text"
)
if not content:
continue
if role == "user":
patterns = self._extract_preferences(content)
for pattern in patterns:
await self._accumulate(pattern)
def get_stats(self) -> dict[str, Any]:
"""Get learner statistics."""
return {
"requests_processed": self._requests_processed,
"patterns_extracted": self._patterns_extracted,
"patterns_saved": self._patterns_saved,
"pending_patterns": len(self._pattern_counts),
"history_size": len(self._tool_history),
}
# =========================================================================
# Pattern Extraction
# =========================================================================
def _extract_error_recovery(self, success_entry: dict[str, Any]) -> list[ExtractedPattern]:
"""Extract error→recovery patterns.
Looks backward in history for recent errors, then checks if the
current successful call is a recovery (same tool, different params).
"""
patterns: list[ExtractedPattern] = []
tool_name = success_entry["tool_name"]
# Look at recent history for matching errors
for i in range(len(self._tool_history) - 1, max(-1, len(self._tool_history) - 6), -1):
prev = self._tool_history[i]
if not prev["is_error"]:
continue
# Same tool type — likely a retry with corrected params
if prev["tool_name"] == tool_name:
pattern = self._build_recovery_pattern(prev, success_entry)
if pattern:
patterns.append(pattern)
break # Only match the most recent error
# Bash → Bash with different command (common for env issues)
if prev["tool_name"] == "Bash" and tool_name == "Bash":
pattern = self._build_command_recovery(prev, success_entry)
if pattern:
patterns.append(pattern)
break
return patterns
def _build_recovery_pattern(
self,
error_entry: dict[str, Any],
success_entry: dict[str, Any],
) -> ExtractedPattern | None:
"""Build a recovery pattern from an error→success pair."""
tool = error_entry["tool_name"]
error_cat = error_entry.get("error_category", "unknown")
if tool == "Bash":
return self._build_command_recovery(error_entry, success_entry)
elif tool == "Read":
error_path = error_entry["input"].get("file_path", "")
success_path = success_entry["input"].get("file_path", "")
if error_path and success_path and error_path != success_path:
content = (
f"File `{error_path}` does not exist. The correct path is `{success_path}`."
)
return ExtractedPattern(
category=PatternCategory.ERROR_RECOVERY,
content=content,
importance=0.7,
entity_refs=[success_path],
metadata={"error_category": error_cat},
)
elif tool in ("Grep", "Glob"):
error_pattern = error_entry["input"].get("pattern", "")
success_pattern = success_entry["input"].get("pattern", "")
if error_pattern != success_pattern:
content = (
f"Search pattern `{error_pattern}` found no results. "
f"Use `{success_pattern}` instead."
)
return ExtractedPattern(
category=PatternCategory.ERROR_RECOVERY,
content=content,
importance=0.5,
)
return None
def _build_command_recovery(
self,
error_entry: dict[str, Any],
success_entry: dict[str, Any],
) -> ExtractedPattern | None:
"""Build a command recovery pattern from Bash error→success."""
failed_cmd = error_entry["input"].get("command", "")
success_cmd = success_entry["input"].get("command", "")
error_cat = error_entry.get("error_category", "unknown")
if not failed_cmd or not success_cmd or failed_cmd == success_cmd:
return None
# Determine importance based on error category
importance = 0.7
if error_cat == "command_not_found":
importance = 0.85 # Environment setup is high-value
elif error_cat == "module_not_found":
importance = 0.8
# Truncate long commands
failed_short = failed_cmd[:200]
success_short = success_cmd[:200]
content = f"Command `{failed_short}` fails ({error_cat}). Use `{success_short}` instead."
# Extract entity references
entities: list[str] = []
module_match = _MODULE_RE.search(error_entry["output"])
if module_match:
entities.append(module_match.group(1))
cmd_match = _COMMAND_NF_RE.search(error_entry["output"])
if cmd_match:
entities.append(cmd_match.group(1))
return ExtractedPattern(
category=PatternCategory.ERROR_RECOVERY,
content=content,
importance=importance,
entity_refs=entities,
metadata={"error_category": error_cat, "failed_cmd": failed_short},
)
def _extract_environment(self, entry: dict[str, Any]) -> list[ExtractedPattern]:
"""Extract environment facts from tool calls."""
patterns: list[ExtractedPattern] = []
if entry["tool_name"] != "Bash":
return patterns
cmd = entry["input"].get("command", "")
output = entry["output"]
# Successful commands reveal working environment patterns
if not entry["is_error"]:
# Python/venv activation patterns
if "activate" in cmd and "source" in cmd:
# Extract the venv path
venv_match = re.search(r"source\s+(\S+/activate)", cmd)
if venv_match:
venv_path = venv_match.group(1)
patterns.append(
ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
content=f"Python virtual environment: `source {venv_path}` before running Python tools.",
importance=0.8,
entity_refs=[venv_path],
metadata={"type": "venv_activation"},
)
)
# Detect working test commands
if "pytest" in cmd and "PASSED" in output:
patterns.append(
ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
content=f"Working test command: `{cmd[:200]}`",
importance=0.6,
metadata={"type": "test_command"},
)
)
return patterns
def _extract_preferences(self, user_text: str) -> list[ExtractedPattern]:
"""Extract preference signals from user messages.
Looks for correction patterns: "no", "don't", "instead", "use X not Y".
"""
patterns: list[ExtractedPattern] = []
# Negative corrections: "don't X", "stop X", "no, X"
correction_res = [
re.compile(r"(?:don'?t|do not|stop|never|avoid)\s+(.{10,100})", re.I),
re.compile(r"(?:no,?\s+)(?:use|try|do)\s+(.{10,100})", re.I),
re.compile(r"instead(?:,?\s+)(.{10,80})", re.I),
]
for regex in correction_res:
match = regex.search(user_text[:500])
if match:
correction = match.group(1).strip().rstrip(".")
patterns.append(
ExtractedPattern(
category=PatternCategory.PREFERENCE,
content=f"User preference: {correction}",
importance=0.75,
metadata={"type": "correction", "source_text": user_text[:200]},
)
)
break # One preference per message
return patterns
# =========================================================================
# Pattern Accumulation & Persistence
# =========================================================================
async def _accumulate(self, pattern: ExtractedPattern) -> None:
"""Accumulate a pattern, saving when evidence threshold is met."""
self._patterns_extracted += 1
h = pattern.content_hash
# Already saved — skip
if h in self._saved_hashes:
return
# Accumulate evidence
if h in self._pattern_counts:
existing, count = self._pattern_counts[h]
count += 1
self._pattern_counts[h] = (existing, count)
else:
self._pattern_counts[h] = (pattern, 1)
return # First sighting — wait for more evidence
# Check if evidence threshold met
_, count = self._pattern_counts[h]
if count >= self._min_evidence:
# Ready to save
del self._pattern_counts[h]
self._saved_hashes.add(h)
# Trim saved hashes to prevent unbounded growth
if len(self._saved_hashes) > self._dedup_window:
# Remove oldest (arbitrary, set is unordered, but prevents growth)
self._saved_hashes.pop()
try:
self._save_queue.put_nowait(pattern)
except asyncio.QueueFull:
logger.debug("Traffic learner save queue full, dropping pattern")
async def _save_worker(self) -> None:
"""Background worker that persists patterns to memory backend."""
while True:
try:
pattern = await self._save_queue.get()
if self._backend is None:
continue
await self._backend.save_memory(
content=pattern.content,
user_id=self._user_id,
metadata={
"source": "traffic_learner",
"category": pattern.category.value,
"evidence_count": pattern.evidence_count,
**pattern.metadata,
},
)
self._patterns_saved += 1
logger.debug(f"Traffic learner saved pattern: {pattern.content[:80]}")
except asyncio.CancelledError:
break
except Exception as e:
logger.warning(f"Traffic learner save failed: {e}")
# =========================================================================
# Convenience: Extract from Anthropic messages format
# =========================================================================
def extract_tool_results_from_messages(
self,
messages: list[dict[str, Any]],
) -> list[dict[str, Any]]:
"""Extract tool_result blocks from Anthropic-format messages.
Useful for processing the messages array to find tool calls and
their results for pattern extraction.
Returns list of dicts with: tool_name, input, output, is_error
"""
results: list[dict[str, Any]] = []
# Build tool_use_id → tool_use mapping
tool_uses: dict[str, dict[str, Any]] = {}
for msg in messages:
content = msg.get("content", [])
if not isinstance(content, list):
continue
for block in content:
if isinstance(block, dict) and block.get("type") == "tool_use":
tool_uses[block.get("id", "")] = block
# Find tool_results and match with tool_uses
for msg in messages:
content = msg.get("content", [])
if not isinstance(content, list):
continue
for block in content:
if not isinstance(block, dict) or block.get("type") != "tool_result":
continue
tool_use_id = block.get("tool_use_id", "")
tool_use = tool_uses.get(tool_use_id, {})
# Extract output text
result_content = block.get("content", "")
if isinstance(result_content, list):
result_content = " ".join(
b.get("text", "")
for b in result_content
if isinstance(b, dict) and b.get("type") == "text"
)
results.append(
{
"tool_name": tool_use.get("name", "unknown"),
"input": tool_use.get("input", {}),
"output": str(result_content),
"is_error": block.get("is_error", False) or _is_error(str(result_content)),
}
)
return results
+33
View File
@@ -0,0 +1,33 @@
"""Agent-native memory writers — export Headroom memories to each agent's format.
Each writer knows how to produce memory files in the format that a specific
coding agent reads on startup. Writers handle:
- Format constraints (YAML frontmatter, heading levels, line limits)
- Token budget management (prioritize by importance × recency)
- Deduplication against existing content
- Marker-delimited sections for safe updates
Supported agents:
- Claude Code: MEMORY.md (auto-memory) + per-topic files
- Cursor: .cursor/rules/*.mdc (YAML frontmatter + markdown)
- Codex: AGENTS.md / ~/.codex/instructions.md
- Aider: Convention files referenced in .aider.conf.yml
- Gemini: GEMINI.md
- Generic: Plain markdown (any agent)
"""
from headroom.memory.writers.base import AgentWriter, ExportResult, MemoryEntry
from headroom.memory.writers.claude_writer import ClaudeCodeMemoryWriter
from headroom.memory.writers.codex_writer import CodexMemoryWriter
from headroom.memory.writers.cursor_writer import CursorMemoryWriter
from headroom.memory.writers.generic_writer import GenericMemoryWriter
__all__ = [
"AgentWriter",
"ClaudeCodeMemoryWriter",
"CodexMemoryWriter",
"CursorMemoryWriter",
"ExportResult",
"GenericMemoryWriter",
"MemoryEntry",
]
+192
View File
@@ -0,0 +1,192 @@
"""Base class and shared utilities for agent-native memory writers.
Writers convert Headroom memory entries into agent-specific file formats.
The base class handles token budgeting, deduplication, marker management,
and priority ranking. Subclasses implement format-specific rendering.
"""
from __future__ import annotations
import hashlib
import re
import time
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
# Marker delimiters for Headroom-managed sections (matches learn/writer.py)
MARKER_START = "<!-- headroom:memory:start -->"
MARKER_END = "<!-- headroom:memory:end -->"
MARKER_PATTERN = re.compile(
re.escape(MARKER_START) + r".*?" + re.escape(MARKER_END),
re.DOTALL,
)
@dataclass
class MemoryEntry:
"""A memory entry to be written to an agent's file.
Simplified view of HierarchicalMemory's Memory model,
focused on what writers need.
"""
content: str
importance: float = 0.5
category: str = "" # error_recovery, environment, preference, architecture
entity_refs: list[str] = field(default_factory=list)
created_at: float = field(default_factory=time.time)
last_accessed: float = 0.0
access_count: int = 0
metadata: dict[str, Any] = field(default_factory=dict)
memory_id: str = ""
@property
def content_hash(self) -> str:
return hashlib.sha256(self.content.encode()).hexdigest()[:16]
@property
def score(self) -> float:
"""Combined score for ranking: importance × recency × access."""
age_days = (time.time() - self.created_at) / 86400
recency = 1.0 / (1.0 + age_days * 0.1) # Decay over ~10 days
access_boost = min(1.0, 0.5 + self.access_count * 0.1)
return self.importance * recency * access_boost
@dataclass
class ExportResult:
"""Result of a memory export operation."""
files_written: list[Path] = field(default_factory=list)
content_by_file: dict[str, str] = field(default_factory=dict) # path → content
memories_exported: int = 0
memories_skipped_dedup: int = 0
memories_skipped_budget: int = 0
dry_run: bool = True
def _estimate_tokens(text: str) -> int:
"""Rough token estimate: ~4 chars per token for English."""
return len(text) // 4
class AgentWriter(ABC):
"""Base class for agent-native memory writers.
Subclasses implement:
- format_memories(): render memories in agent-specific format
- default_paths(): where to write for this agent
- agent_name: human-readable agent name
"""
# Subclasses set these
agent_name: str = "generic"
default_token_budget: int = 3000 # Max tokens for the memory section
def __init__(
self,
project_path: Path | None = None,
token_budget: int | None = None,
) -> None:
self._project_path = project_path or Path.cwd()
self._token_budget = token_budget or self.default_token_budget
def export(
self,
memories: list[MemoryEntry],
output_path: Path | None = None,
dry_run: bool = True,
) -> ExportResult:
"""Export memories to agent-native format.
Args:
memories: Memory entries to export.
output_path: Override output path (uses default if None).
dry_run: If True, don't write files.
Returns:
ExportResult with files written and stats.
"""
result = ExportResult(dry_run=dry_run)
if not memories:
return result
# Rank by combined score
ranked = sorted(memories, key=lambda m: m.score, reverse=True)
# Deduplicate by content hash
seen_hashes: set[str] = set()
unique: list[MemoryEntry] = []
for m in ranked:
h = m.content_hash
if h in seen_hashes:
result.memories_skipped_dedup += 1
continue
seen_hashes.add(h)
unique.append(m)
# Apply token budget
budgeted: list[MemoryEntry] = []
tokens_used = 0
for m in unique:
entry_tokens = _estimate_tokens(m.content) + 10 # overhead
if tokens_used + entry_tokens > self._token_budget:
result.memories_skipped_budget += 1
continue
tokens_used += entry_tokens
budgeted.append(m)
if not budgeted:
return result
# Format in agent-specific way
formatted = self.format_memories(budgeted)
# Wrap in markers
section = f"{MARKER_START}\n{formatted}\n{MARKER_END}"
# Determine output path
target = output_path or self.default_path()
# Merge into existing file
full_content = _merge_section(target, section)
result.files_written.append(target)
result.content_by_file[str(target)] = full_content
result.memories_exported = len(budgeted)
if not dry_run:
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(full_content)
return result
@abstractmethod
def format_memories(self, memories: list[MemoryEntry]) -> str:
"""Format memories in agent-specific format.
Args:
memories: Ranked, deduped, budget-constrained memory entries.
Returns:
Formatted string ready to be wrapped in markers and written.
"""
...
@abstractmethod
def default_path(self) -> Path:
"""Default output path for this agent."""
...
def _merge_section(file_path: Path, section: str) -> str:
"""Merge a marker-delimited section into an existing file."""
if file_path.exists():
existing = file_path.read_text()
if MARKER_START in existing:
return MARKER_PATTERN.sub(section, existing)
return existing.rstrip() + "\n\n" + section + "\n"
return section + "\n"
+120
View File
@@ -0,0 +1,120 @@
"""Claude Code memory writer — exports to MEMORY.md and per-topic files.
Claude Code's memory system:
- MEMORY.md index at ~/.claude/projects/<project>/memory/MEMORY.md
- First 200 lines always loaded into context
- Per-topic files in same directory, loaded on demand
- Format: markdown with ## headers and bullet points
"""
from __future__ import annotations
from collections import defaultdict
from pathlib import Path
from headroom.memory.writers.base import AgentWriter, MemoryEntry
class ClaudeCodeMemoryWriter(AgentWriter):
"""Writes memories to Claude Code's MEMORY.md format."""
agent_name = "claude"
default_token_budget = 2000 # Claude loads first 200 lines (~2K tokens)
def __init__(
self,
project_path: Path | None = None,
token_budget: int | None = None,
memory_dir: Path | None = None,
) -> None:
super().__init__(project_path, token_budget)
self._memory_dir = memory_dir
def format_memories(self, memories: list[MemoryEntry]) -> str:
"""Format as Claude Code MEMORY.md section."""
lines = [
"## Headroom Learned Context",
"*Auto-maintained by Headroom — do not edit manually*",
"",
]
# Group by category
grouped: dict[str, list[MemoryEntry]] = defaultdict(list)
for m in memories:
cat = m.category or "General"
# Capitalize category for heading
heading = cat.replace("_", " ").title()
grouped[heading].append(m)
for heading, entries in grouped.items():
lines.append(f"### {heading}")
for entry in entries:
# Each memory as a bullet point
lines.append(f"- {entry.content}")
lines.append("")
return "\n".join(lines)
def default_path(self) -> Path:
"""Default: Claude Code project memory directory."""
if self._memory_dir:
return self._memory_dir / "MEMORY.md"
# Try to find Claude Code project memory path
project_path = self._project_path
# Claude Code stores per-project memory at:
# ~/.claude/projects/-<sanitized-path>/memory/MEMORY.md
sanitized = str(project_path).replace("/", "-")
claude_memory_dir = Path.home() / ".claude" / "projects" / sanitized / "memory"
return claude_memory_dir / "MEMORY.md"
def export_topics(
self,
memories: list[MemoryEntry],
dry_run: bool = True,
) -> dict[str, str]:
"""Export high-importance memories to per-topic files.
Claude Code loads topic files on demand, so we can put
detailed memories here without consuming the 200-line budget.
Returns:
Dict of filename → content for topic files written.
"""
topic_files: dict[str, str] = {}
# Group by category
grouped: dict[str, list[MemoryEntry]] = defaultdict(list)
for m in memories:
cat = m.category or "general"
grouped[cat].append(m)
memory_dir = self.default_path().parent
for category, entries in grouped.items():
if len(entries) < 2:
continue # Not enough for a dedicated topic file
filename = f"headroom_{category}.md"
lines = [
"---",
f"name: headroom-{category}",
f"description: Headroom-learned {category.replace('_', ' ')} patterns",
"type: reference",
"---",
"",
f"# {category.replace('_', ' ').title()}",
"",
]
for entry in entries:
lines.append(f"- {entry.content}")
lines.append("")
content = "\n".join(lines)
topic_files[filename] = content
if not dry_run:
memory_dir.mkdir(parents=True, exist_ok=True)
(memory_dir / filename).write_text(content)
return topic_files
+47
View File
@@ -0,0 +1,47 @@
"""Codex CLI memory writer — exports to AGENTS.md / instructions.md.
OpenAI Codex CLI's memory system:
- AGENTS.md files walk up directory tree (like Claude's CLAUDE.md)
- ~/.codex/AGENTS.override.md for global overrides
- All layers are merged before injection
- Plain markdown format, no special frontmatter
"""
from __future__ import annotations
from collections import defaultdict
from pathlib import Path
from headroom.memory.writers.base import AgentWriter, MemoryEntry
class CodexMemoryWriter(AgentWriter):
"""Writes memories to Codex's AGENTS.md format."""
agent_name = "codex"
default_token_budget = 3000
def format_memories(self, memories: list[MemoryEntry]) -> str:
"""Format as AGENTS.md section."""
lines = [
"## Headroom Learned Context",
"",
]
grouped: dict[str, list[MemoryEntry]] = defaultdict(list)
for m in memories:
cat = m.category or "General"
heading = cat.replace("_", " ").title()
grouped[heading].append(m)
for heading, entries in grouped.items():
lines.append(f"### {heading}")
for entry in entries:
lines.append(f"- {entry.content}")
lines.append("")
return "\n".join(lines)
def default_path(self) -> Path:
"""Default: AGENTS.md in project root."""
return self._project_path / "AGENTS.md"
+132
View File
@@ -0,0 +1,132 @@
"""Cursor memory writer — exports to .cursor/rules/*.mdc files.
Cursor's rules system:
- Files in .cursor/rules/ with .mdc extension
- YAML frontmatter with: description, globs (optional), alwaysApply (bool)
- Markdown body with instructions
- Rules with alwaysApply: true are always loaded
- Rules with globs are loaded when matching files are in context
"""
from __future__ import annotations
from collections import defaultdict
from pathlib import Path
from headroom.memory.writers.base import (
MARKER_END,
MARKER_PATTERN,
MARKER_START,
AgentWriter,
ExportResult,
MemoryEntry,
_estimate_tokens,
)
class CursorMemoryWriter(AgentWriter):
"""Writes memories to Cursor's .cursor/rules/*.mdc format."""
agent_name = "cursor"
default_token_budget = 3000
def format_memories(self, memories: list[MemoryEntry]) -> str:
"""Format as Cursor .mdc content (body only, no frontmatter).
Frontmatter is handled in export() since it's outside markers.
"""
lines: list[str] = []
grouped: dict[str, list[MemoryEntry]] = defaultdict(list)
for m in memories:
cat = m.category or "General"
heading = cat.replace("_", " ").title()
grouped[heading].append(m)
for heading, entries in grouped.items():
lines.append(f"## {heading}")
lines.append("")
for entry in entries:
lines.append(f"- {entry.content}")
lines.append("")
return "\n".join(lines)
def default_path(self) -> Path:
"""Default: .cursor/rules/headroom-memory.mdc in project root."""
return self._project_path / ".cursor" / "rules" / "headroom-memory.mdc"
def export(
self,
memories: list[MemoryEntry],
output_path: Path | None = None,
dry_run: bool = True,
) -> ExportResult:
"""Export with Cursor-specific .mdc frontmatter."""
result = ExportResult(dry_run=dry_run)
if not memories:
return result
# Rank, dedup, budget (reuse base logic)
ranked = sorted(memories, key=lambda m: m.score, reverse=True)
seen: set[str] = set()
unique: list[MemoryEntry] = []
for m in ranked:
h = m.content_hash
if h in seen:
result.memories_skipped_dedup += 1
continue
seen.add(h)
unique.append(m)
budgeted: list[MemoryEntry] = []
tokens_used = 0
for m in unique:
entry_tokens = _estimate_tokens(m.content) + 10
if tokens_used + entry_tokens > self._token_budget:
result.memories_skipped_budget += 1
continue
tokens_used += entry_tokens
budgeted.append(m)
if not budgeted:
return result
# Build full .mdc file content
body = self.format_memories(budgeted)
target = output_path or self.default_path()
# If file exists and has our markers, only replace marker section
if target.exists():
existing = target.read_text()
if MARKER_START in existing:
section = f"{MARKER_START}\n{body}\n{MARKER_END}"
full_content = MARKER_PATTERN.sub(section, existing)
else:
# Append our section
section = f"{MARKER_START}\n{body}\n{MARKER_END}"
full_content = existing.rstrip() + "\n\n" + section + "\n"
else:
# Create new .mdc file with frontmatter
full_content = (
"---\n"
"description: Headroom-learned patterns from proxy traffic\n"
"alwaysApply: true\n"
"---\n"
"\n"
"# Headroom Learned Context\n"
"\n"
f"{MARKER_START}\n{body}\n{MARKER_END}\n"
)
result.files_written.append(target)
result.content_by_file[str(target)] = full_content
result.memories_exported = len(budgeted)
if not dry_run:
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(full_content)
return result
+56
View File
@@ -0,0 +1,56 @@
"""Generic memory writer — exports to plain markdown for any agent.
Fallback writer that produces clean markdown suitable for:
- Aider (via .aider.conf.yml read setting)
- Gemini (GEMINI.md)
- Any agent that reads markdown context files
"""
from __future__ import annotations
from collections import defaultdict
from pathlib import Path
from headroom.memory.writers.base import AgentWriter, MemoryEntry
class GenericMemoryWriter(AgentWriter):
"""Writes memories to plain markdown format."""
agent_name = "generic"
default_token_budget = 3000
def __init__(
self,
project_path: Path | None = None,
token_budget: int | None = None,
filename: str = "HEADROOM_MEMORY.md",
) -> None:
super().__init__(project_path, token_budget)
self._filename = filename
def format_memories(self, memories: list[MemoryEntry]) -> str:
"""Format as clean markdown."""
lines = [
"## Headroom Learned Context",
"*Auto-maintained by Headroom proxy — do not edit manually*",
"",
]
grouped: dict[str, list[MemoryEntry]] = defaultdict(list)
for m in memories:
cat = m.category or "General"
heading = cat.replace("_", " ").title()
grouped[heading].append(m)
for heading, entries in grouped.items():
lines.append(f"### {heading}")
for entry in entries:
lines.append(f"- {entry.content}")
lines.append("")
return "\n".join(lines)
def default_path(self) -> Path:
"""Default: HEADROOM_MEMORY.md in project root."""
return self._project_path / self._filename
+10
View File
@@ -1412,6 +1412,16 @@ To SAVE: create /memories/<topic>.txt "content"
logger.error(f"Memory: Semantic rename failed: {e}")
return f"Error: {e}"
@property
def backend(self) -> Any:
"""Expose the backend for external components (e.g., TrafficLearner)."""
return self._backend
@property
def initialized(self) -> bool:
"""Whether the backend has been initialized."""
return self._initialized
async def close(self) -> None:
"""Close the memory backend."""
if self._backend and hasattr(self._backend, "close"):
+45
View File
@@ -715,6 +715,7 @@ class ProxyConfig:
memory_backend: Literal["local", "qdrant-neo4j"] = "local" # Backend type
memory_db_path: str = "headroom_memory.db" # Path for local backend
memory_inject_tools: bool = True # Auto-inject memory tools
traffic_learning_enabled: bool = False # Live traffic pattern learning (--learn)
memory_use_native_tool: bool = False # Use Anthropic's native memory_20250818 tool
memory_inject_context: bool = True # Inject searched memories into context
memory_top_k: int = 10 # Number of memories to inject
@@ -1841,6 +1842,16 @@ class HeadroomProxy:
)
self.memory_handler = MemoryHandler(memory_config)
# Traffic Learner (live pattern extraction from proxy traffic)
# Only activates with --learn flag; requires --memory for backend
self.traffic_learner: TrafficLearner | None = None
if config.traffic_learning_enabled:
from headroom.memory.traffic_learner import TrafficLearner
self.traffic_learner = TrafficLearner(
user_id=os.environ.get("HEADROOM_USER_ID", os.environ.get("USER", "default")),
)
def _get_compression_cache(self, session_id: str) -> CompressionCache:
"""Get or create a CompressionCache for a session."""
if session_id not in self._compression_caches:
@@ -2520,6 +2531,35 @@ class HeadroomProxy:
"content": content + "\n\n" + expansion_text,
}
# Traffic Learner: Extract patterns from inbound tool results
if self.traffic_learner:
try:
# Wire backend on first use (lazy init after memory handler is ready)
if (
self.traffic_learner._backend is None
and self.memory_handler
and self.memory_handler.initialized
and self.memory_handler.backend
):
self.traffic_learner.set_backend(self.memory_handler.backend)
# Extract tool results from messages and learn from them
tool_results = self.traffic_learner.extract_tool_results_from_messages(
optimized_messages
)
for tr in tool_results[-5:]: # Only recent results
await self.traffic_learner.on_tool_result(
tool_name=tr["tool_name"],
tool_input=tr["input"],
tool_output=tr["output"],
is_error=tr["is_error"],
)
# Also extract preference signals from user messages
await self.traffic_learner.on_messages(optimized_messages)
except Exception as e:
logger.debug(f"[{request_id}] Traffic learner: {e}")
# Memory: Inject context and tools
if self.memory_handler and memory_user_id:
# Search and inject memory context
@@ -6648,9 +6688,14 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
await proxy.startup()
# Start background task for periodic TOIN stats logging
asyncio.create_task(_log_toin_stats_periodically())
# Start traffic learner background save worker
if proxy.traffic_learner:
await proxy.traffic_learner.start()
@app.on_event("shutdown")
async def shutdown():
if proxy.traffic_learner:
await proxy.traffic_learner.stop()
await proxy.shutdown()
# Health & Metrics
+165
View File
@@ -0,0 +1,165 @@
"""Tests for the Memory Budget Manager."""
from __future__ import annotations
import time
from pathlib import Path
import pytest
from headroom.memory.budget import (
BudgetConfig,
BudgetReport,
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_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_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
+246
View File
@@ -0,0 +1,246 @@
"""Tests for --learn flag opt-in/opt-out behavior.
Verifies that:
1. Default proxy has no traffic learner (memory_enabled=False, traffic_learning=False)
2. --memory enables memory tools but NOT traffic learning
3. --learn enables traffic learning AND implies --memory
4. --no-learn disables traffic learning even with --memory
5. compress() API is completely unaffected by memory/learn flags
6. ProxyConfig correctly resolves flag combinations
"""
from __future__ import annotations
import pytest
from headroom.proxy.server import HeadroomProxy, ProxyConfig
# =============================================================================
# ProxyConfig Flag Resolution Tests
# =============================================================================
class TestProxyConfigFlags:
"""Test that ProxyConfig correctly reflects flag combinations."""
def test_default_config_no_memory_no_learning(self):
"""Default config: no memory, no traffic learning."""
config = ProxyConfig()
assert config.memory_enabled is False
assert config.traffic_learning_enabled is False
def test_memory_only(self):
"""--memory: memory tools enabled, no traffic learning."""
config = ProxyConfig(memory_enabled=True)
assert config.memory_enabled is True
assert config.traffic_learning_enabled is False
def test_learn_implies_memory(self):
"""--learn: both memory and traffic learning enabled."""
config = ProxyConfig(
memory_enabled=True, # --learn implies --memory in CLI
traffic_learning_enabled=True,
)
assert config.memory_enabled is True
assert config.traffic_learning_enabled is True
def test_learn_without_memory_still_works(self):
"""Edge case: traffic_learning=True but memory=False (server handles gracefully)."""
config = ProxyConfig(
memory_enabled=False,
traffic_learning_enabled=True,
)
assert config.traffic_learning_enabled is True
# In practice, CLI ensures --learn implies --memory
def test_no_learn_overrides(self):
"""--no-learn should prevent traffic learning even with --memory."""
# This is handled at CLI level, not config level.
# Config just stores the resolved values.
config = ProxyConfig(
memory_enabled=True,
traffic_learning_enabled=False, # --no-learn
)
assert config.memory_enabled is True
assert config.traffic_learning_enabled is False
# =============================================================================
# ProxyServer Traffic Learner Initialization Tests
# =============================================================================
class TestHeadroomProxyTrafficLearner:
"""Test that HeadroomProxy correctly initializes (or doesn't) the traffic learner."""
def test_no_traffic_learner_by_default(self):
"""Default proxy has no traffic learner."""
config = ProxyConfig()
proxy = HeadroomProxy(config)
assert proxy.traffic_learner is None
def test_no_traffic_learner_with_memory_only(self):
"""--memory alone does NOT create traffic learner."""
config = ProxyConfig(memory_enabled=True)
proxy = HeadroomProxy(config)
assert proxy.traffic_learner is None
def test_traffic_learner_created_with_learn(self):
"""--learn creates traffic learner."""
config = ProxyConfig(
memory_enabled=True,
traffic_learning_enabled=True,
)
proxy = HeadroomProxy(config)
assert proxy.traffic_learner is not None
def test_traffic_learner_starts_without_backend(self):
"""Traffic learner starts with no backend (wired lazily)."""
config = ProxyConfig(
memory_enabled=True,
traffic_learning_enabled=True,
)
proxy = HeadroomProxy(config)
assert proxy.traffic_learner is not None
assert proxy.traffic_learner._backend is None
# =============================================================================
# CLI Flag Resolution Tests (simulates CLI logic without running Click)
# =============================================================================
class TestCLIFlagResolution:
"""Test the flag resolution logic used in the proxy CLI.
Replicates the logic: memory_enabled = memory or (learn and not no_learn)
traffic_learning_enabled = learn and not no_learn
"""
@staticmethod
def _resolve(
memory: bool = False,
learn: bool = False,
no_learn: bool = False,
) -> tuple[bool, bool]:
"""Replicate CLI flag resolution logic from proxy.py."""
memory_enabled = memory or (learn and not no_learn)
traffic_learning_enabled = learn and not no_learn
return memory_enabled, traffic_learning_enabled
def test_no_flags(self):
"""No flags: nothing enabled."""
mem, learn = self._resolve()
assert mem is False
assert learn is False
def test_memory_only(self):
"""--memory: memory yes, learning no."""
mem, learn = self._resolve(memory=True)
assert mem is True
assert learn is False
def test_learn_only(self):
"""--learn: both memory and learning enabled."""
mem, learn = self._resolve(learn=True)
assert mem is True
assert learn is True
def test_learn_and_memory(self):
"""--learn --memory: both enabled (redundant but valid)."""
mem, learn = self._resolve(memory=True, learn=True)
assert mem is True
assert learn is True
def test_no_learn_overrides_learn(self):
"""--learn --no-learn: learning disabled, memory disabled (learn was sole enabler)."""
mem, learn = self._resolve(learn=True, no_learn=True)
assert mem is False
assert learn is False
def test_memory_and_no_learn(self):
"""--memory --no-learn: memory yes, learning no."""
mem, learn = self._resolve(memory=True, no_learn=True)
assert mem is True
assert learn is False
def test_all_flags(self):
"""--memory --learn --no-learn: memory yes (explicit), learning no (--no-learn wins)."""
mem, learn = self._resolve(memory=True, learn=True, no_learn=True)
assert mem is True
assert learn is False
# =============================================================================
# compress() API Isolation Tests
# =============================================================================
class TestCompressAPIIsolation:
"""Verify that compress() is completely unaffected by memory/learn flags.
compress() is a pure function — it should never touch memory, traffic
learning, or any stateful components.
"""
def test_compress_has_no_memory_dependency(self):
"""compress() module does not import memory modules."""
from headroom import compress
# compress is a function, not a class with state
assert callable(compress)
def test_compress_function_signature(self):
"""compress() signature has no memory/learn parameters."""
import inspect
from headroom import compress
sig = inspect.signature(compress)
param_names = set(sig.parameters.keys())
# Should NOT have memory or learn parameters
assert "memory" not in param_names
assert "learn" not in param_names
assert "traffic_learning" not in param_names
assert "memory_enabled" not in param_names
# =============================================================================
# Wrap CLI --learn Flag Tests
# =============================================================================
class TestWrapCLILearnFlag:
"""Test that wrap subcommands accept --learn flag."""
def test_start_proxy_builds_learn_command(self):
"""_start_proxy with learn=True adds --learn to command."""
import sys
from headroom.cli.wrap import _start_proxy
# We can't actually run the proxy, but we can check the function signature
import inspect
sig = inspect.signature(_start_proxy)
assert "learn" in sig.parameters
def test_ensure_proxy_accepts_learn(self):
"""_ensure_proxy accepts learn kwarg."""
import inspect
from headroom.cli.wrap import _ensure_proxy
sig = inspect.signature(_ensure_proxy)
assert "learn" in sig.parameters
def test_launch_tool_accepts_learn(self):
"""_launch_tool accepts learn kwarg."""
import inspect
from headroom.cli.wrap import _launch_tool
sig = inspect.signature(_launch_tool)
assert "learn" in sig.parameters
+286
View File
@@ -0,0 +1,286 @@
"""Tests for the Traffic Pattern Learner.
Tests pattern extraction from proxy traffic without requiring
a real memory backend.
"""
from __future__ import annotations
import asyncio
import time
import pytest
from headroom.memory.traffic_learner import (
ExtractedPattern,
PatternCategory,
TrafficLearner,
_classify_error,
_is_error,
)
# =============================================================================
# Error Classification Tests
# =============================================================================
class TestErrorClassification:
def test_file_not_found(self):
assert _classify_error("No such file or directory: foo.py") == "file_not_found"
assert _classify_error("FileNotFoundError: [Errno 2]") == "file_not_found"
def test_command_not_found(self):
assert _classify_error("zsh: command not found: ruff") == "command_not_found"
def test_module_not_found(self):
assert _classify_error("ModuleNotFoundError: No module named 'foo'") == "module_not_found"
def test_permission_denied(self):
assert _classify_error("Permission denied: /etc/shadow") == "permission_denied"
def test_not_an_error(self):
assert _classify_error("Everything is fine, tests passed!") is None
assert _classify_error("") is None
def test_is_error_helper(self):
assert _is_error("No such file or directory")
assert not _is_error("All tests passed")
assert not _is_error("")
assert not _is_error("short")
# =============================================================================
# Traffic Learner Core Tests
# =============================================================================
class TestTrafficLearner:
@pytest.fixture
def learner(self):
"""Create a learner with low evidence threshold for testing."""
return TrafficLearner(
backend=None,
user_id="test-user",
min_evidence=1, # Save on first sighting for tests
)
@pytest.mark.asyncio
async def test_error_recovery_bash(self, learner: TrafficLearner):
"""Test error→recovery pattern extraction for Bash commands."""
# First: a failed command
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": "ruff check ."},
tool_output="zsh: command not found: ruff",
is_error=True,
)
# Then: the recovery
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": "source .venv/bin/activate && ruff check ."},
tool_output="All checks passed!",
is_error=False,
)
stats = learner.get_stats()
assert stats["patterns_extracted"] >= 1
assert stats["requests_processed"] == 2
@pytest.mark.asyncio
async def test_error_recovery_read(self, learner: TrafficLearner):
"""Test error→recovery for Read tool (wrong path → correct path)."""
await learner.on_tool_result(
tool_name="Read",
tool_input={"file_path": "/src/old_module.py"},
tool_output="No such file or directory: /src/old_module.py",
is_error=True,
)
await learner.on_tool_result(
tool_name="Read",
tool_input={"file_path": "/src/new_module.py"},
tool_output="# Module content here\nclass Foo: pass",
is_error=False,
)
stats = learner.get_stats()
assert stats["patterns_extracted"] >= 1
@pytest.mark.asyncio
async def test_environment_venv_detection(self, learner: TrafficLearner):
"""Test detection of virtual environment activation patterns."""
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": "source /project/.venv/bin/activate && pytest"},
tool_output="5 passed in 2.1s",
is_error=False,
)
stats = learner.get_stats()
assert stats["patterns_extracted"] >= 1
@pytest.mark.asyncio
async def test_preference_extraction(self, learner: TrafficLearner):
"""Test extraction of user preference signals."""
await learner.on_messages([
{"role": "user", "content": "don't use git push, I'll push manually"},
])
stats = learner.get_stats()
assert stats["patterns_extracted"] >= 1
@pytest.mark.asyncio
async def test_preference_from_content_blocks(self, learner: TrafficLearner):
"""Test preference extraction from Anthropic content block format."""
await learner.on_messages([
{
"role": "user",
"content": [
{"type": "text", "text": "stop running the full test suite without asking"},
],
},
])
stats = learner.get_stats()
assert stats["patterns_extracted"] >= 1
@pytest.mark.asyncio
async def test_evidence_accumulation(self):
"""Test that patterns need min_evidence before saving."""
learner = TrafficLearner(backend=None, min_evidence=3)
# Same error→recovery pattern 3 times
for _ in range(3):
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": "python test.py"},
tool_output="command not found: python",
is_error=True,
)
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": "python3 test.py"},
tool_output="OK",
is_error=False,
)
stats = learner.get_stats()
assert stats["patterns_extracted"] >= 3
@pytest.mark.asyncio
async def test_dedup(self, learner: TrafficLearner):
"""Test that identical patterns are deduplicated."""
# Same pattern twice
for _ in range(2):
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": "ruff check ."},
tool_output="command not found: ruff",
is_error=True,
)
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": ".venv/bin/ruff check ."},
tool_output="OK",
is_error=False,
)
# Should not double-count the same pattern
stats = learner.get_stats()
# First extraction saves, second is deduped
assert stats["patterns_extracted"] >= 1
@pytest.mark.asyncio
async def test_extract_tool_results_from_messages(self, learner: TrafficLearner):
"""Test extraction of tool results from Anthropic message format."""
messages = [
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "tu_1",
"name": "Bash",
"input": {"command": "ls"},
}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "tu_1",
"content": [{"type": "text", "text": "file1.py\nfile2.py"}],
}
],
},
]
results = learner.extract_tool_results_from_messages(messages)
assert len(results) == 1
assert results[0]["tool_name"] == "Bash"
assert "file1.py" in results[0]["output"]
assert not results[0]["is_error"]
@pytest.mark.asyncio
async def test_tool_history_bounded(self, learner: TrafficLearner):
"""Test that tool history stays within max_history."""
for i in range(30):
await learner.on_tool_result(
tool_name="Read",
tool_input={"file_path": f"/file{i}.py"},
tool_output=f"content {i}",
is_error=False,
)
assert len(learner._tool_history) <= learner._max_history
@pytest.mark.asyncio
async def test_no_pattern_from_success_only(self, learner: TrafficLearner):
"""Test that success without prior error doesn't generate error_recovery pattern."""
await learner.on_tool_result(
tool_name="Bash",
tool_input={"command": "echo hello"},
tool_output="hello",
is_error=False,
)
stats = learner.get_stats()
# Only environment patterns possible, no error_recovery
assert stats["requests_processed"] == 1
# =============================================================================
# Pattern Model Tests
# =============================================================================
class TestExtractedPattern:
def test_content_hash_deterministic(self):
p1 = ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
content="Use venv",
importance=0.5,
)
p2 = ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
content="Use venv",
importance=0.8, # Different importance, same hash
)
assert p1.content_hash == p2.content_hash
def test_different_content_different_hash(self):
p1 = ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
content="Use venv",
importance=0.5,
)
p2 = ExtractedPattern(
category=PatternCategory.ENVIRONMENT,
content="Use conda",
importance=0.5,
)
assert p1.content_hash != p2.content_hash
+279
View File
@@ -0,0 +1,279 @@
"""Tests for agent-native memory writers."""
from __future__ import annotations
import time
from pathlib import Path
import pytest
from headroom.memory.writers.base import (
MARKER_END,
MARKER_START,
ExportResult,
MemoryEntry,
_estimate_tokens,
_merge_section,
)
from headroom.memory.writers.claude_writer import ClaudeCodeMemoryWriter
from headroom.memory.writers.codex_writer import CodexMemoryWriter
from headroom.memory.writers.cursor_writer import CursorMemoryWriter
from headroom.memory.writers.generic_writer import GenericMemoryWriter
# =============================================================================
# Test Data
# =============================================================================
def _make_entries(count: int = 5) -> list[MemoryEntry]:
"""Create test memory entries."""
entries = []
categories = ["error_recovery", "environment", "preference", "architecture"]
for i in range(count):
entries.append(MemoryEntry(
content=f"Test memory entry {i}: use pytest not unittest",
importance=0.5 + (i % 3) * 0.15,
category=categories[i % len(categories)],
entity_refs=[f"/path/to/file{i}.py"],
created_at=time.time() - i * 3600, # Each an hour older
access_count=max(0, 3 - i),
))
return entries
# =============================================================================
# Base / Shared Tests
# =============================================================================
class TestMemoryEntry:
def test_score_calculation(self):
entry = MemoryEntry(
content="test",
importance=0.9,
created_at=time.time(), # Just now
access_count=5,
)
assert entry.score > 0.5 # High importance + recent + accessed
def test_score_decays_with_age(self):
recent = MemoryEntry(content="new", importance=0.9, created_at=time.time())
old = MemoryEntry(content="old", importance=0.9, created_at=time.time() - 30 * 86400)
assert recent.score > old.score
def test_content_hash(self):
e1 = MemoryEntry(content="same content")
e2 = MemoryEntry(content="same content")
assert e1.content_hash == e2.content_hash
def test_different_hash(self):
e1 = MemoryEntry(content="content A")
e2 = MemoryEntry(content="content B")
assert e1.content_hash != e2.content_hash
class TestTokenEstimate:
def test_rough_estimate(self):
assert _estimate_tokens("hello world") > 0
assert _estimate_tokens("a" * 400) == 100 # ~4 chars per token
class TestMergeSection:
def test_new_file(self, tmp_path: Path):
nonexistent = tmp_path / "new.md"
result = _merge_section(nonexistent, "new section")
assert result == "new section\n"
def test_append_to_existing(self, tmp_path: Path):
existing = tmp_path / "existing.md"
existing.write_text("# Existing Content\n\nSome stuff here.")
result = _merge_section(existing, "new section")
assert "# Existing Content" in result
assert "new section" in result
def test_replace_existing_markers(self, tmp_path: Path):
existing = tmp_path / "marked.md"
existing.write_text(
f"# Header\n\n{MARKER_START}\nold content\n{MARKER_END}\n\n# Footer"
)
result = _merge_section(existing, f"{MARKER_START}\nnew content\n{MARKER_END}")
assert "new content" in result
assert "old content" not in result
assert "# Header" in result
assert "# Footer" in result
# =============================================================================
# Claude Code Writer Tests
# =============================================================================
class TestClaudeCodeWriter:
def test_format_memories(self):
writer = ClaudeCodeMemoryWriter()
entries = _make_entries(3)
formatted = writer.format_memories(entries)
assert "## Headroom Learned Context" in formatted
assert "Auto-maintained by Headroom" in formatted
assert "Test memory entry" in formatted
def test_export_dry_run(self, tmp_path: Path):
writer = ClaudeCodeMemoryWriter(
project_path=tmp_path,
memory_dir=tmp_path / "memory",
)
entries = _make_entries(3)
result = writer.export(entries, dry_run=True)
assert result.dry_run is True
assert result.memories_exported == 3
assert len(result.files_written) == 1
assert not (tmp_path / "memory" / "MEMORY.md").exists()
def test_export_writes_file(self, tmp_path: Path):
writer = ClaudeCodeMemoryWriter(
project_path=tmp_path,
memory_dir=tmp_path / "memory",
)
entries = _make_entries(3)
result = writer.export(entries, dry_run=False)
assert result.memories_exported == 3
written = (tmp_path / "memory" / "MEMORY.md").read_text()
assert MARKER_START in written
assert MARKER_END in written
assert "Test memory entry" in written
def test_budget_limits_output(self, tmp_path: Path):
writer = ClaudeCodeMemoryWriter(
project_path=tmp_path,
memory_dir=tmp_path / "memory",
token_budget=50, # Very small budget
)
entries = _make_entries(10)
result = writer.export(entries, dry_run=True)
assert result.memories_skipped_budget > 0
assert result.memories_exported < 10
def test_dedup(self, tmp_path: Path):
writer = ClaudeCodeMemoryWriter(
project_path=tmp_path,
memory_dir=tmp_path / "memory",
)
entries = [
MemoryEntry(content="duplicate content", importance=0.5),
MemoryEntry(content="duplicate content", importance=0.8), # Same content
MemoryEntry(content="unique content", importance=0.6),
]
result = writer.export(entries, dry_run=True)
assert result.memories_skipped_dedup == 1
assert result.memories_exported == 2
def test_export_topics(self, tmp_path: Path):
writer = ClaudeCodeMemoryWriter(
project_path=tmp_path,
memory_dir=tmp_path / "memory",
)
entries = _make_entries(6)
topics = writer.export_topics(entries, dry_run=True)
# Should produce topic files for categories with 2+ entries
assert len(topics) > 0
for filename, content in topics.items():
assert filename.startswith("headroom_")
assert "---" in content # YAML frontmatter
# =============================================================================
# Cursor Writer Tests
# =============================================================================
class TestCursorWriter:
def test_format_memories(self):
writer = CursorMemoryWriter()
entries = _make_entries(3)
formatted = writer.format_memories(entries)
assert "##" in formatted
assert "Test memory entry" in formatted
def test_creates_mdc_with_frontmatter(self, tmp_path: Path):
writer = CursorMemoryWriter(project_path=tmp_path)
entries = _make_entries(3)
result = writer.export(entries, dry_run=False)
mdc_path = tmp_path / ".cursor" / "rules" / "headroom-memory.mdc"
assert mdc_path.exists()
content = mdc_path.read_text()
assert "---" in content
assert "alwaysApply: true" in content
assert "description:" in content
assert MARKER_START in content
def test_updates_existing_mdc(self, tmp_path: Path):
mdc_dir = tmp_path / ".cursor" / "rules"
mdc_dir.mkdir(parents=True)
mdc_file = mdc_dir / "headroom-memory.mdc"
mdc_file.write_text(
"---\ndescription: test\nalwaysApply: true\n---\n\n"
f"# Header\n\n{MARKER_START}\nold stuff\n{MARKER_END}\n"
)
writer = CursorMemoryWriter(project_path=tmp_path)
entries = _make_entries(2)
writer.export(entries, dry_run=False)
content = mdc_file.read_text()
assert "old stuff" not in content
assert "Test memory entry" in content
assert "alwaysApply: true" in content # Preserved
# =============================================================================
# Codex Writer Tests
# =============================================================================
class TestCodexWriter:
def test_format_memories(self):
writer = CodexMemoryWriter()
entries = _make_entries(3)
formatted = writer.format_memories(entries)
assert "## Headroom Learned Context" in formatted
def test_default_path(self, tmp_path: Path):
writer = CodexMemoryWriter(project_path=tmp_path)
assert writer.default_path() == tmp_path / "AGENTS.md"
def test_export(self, tmp_path: Path):
writer = CodexMemoryWriter(project_path=tmp_path)
entries = _make_entries(3)
result = writer.export(entries, dry_run=False)
agents_md = tmp_path / "AGENTS.md"
assert agents_md.exists()
content = agents_md.read_text()
assert MARKER_START in content
# =============================================================================
# Generic Writer Tests
# =============================================================================
class TestGenericWriter:
def test_custom_filename(self, tmp_path: Path):
writer = GenericMemoryWriter(project_path=tmp_path, filename="GEMINI.md")
assert writer.default_path() == tmp_path / "GEMINI.md"
def test_export(self, tmp_path: Path):
writer = GenericMemoryWriter(project_path=tmp_path)
entries = _make_entries(3)
result = writer.export(entries, dry_run=False)
assert (tmp_path / "HEADROOM_MEMORY.md").exists()
assert result.memories_exported == 3