Les agents IA consacrent une part surprenante de leur budget a relire. Les sorties d’outils repetent des metadonnees, les logs contiennent des milliers de lignes inutiles, la recherche de code renvoie des extraits qui se chevauchent et l’historique continue de croitre.
Headroom insere une couche de compression locale avant l’envoi du contexte au LLM. Il detecte le type de contenu, applique des compresseurs specialises au JSON, code, texte, images et fenetres de contexte, stabilise les prefixes pour les caches fournisseur et peut conserver les originaux pour une recuperation ulterieure.
C’est un projet Apache-2.0 avec bibliotheques Python et TypeScript, proxy compatible OpenAI, wrappers pour agents et outils MCP. L’objectif n’est pas seulement un prompt plus court, mais moins de tokens tout en preservant l’information utile.
JSON, code source, texte, images et contexte n'ont pas les memes redondances. Un seul resumeur ne convient pas partout.
Headroom reduit les sorties d'outils et de recherche tandis que CacheAligner preserve les prefixes stables pour les caches fournisseur.
CCR garde les originaux localement pendant la duree configuree et permet a l'agent de recuperer les details omis.
Ce que fait Headroom
Headroom se place entre l’agent et le fournisseur de modele. Il s’integre de quatre manieres : appel compress(messages) en Python ou TypeScript, proxy local compatible OpenAI, lancement via headroom wrap, ou outils MCP de compression, recuperation et statistiques.
Le proxy permet aux applications de tout langage de l’utiliser sans integration directe. Les wrappers ciblent Claude Code, Codex, Cursor, Aider, Copilot CLI et OpenClaw. Des integrations existent pour LangChain, Agno, LiteLLM, Strands et Vercel AI SDK.
Le pipeline de compression
Il ne s’agit pas d’un simple prompt de resume.
ContentRouter choisit le chemin. SmartCrusher traite JSON et sorties imbriquees. CodeCompressor comprend l’AST de Python, JavaScript, Go, Rust, Java et C++. Kompress-base est un modele Hugging Face entraine sur des traces d’agents. D’autres composants gerent pertinence, fenetres glissantes et images.
CacheAligner protege les caches de prompts. Les caches KV profitent de prefixes stables ; si le preprocessing reecrit constamment le debut, la compression peut detruire cette reutilisation. Headroom tente de garder ces prefixes alignes.
Le pipeline tourne localement, mais le prompt compresse part encore vers le fournisseur configure sauf si le modele est lui aussi local.
CCR : compression reversible
Toute compression retire des details. Le mecanisme CCR conserve l’original localement et offre une voie de recuperation.
Au lieu d’envoyer 10 000 lignes de logs, Headroom fournit une forme compacte avec references. Le modele peut demander une stack trace ou un enregistrement exact si necessaire.
C’est un filet de securite, pas une garantie. Le modele doit identifier le manque et appeler la recuperation. TTL, limites, permissions et suppression influencent donc correction et confidentialite.
Demarrage
L’installation Python complete exige Python 3.10+ :
pip install "headroom-ai[all]"
headroom wrap codex
headroom perf
Ou lancez le proxy :
headroom proxy --port 8787
Le package TypeScript est disponible sur npm, des extras Python evitent d’installer chaque fonctionnalite, et des images Docker sont publiees.
Commencez par un workload observable comme des logs ou une recherche verbeuse. Comparez le succes avant/apres avant d’etendre a l’historique et la memoire partagee.
Lire correctement les benchmarks
Le depot annonce 92 % de reduction pour une recherche de code de 100 resultats, 92 % pour un incident SRE, 73 % pour le tri d’issues GitHub et 47 % pour l’exploration d’un codebase. Il publie aussi de petits echantillons de benchmarks ou la precision est maintenue ou amelioree.
Ces resultats montrent une possibilite, pas une remise universelle de 60 a 95 %. Le ratio depend de la redondance, de la requete, du modele et de la fidelite exigee. Un log repetitif se compresse mieux qu’un code compact ou un caractere change le sens.
Reproduisez l’evaluation sur vos propres traces. Mesurez correction, appels d’outils, latence, cache fournisseur et frequence de recuperation avec les tokens.
Tokens d’entree et de sortie
La plupart des fonctions reduisent l’entree. Un output shaper optionnel agit sur la reponse en orientant la concision et en diminuant l’effort de raisonnement sur les reprises routinieres apres outils. Il est desactive par defaut.
Cela peut supprimer preambules et repetitions, mais change le comportement. Utilisez un groupe temoin : une reponse plus courte n’est pas automatiquement equivalente.
Le projet distingue les economies contrefactuelles estimees, avec intervalle de confiance, des comparaisons mesurees via holdout. Cette distinction est rigoureuse car on n’observe jamais les deux reponses possibles dans la meme conversation.
Memoire inter-agents et apprentissage
Headroom propose une memoire partagee compressee avec provenance et deduplication. On peut passer de Claude a Codex sans recopier tout l’historique.
headroom learn analyse les sessions echouees et propose des corrections pour CLAUDE.md, AGENTS.md et GEMINI.md. Ces regles doivent etre revues : un echec peut venir d’un incident transitoire ou d’une mauvaise formulation, pas d’un principe reutilisable.
Confidentialite et securite
Local-first limite l’exposition a un service de compression heberge, mais Headroom traite les prompts et stocke des originaux recuperables. Il faut definir emplacement, TTL, chiffrement, controles d’acces, isolation entre utilisateurs, telemetrie, acces reseau et comportement en cas d’echec.
Les environnements d’entreprise peuvent aussi exiger des certificats approuves ou des copies hors ligne des assets ONNX Runtime et Hugging Face.
Quand l’utiliser ou l’eviter
Headroom convient aux agents consommant sorties d’outils, recherches de code, logs, chunks RAG repetes ou longs historiques. Il est interessant quand la neutralite fournisseur et la recuperation reversible comptent.
Evitez-le si la compaction native suffit, si aucun processus local ne peut tourner, si les prompts sont deja compacts ou si le workload ne tolere aucun preprocessing avec perte. Les usages reglementes exigent une evaluation metier.
Conclusion
Headroom traite le contexte comme un pipeline de donnees plutot qu’un tampon texte infini. Il route chaque type vers un compresseur specialise, preserve la stabilite des caches et garde une voie vers les originaux.
La cible n’est pas le ratio maximal, mais le plus petit contexte qui conserve succes, recuperabilite, latence, confidentialite et auditabilite.
Deployeez d’abord en shadow ou avec holdout, reproduisez les benchmarks sur vos traces, examinez les echecs de recuperation et laissez la qualite mesuree determiner la compression acceptable.