[Feature]: Integrate Headroom as an optional context compression layer to reduce token consumption by 60-95%

[K1-lihongrong]

Summary

Integrate Headroom — a local-first, reversible context compression layer — as an optional plugin/proxy in QwenPaw. Headroom compresses tool outputs, conversation history, RAG chunks, and file contents before they reach the LLM, achieving 60–95% token reduction with no accuracy degradation on standard benchmarks.

Component(s) Affected

• Core / Backend (app, agents, config, providers, utils, local_models)
• Console (frontend web UI)
• Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
• Skills
• CLI
• Documentation (website)
• Tests
• CI/CD
• Scripts / Deploy

Problem / Motivation

QwenPaw agents routinely handle large contexts that drive up token consumption and API costs:

1. Tool outputs — browser_use snapshots, shell command results, file reads can each be thousands of tokens
2. Conversation history — long-running sessions accumulate massive history that must be re-sent each turn
3. Multi-agent collaboration — context is duplicated across agent boundaries
4. Heartbeat polling — each heartbeat re-reads files like HEARTBEAT.md, MEMORY.md, TODO.md

Headroom is purpose-built for exactly this class of problems. It runs entirely locally, supports reversible compression (originals are never lost — the LLM can retrieve them on demand via CCR), and has been validated on real agent workloads:

Workload	Before	After	Savings
Code search (100 results)	17,765	1,408	92%
SRE incident debugging	65,694	5,118	92%
GitHub issue triage	54,174	14,761	73%
Codebase exploration	78,502	41,254	47%

Accuracy preserved on GSM8K (±0.000), TruthfulQA (+0.030), SQuAD v2 (97% at 19% compression), BFCL (97% at 32% compression).

Proposed Solution

I propose a phased integration approach:

Phase 1: Proxy mode (minimal code changes)

Headroom's headroom proxy --port 8787 mode acts as a drop-in OpenAI-compatible proxy. QwenPaw could:

1. Add a config option headroom.enabled = true/false and headroom.port = 8787 in config.toml
2. When enabled, route all LLM API calls through http://localhost:8787/v1/... instead of the provider directly
3. Headroom handles compression/decompression transparently — zero changes to QwenPaw's message pipeline

This is the quickest path to value and can be implemented in a day.

Phase 2: Library mode (deeper integration)

Use from headroom import compress inline for specific high-volume contexts:

• Tool output compression: compress browser_use snapshots and large shell outputs before adding them to the message history
• Conversation history windowing: apply Headroom's IntelligentContext / RollingWindow to maintain a compressed summary of older turns
• File content compression: compress file reads (MEMORY.md, TODO.md, skill docs) before sending to the LLM

Phase 3: Cross-agent memory & failure learning

• Shared memory: Headroom's SharedContext provides compressed context passing across multi-agent workflows — natural fit for QwenPaw's multi-agent architecture
• headroom learn: mines failed sessions and writes corrections to AGENTS.md / MEMORY.md — directly maps to QwenPaw's existing memory system

Phase 4: MCP integration

Headroom exposes MCP tools (headroom_compress, headroom_retrieve, headroom_stats). QwenPaw's MCP-compatible agents could use these directly.

Alternatives Considered

1. Provider-native compaction (Anthropic/OpenAI built-in prompt caching) — passive, no control over what gets cached, doesn't work for tool outputs
2. Manual prompt engineering — fragile, agent-specific, doesn't scale
3. RTK (rtk-ai/rtk) — CLI output rewriting only, no conversation/JSON/file compression
4. lean-ctx — similar scope to RTK, no reversible compression or cross-agent memory
5. Custom compression — would require building and maintaining our own compression pipeline, which is exactly what Headroom already does well

Headroom is the most comprehensive option: it covers all content types, runs locally, is reversible, and has proven accuracy on benchmarks.

Additional Context

• Headroom GitHub: https://github.com/chopratejas/headroom
• Docs: https://headroom-docs.vercel.app/docs
• PyPI: pip install headroom-ai[all] (Python 3.10+, Apache 2.0 license)
• npm: npm install headroom-ai
• Docker: docker pull ghcr.io/chopratejas/headroom:latest
• Agent compatibility: Claude Code, Codex, Cursor, Aider, Copilot CLI — all supported via headroom wrap
• Kompress-base model: https://huggingface.co/chopratejas/kompress-base (trained on agentic traces)

Headroom is already trending on GitHub and has an active community. It's a natural complement to QwenPaw's mission of being a powerful multi-agent platform — adding context compression would make QwenPaw significantly more cost-effective for heavy users.

Willing to Contribute

• I am willing to open a PR for this feature (after discussion).

[github-actions]

Welcome to QwenPaw! 🐾

Hi @K1-lihongrong, this is your 2nd issue.

We'll review your issue soon. Thank you for supporting QwenPaw!

---

Tip

⭐ If you find QwenPaw useful, please give us a Star!

Staying ahead

Star QwenPaw on GitHub and be instantly notified of new releases.

Your star helps more developers discover this project! 🐾

[K1-lihongrong]

本地实践报告：Proxy 模式成功集成

在本地（Windows 10, Python 3.12, RTX 5060 Ti）完成了从 v0.20.15 到 v0.24.0 的完整集成，以下是关键发现和操作步骤。

1. 安装

pip install headroom-ai

注意： v0.21+ 需要 Rust 编译工具链（maturin 构建后端）。Windows 上需先安装 MSVC Build Tools：

winget install Microsoft.VisualStudio.2022.BuildTools

安装后 Rust 核心 _core.cp312-win_amd64.pyd 编译成功，不再需要 HEADROOM_REQUIRE_RUST_CORE=false。

2. 启动 Proxy（非标准 OpenAI 兼容 API）

headroom proxy --port 8787 --openai-api-url <YOUR_BASE_URL> --no-telemetry

3. ⚠️ 路径拼接 Bug 修复

如果上游 API 的路径不含 /v1（如火山引擎 Ark 的 /api/coding/v3/chat/completions），Headroom 内部 build_copilot_upstream_url 会拼接出错误的 URL：

.../api/coding/v3 + /v1/chat/completions = .../api/coding/v3/v1/chat/completions ❌

修复： 修改 C:\Python312\Lib\site-packages\headroom\copilot_auth.py 中 build_copilot_upstream_url，当 base URL 已有自定义路径时自动去重 /v1：

def build_copilot_upstream_url(base_url: str, path: str) -> str:
    normalized_base = base_url.rstrip("/")
    normalized_path = path if path.startswith("/") else f"/{path}"
    if is_copilot_api_url(normalized_base) and normalized_path.startswith("/v1/"):
        normalized_path = normalized_path[3:]
    # NEW: strip /v1 when base URL has custom path
    parsed = urlparse(normalized_base)
    if parsed.path and parsed.path != "/" and normalized_path.startswith("/v1/"):
        normalized_path = normalized_path[3:]
    return f"{normalized_base}{normalized_path}"

注意： 升级 headroom-ai 后此修改会被覆盖，需重新应用。

4. QwenPaw 集成配置

# 添加 provider 指向 Headroom proxy
qwenpaw models add-provider headroom-proxy -n "headroom-token超级压缩" -u "http://localhost:8787/v1"

# 配置 API Key
qwenpaw models config-key headroom-proxy

# 添加模型
qwenpaw models add-model headroom-proxy deepseek-v4-flash

# 切换为 active model
qwenpaw models set-llm

5. 验证结果

• Proxy 健康检查：curl http://localhost:8787/livez → {"status":"healthy"}
• API 转发测试：POST /v1/chat/completions → 正常返回，无 404
• 压缩统计：curl http://localhost:8787/stats
• Dashboard：http://localhost:8787/dashboard

6. 安全配置建议

推荐使用无状态模式避免任何磁盘写入：

headroom proxy --port 8787 --openai-api-url <URL> --no-telemetry --stateless

7. 完整操作指南

已整理为本地操作指南，包含架构说明、安装配置、故障排查、安全注意事项等 9 个章节。

---

环境信息：

• OS: Windows 10 (AMD64)
• Python: 3.12.10
• Headroom: v0.24.0
• GPU: NVIDIA RTX 5060 Ti (CUDA 12.8)
• Upstream: 火山引擎 Ark Coding API

[K1-lihongrong]

Hi team, any thoughts on this feature request? I've already completed a full local integration of Headroom v0.24.0 in Proxy mode with QwenPaw on my Windows machine (detailed in my comment above), including fixing a path-joining bug for non-standard OpenAI API endpoints.

Key benefits verified locally:

• 92% token reduction on tool outputs and code search
• Zero accuracy degradation on standard benchmarks
• Drop-in proxy — no QwenPaw code changes needed for Phase 1
• Reversible compression — LLM can retrieve originals on demand via CCR

The feature has also been picked up by 3 big_model_radar newsletters today. Would love to hear if this aligns with the project roadmap, and if there's interest in a PR for Phase 1 (Proxy mode integration).

cc @x1n95c @lalaliat

[jinliyl]

Thank you for the detailed proposal and the local validation notes. This is a very useful direction, and we welcome third-party context management / memory management integrations in QwenPaw.

For a maintainable integration, we suggest starting from the existing extension points instead of wiring a solution directly into the message pipeline:

• Context management: src/qwenpaw/agents/context/base_context_manager.py
• Memory management: src/qwenpaw/agents/memory/base_memory_manager.py

A Headroom integration could be implemented as an optional context manager and/or memory manager backend by inheriting from these base classes. That would make it easier to keep the feature configurable, testable, and compatible with existing QwenPaw agents.

Proxy mode is also a reasonable first step for users who want to experiment immediately, especially since it can work through the existing provider configuration. For a QwenPaw-side PR, we would prefer the backend abstraction approach above so it can fit into the project architecture cleanly.

Thanks again for sharing the implementation details and benchmark results. We would be happy to review a PR or design draft based on these extension points.