mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
+19
-1
@@ -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
@@ -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:
|
||||
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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"):
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user