mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
refactor(memory): deprecate the never-wired agent memory writers (#4101)
## Description `headroom/memory/writers/` exports memories to agent files (CLAUDE.md, `.cursor/rules`, AGENTS.md, generic markdown). It arrived in0fd6dfca, and no product code has ever imported it. `headroom learn` writes agent context files through `headroom.learn.writer`, a separate writer. The package lists its classes in `__all__`, so it is public API. This PR deprecates it instead of deleting it. Importing `headroom.memory.writers` now emits a `DeprecationWarning`. **What to use instead:** there is no replacement. For writing agent context files, `headroom learn` (`headroom.learn.writer`) is the supported path. Evidence: - `grep -rnE 'memory\.writers|MemoryWriter|AgentWriter|ExportResult'` finds only the package itself, `memory/budget.py` (removed in a separate PR) and tests. The search covered `headroom crates plugins sdk docs wiki scripts benchmarks examples e2e .github pyproject.toml` and the consumer repos. - The package is not re-exported from `headroom.memory` and not documented. 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 - `headroom/memory/writers/__init__.py`: - Emit `DeprecationWarning("headroom.memory.writers is deprecated and will be removed in a future release; it has no replacement …")` when the package is imported. Importing any submodule, such as `headroom.memory.writers.base`, runs the package first, so that warns too. - Add `.. deprecated::` to the docstring. - `tests/test_memory/test_writers.py`: add one test that asserts the warning fires on import. The existing writer tests stay. - Unchanged: `import headroom.memory`, `headroom.memory.sync` and the sync adapters stay quiet. Checked with `-W error::DeprecationWarning`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest -q -p no:cacheprovider tests/test_memory/test_writers.py tests/test_managed_block_injection.py tests/test_memory/test_budget.py tests/test_memory_sync.py ======================== 92 passed, 1 warning in 1.21s ========================= $ python -W error::DeprecationWarning -c "import headroom.memory, headroom.memory.sync, headroom.memory.sync_adapters.claude_code; print('quiet')" quiet $ uvx ruff@0.16.8 check headroom/memory/writers/__init__.py tests/test_memory/test_writers.py All checks passed! ``` ## Real Behavior Proof - Environment: macOS, Python 3.12.13, repo .venv, branch checkout at58e5702d(basea9815bbb), 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 `python -W always`. It imports `headroom.memory` (the live path), then imports a writer from the deprecated package directly. - Ran the full `tests/test_memory` suite. - Observed result: - Both proxy requests return HTTP 200 with savings, and the proxy log has no deprecation warning. - `headroom.memory` imports quietly. The direct writers import emits the new warning, and the writer still loads. - 615 passed. - Not tested: No runtime path imports the package. `headroom/memory/budget.py` imports it, and #4099 deletes that file. ```text $ bash smoke.sh <worktree> branch: cleanup/memory-cache-memory-writers @58e5702dhealth: 200 POST /v1/messages -> HTTP200 smoke-ok POST /v1/chat/completions -> HTTP200 smoke-ok stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82 proxy.log WARNING/ERROR lines: 2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base 4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection. $ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -u -W always -c "import headroom.memory; print(...); from headroom.memory.writers import GenericMemoryWriter; print(...)" headroom.memory imported <string>:4: DeprecationWarning: headroom.memory.writers is deprecated and will be removed in a future release; it has no replacement (headroom learn writes agent context files through headroom.learn.writer). writer: GenericMemoryWriter ``` ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: N/A; deprecation notice only. - Stable/default behavior changed: No. The writers behave as before. Importing them additionally emits a DeprecationWarning, which Python hides by default outside `__main__` and tests. - Kill switch / disable path: Standard `warnings` filters. - 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 - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] 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. - The audit first proposed deleting the package. Under the deprecate-first rule for public API, it is deprecated here. Deletion can follow in a later release. - The unused budget manager (`memory/budget.py`), which depends on this package, is removed in a separate PR. - "My changes generate no new warnings" refers to code that is used. The only new warning is the intended DeprecationWarning. - mypy was not run, because no types changed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
e4a1ec19be
commit
2e497cbec3
@@ -14,14 +14,28 @@ Supported agents:
|
||||
- Aider: Convention files referenced in .aider.conf.yml
|
||||
- Gemini: GEMINI.md
|
||||
- Generic: Plain markdown (any agent)
|
||||
|
||||
.. deprecated::
|
||||
Nothing in Headroom uses these writers. ``headroom learn`` writes agent
|
||||
context files through ``headroom.learn.writer`` instead.
|
||||
"""
|
||||
|
||||
import warnings
|
||||
|
||||
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
|
||||
|
||||
warnings.warn(
|
||||
"headroom.memory.writers is deprecated and will be removed in a future release; "
|
||||
"it has no replacement (headroom learn writes agent context files through "
|
||||
"headroom.learn.writer).",
|
||||
DeprecationWarning,
|
||||
stacklevel=2,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"AgentWriter",
|
||||
"ClaudeCodeMemoryWriter",
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import importlib
|
||||
import sys
|
||||
import time
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
@@ -22,6 +24,18 @@ from headroom.memory.writers.codex_writer import CodexMemoryWriter
|
||||
from headroom.memory.writers.cursor_writer import CursorMemoryWriter
|
||||
from headroom.memory.writers.generic_writer import GenericMemoryWriter
|
||||
|
||||
|
||||
def test_importing_the_writers_package_warns_deprecated(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
# Restore both the sys.modules entry and the parent attribute afterwards, so
|
||||
# later tests see the original package object whatever the import form.
|
||||
import headroom.memory
|
||||
|
||||
monkeypatch.delitem(sys.modules, "headroom.memory.writers", raising=False)
|
||||
monkeypatch.delattr(headroom.memory, "writers", raising=False)
|
||||
with pytest.warns(DeprecationWarning, match="headroom.memory.writers is deprecated"):
|
||||
importlib.import_module("headroom.memory.writers")
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Test Data
|
||||
# =============================================================================
|
||||
|
||||
Reference in New Issue
Block a user