refactor(memory,learn,cache): remove unreferenced classes, methods and constants (#4112)

## Description

This removes nine symbols in `headroom/memory`, `headroom/learn` and
`headroom/cache` that nothing references outside their own definition.
One is a legacy alias whose only user was its own test.

Evidence: for each name I ran `grep -rnw <name>` across `headroom crates
plugins sdk docs wiki scripts benchmarks examples e2e .github
pyproject.toml tests` and the org's consumer repos. The only hit was the
definition, plus the `FailureAnalyzer` alias test removed here. None of
the names is public API. None is in an `__all__`, a re-export or lazy
export map, an entry-point group or the docs, and no consumer imports
it.

Refs #4136

## Type of Change

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

## Changes Made

- `memory/inline_extractor.py`: remove `InlineMemoryWrapper`, with
`chat` and `chat_with_response`. `with_memory` (`memory/wrapper.py`)
uses only the module's functions, `inject_memory_instruction` and
`parse_response_with_memory`, and those stay.
- `memory/traffic_learner.py`: remove these:
  - `AgentType`;
- `_COMMAND_RE` and `_FILE_PATH_RE`. `_MODULE_RE` and `_COMMAND_NF_RE`
next to them are used and stay;
- `TrafficLearner.get_learned_patterns`. Its docstring said "retained
for backwards compatibility", but `TrafficLearner` is internal to the
proxy.
- `memory/core.py`: remove the private
`HierarchicalMemory._scope_level_value`.
- `cache/compression_feedback.py`: remove the private
`CompressionFeedback._truncate_strategy_dicts`.
- `learn/analyzer.py`: remove `FailureAnalyzer`. Its docstring said
"used by existing CLI code", but `cli/learn.py` uses `SessionAnalyzer`
directly. Also remove `TestFailureAnalyzerCompat` from
`tests/test_learn/test_analyzer.py`.

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_memory_wrapper.py tests/test_inline_extractor_inject.py tests/test_memory/test_traffic_learner.py tests/test_openai_responses_traffic_learner.py tests/test_memory/test_core_operations.py tests/test_learn/test_analyzer.py tests/test_ccr_feedback.py tests/test_memory/test_hierarchical.py tests/test_toin_fixes.py
================ 417 passed, 8 skipped, 772 warnings in 49.26s =================
$ mypy <5 changed product files> --ignore-missing-imports
Success: no issues found in 5 source files
$ uvx ruff@0.16.8 check <changed files>
All checks passed!
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, repo .venv, branch checkout at
93c23cb2 (base a9815bbb), temp HOME / HEADROOM_WORKSPACE_DIR /
CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran a direct script. It imports the touched modules, checks that the
removed names are gone, and drives a real `TrafficLearner` through two
`on_tool_result` calls.
- Ran the tests for every touched module: the memory wrapper, inline
extractor, traffic learner, core, CCR feedback and learn analyzer.
- Observed result:
  - Both proxy requests return HTTP 200 with savings.
- The modules import without the removed symbols, and the learner
processes both results.
  - 417 passed. The 8 skips are optional-dependency skips.
- Not tested: No runtime path changed, because nothing called the
removed symbols.

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

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -u -c "<import touched modules; hasattr(removed name); TrafficLearner().on_tool_result(...) x2; get_stats()>"
headroom.memory.inline_extractor: imports, InlineMemoryWrapper present=False
headroom.memory.traffic_learner: imports, AgentType present=False
headroom.learn.analyzer: imports, FailureAnalyzer present=False
traffic learner stats: {'requests_processed': 2, 'patterns_extracted': 0, 'patterns_saved': 0, 'pending_patterns': 0, 'min_evidence': 1, 'history_size': 2}
```

## Runtime Rollout Safety

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

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A.

## Additional Notes

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

- Documentation: N/A, because none of these names is documented.
- `SQLiteMemoryStore.count_sync` and `HNSWVectorIndex.set_ef_search` are
also unused. Their classes are re-exported from
`headroom.memory.adapters`, so they are deprecated in a separate PR
instead of being deleted here.

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

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Tejas Chopra
2026-10-10 09:00:02 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 65a219877c
commit abbf36f052
6 changed files with 0 additions and 165 deletions
-7
View File
@@ -344,13 +344,6 @@ class CompressionFeedback:
# Extract potential field names from query
self._extract_field_hints(pattern, event.query)
def _truncate_strategy_dicts(self, pattern: LocalToolPattern) -> None:
"""Truncate strategy counters using the shared strategy outcome domain."""
outcomes = pattern.strategy_outcomes
outcomes.prune()
pattern.strategy_compressions = outcomes.compressions
pattern.strategy_retrievals = outcomes.retrievals
def _extract_field_hints(self, pattern: LocalToolPattern, query: str) -> None:
"""Extract potential field names from search queries.
-15
View File
@@ -1162,18 +1162,3 @@ def _safe_int(val: object) -> int:
except (ValueError, TypeError):
return 0
return 0
# =============================================================================
# Legacy compatibility alias
# =============================================================================
class FailureAnalyzer:
"""Legacy alias for SessionAnalyzer — used by existing CLI code."""
def __init__(self) -> None:
self._analyzer = SessionAnalyzer()
def analyze(self, project: ProjectInfo, sessions: list[SessionData]) -> AnalysisResult:
return self._analyzer.analyze(project, sessions)
-9
View File
@@ -894,15 +894,6 @@ class HierarchicalMemory:
f"Bubbled memory {memory.id} from {current_scope.value} to {target_scope.value}"
)
def _scope_level_value(self, level: ScopeLevel) -> int:
"""Get numeric value for scope level (lower = broader scope)."""
return {
ScopeLevel.USER: 0,
ScopeLevel.SESSION: 1,
ScopeLevel.AGENT: 2,
ScopeLevel.TURN: 3,
}[level]
# =========================================================================
# Properties
# =========================================================================
-92
View File
@@ -173,95 +173,3 @@ def parse_response_with_memory(response_text: str | None) -> ParsedResponse:
memories=memories,
raw=response_text,
)
class InlineMemoryWrapper:
"""Wrapper that extracts memories from LLM responses inline.
This is the zero-latency approach - memories are extracted
as part of the response, not in a separate call.
Usage:
wrapper = InlineMemoryWrapper(openai_client)
response, memories = wrapper.chat(
messages=[{"role": "user", "content": "I prefer Python"}],
model="gpt-4o-mini"
)
# response = "Great choice! Python is excellent..."
# memories = [{"content": "User prefers Python"}]
"""
def __init__(self, client: Any):
"""Initialize wrapper.
Args:
client: OpenAI-compatible client
"""
self.client = client
def chat(
self,
messages: list[dict[str, Any]],
model: str = "gpt-4o-mini",
short_instruction: bool = True,
**kwargs: Any,
) -> tuple[str | None, list[dict[str, Any]]]:
"""Send chat request and extract memories inline.
Args:
messages: Chat messages
model: Model to use
short_instruction: Use shorter memory instruction
**kwargs: Additional args for chat completion
Returns:
Tuple of (response_content, extracted_memories)
"""
# Inject memory instruction
modified_messages = inject_memory_instruction(messages, short=short_instruction)
# Call LLM
response = self.client.chat.completions.create(
model=model,
messages=modified_messages,
**kwargs,
)
raw_content = response.choices[0].message.content
# Parse response and extract memories
parsed = parse_response_with_memory(raw_content)
return parsed.content, parsed.memories
def chat_with_response(
self,
messages: list[dict[str, Any]],
model: str = "gpt-4o-mini",
**kwargs: Any,
) -> tuple[Any, str | None, list[dict[str, Any]]]:
"""Send chat request and return full response object.
Args:
messages: Chat messages
model: Model to use
**kwargs: Additional args for chat completion
Returns:
Tuple of (response_object, content, memories)
"""
modified_messages = inject_memory_instruction(messages)
response = self.client.chat.completions.create(
model=model,
messages=modified_messages,
**kwargs,
)
raw_content = response.choices[0].message.content
parsed = parse_response_with_memory(raw_content)
# Modify response to have clean content
response.choices[0].message.content = parsed.content
return response, parsed.content, parsed.memories
-24
View File
@@ -125,17 +125,6 @@ class PatternCategory(str, Enum):
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
# =============================================================================
@@ -258,11 +247,6 @@ def _is_error(content: str) -> bool:
# 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.]*)['\"]?")
@@ -758,14 +742,6 @@ class TrafficLearner:
return list(by_hash.values())
def get_learned_patterns(self) -> list[ExtractedPattern]:
"""Return patterns from the in-memory accumulator.
Retained for backwards compatibility. Reads only the accumulator;
does not consult persisted rows. Use flush_to_file() for full data.
"""
return [pattern for pattern, count in self._pattern_counts.values() if count >= 1]
async def on_tool_result(
self,
tool_name: str,
-18
View File
@@ -21,7 +21,6 @@ from headroom.learn.analyzer import (
_strip_fenced_json,
)
from headroom.learn.models import (
AnalysisResult,
ErrorCategory,
ProjectInfo,
RecommendationTarget,
@@ -1445,20 +1444,3 @@ class TestCallLlmRouting:
mock_cli.return_value = {}
_call_llm("digest", "codex-cli")
mock_cli.assert_called_once_with("digest", "codex-cli", on_progress=None)
# =============================================================================
# Legacy Compatibility
# =============================================================================
class TestFailureAnalyzerCompat:
@patch("headroom.learn.analyzer._call_llm")
def test_legacy_alias_works(self, mock_call_llm: MagicMock):
from headroom.learn.analyzer import FailureAnalyzer
mock_call_llm.return_value = {"context_file_rules": [], "memory_file_rules": []}
analyzer = FailureAnalyzer()
result = analyzer.analyze(_project(), [])
assert isinstance(result, AnalysisResult)