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 in 0fd6dfca,
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 at
58e5702d (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 `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 @ 58e5702d
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 -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:
Tejas Chopra
2026-10-10 09:03:14 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent e4a1ec19be
commit 2e497cbec3
2 changed files with 28 additions and 0 deletions
+14
View File
@@ -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",
+14
View File
@@ -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
# =============================================================================