🧬 HCS : des fichiers de contexte pour l'IA qui citent leurs sources et se vérifient

npm install -g @oufrid/hcs-cli
hcs check project.hcs

Le problème

Tous ceux qui travaillent avec des agents IA écrivent des fichiers de contexte : AGENTS.md, CLAUDE.md, résumés de session, notes de projet. Je le fais moi-même sur ce site et sur mes applications Android. Ces fichiers ont trois angles morts.

1. Personne ne sait ce que le résumé a perdu. On résume un projet de dizaines de milliers de tokens en quelques centaines de lignes, et aucun chiffre ne dit ce qui a disparu.
2. Ils vieillissent en silence. Le code change, le fichier de contexte non. Le modèle croit alors quelque chose de faux, sans que rien ne le signale.
3. Ils ne sont pas traçables. Quand le fichier affirme quelque chose, rien n'indique d'où cela vient ni où aller vérifier.

J'en parle plus longuement, avec les leviers qui ne demandent aucun outil, dans le guide Optimiser le contexte d'une IA. HCS s'attaque aux trois problèmes à la fois.

Comment HCS fonctionne

Un fichier .hcs contient des affirmations courtes et numérotées sur un projet. Chacune porte une ancre vers sa source, avec une empreinte.

#c7 Shipping costs a base fee of 25 plus 4 per kg, and parcels over 30 kg are refused.
  > src/rates.ts::shippingFee #9c1e0f2a3b4d
#c8 Refunds are accepted within 14 days of delivery.
  > docs/policy.md::"Refund policy" #77aa01b2c3d4

Trois propriétés en découlent.

• Traçable. Chaque affirmation cite sa source : une fonction, une classe, un titre de document ou une plage de lignes. Le modèle sait où lire au lieu de deviner, et via MCP il peut ouvrir cette source à la demande.
• Vérifiable. Chaque citation porte une empreinte. hcs check détecte les affirmations périmées, sans modèle, et s'utilise en intégration continue. Il ignore le reformatage, suit le code déplacé (même dans un autre fichier) et échoue quand le sens a pu changer.
• Mesuré. Le fichier embarque des questions de test dont la réponse figure mot pour mot dans la source. hcs score donne la fidélité du contexte pour un modèle donné, avec un intervalle de confiance, une comparaison sans contexte et le taux de réponses où le contexte a induit le modèle en erreur.

Le compilateur demande au modèle des affirmations appuyées chacune par une citation exacte, puis jette toute affirmation dont la citation ne se trouve pas réellement dans la source. C'est un garde-fou mécanique contre les résumés inventés. Les affirmations écrites à la main restent possibles, et ce sont souvent les plus précieuses : une règle comme « ne jamais journaliser un numéro de carte complet » ne se déduit pas du code.

HCS fonctionne avec n'importe quel matériau (code dans tous les langages, documentation, notes, conversations) et n'importe quel modèle : OpenAI, Anthropic, Gemini, Groq, OpenRouter, Mistral, ou un modèle local via Ollama.

Ce que les mesures montrent

J'ai voulu des chiffres, pas une impression. Le protocole complet et les résultats bruts sont dans le rapport de benchmark. Chaque contexte a le même budget de 2 000 tokens, et les questions de test ont été écrites à part, par des appels qui n'ont jamais vu le contexte HCS.

• Sur les trois nouveaux dépôts (express, requests, logrus), le protocole et le critère de réussite ont été enregistrés avant tout appel au modèle. Écart avec le résumé naïf : +18,9 points, intervalle de confiance à 95 % entièrement au-dessus de zéro.
• Avec un second modèle d'une autre famille (ministral-14b chez Mistral), l'écart tient : +18,8 points sur les cinq premiers dépôts, +16,1 points sur les trois nouveaux.
• Lire la source compte encore plus que la forme du résumé. Quand le modèle peut ouvrir la source citée par les affirmations, HCS atteint 58,3 % sur les cinq premiers dépôts et 62,8 % sur les trois nouveaux.

Ce qui n'a pas marché, ou pas encore, figure dans le même rapport :

• hcs refine, qui ajoute des affirmations pour combler les questions ratées, n'a pas amélioré la fidélité sur les questions mises de côté, et l'a même légèrement dégradée sur un dépôt. C'est documenté comme une expérience.
• Les alertes de dépendances (seal --deps) : sur l'historique du projet, 17 alertes sur 18 n'étaient pas nécessaires. Attendez-vous surtout à de fausses alertes.
• La détection d'injection de prompt attrape 90 % des attaques du corpus sur lequel elle a été réglée, mais seulement 47 % (7 sur 15) sur un jeu tenu à l'écart. C'est un filtre, pas une garantie.
• Limites du protocole : un seul modèle a compilé les fichiers et écrit les questions, un seul budget a été testé, 24 à 30 questions par dépôt.

Essayer en 5 minutes

Il faut Node.js 18.17 ou plus récent. Aucune dépendance d'exécution.

npm install -g @oufrid/hcs-cli          # installe la commande hcs
hcs init                                # crée un fichier vide pour des affirmations écrites à la main
hcs check project.hcs                   # vérifie les ancres, sans modèle

Pour compiler un contexte à partir de votre projet, une clé gratuite suffit (Gemini ou Groq), ou un modèle local :

export GEMINI_API_KEY=...               # ou GROQ_API_KEY, ou Ollama en local
hcs models gemini                       # liste les modèles disponibles pour votre clé
hcs compile --model gemini:<modèle> --rpm 8 -o project.hcs
hcs render project.hcs --decoder --budget 2000   # à coller dans n'importe quel chat

Le tutoriel va de l'installation à un contexte vérifié et noté en une dizaine de minutes, sur un petit projet d'exemple. Une version Python du cœur déterministe existe aussi : pip install hcs-format.

Le connecter à Claude Code, Cursor ou VS Code

hcs serve project.hcs est un serveur MCP (Model Context Protocol). L'agent lit d'abord quelques centaines de tokens d'affirmations vérifiées, puis ouvre la source exacte derrière une affirmation seulement quand il en a besoin. Il n'a jamais à lire tout le dépôt.

Avec Claude Code, dans le dossier du projet :

claude mcp add hcs -- hcs serve project.hcs

Configuration type pour les autres clients :

{
  "mcpServers": {
    "hcs": { "command": "hcs", "args": ["serve", "project.hcs"] }
  }
}

Seul Claude Code a été testé jusqu'ici, avec une session enregistrée. Les réglages pour Claude Desktop, Cursor et VS Code sont dans la documentation MCP. Pour comprendre MCP lui-même, voir mon guide Connecter une IA à vos outils.

Sécurité et vie privée

• Ce qui ne quitte jamais votre machine : check, seal, render, stats, impact, audit et le serveur MCP n'appellent ni modèle ni réseau.
• Ce qui envoie du texte au fournisseur choisi : compile, score, curve, compare et snapshot. Certaines offres gratuites peuvent utiliser vos prompts pour améliorer leurs produits. N'y compilez pas de code privé, ou utilisez un modèle local.
• Bac à sable : le serveur MCP ne peut rien lire en dehors du dossier du projet, liens symboliques compris.
• Injection de prompt : le texte qui ressemble à une consigne adressée à une IA est marqué suspect et n'est jamais affiché par défaut. Comme dit plus haut, la détection repose sur des motifs et laisse passer environ la moitié des attaques nouvelles.

Le modèle de menace complet est dans SECURITY.md.

Ce que HCS n'est pas

• Pas sans perte. Aucun résumé ne l'est. HCS mesure la perte au lieu de la cacher.
• Pas une compression magique. Les affirmations sont des phrases ordinaires. Ce qui économise des tokens, c'est le choix de ce que l'on garde.
• Pas toujours plus petit. Sur un tout petit projet, le contexte peut être plus long que la source elle-même. HCS devient utile quand le matériau dépasse ce que l'on veut mettre dans un prompt.
• Pas une note sans juge. Les réponses exactes sont notées mécaniquement, les autres par un modèle juge. Utilisez un juge d'une autre famille de modèles.
• Pas une preuve de vérité. Un fichier valide prouve que chaque citation existait dans la source et que la source n'a pas changé depuis. Il ne prouve pas que la reformulation est fidèle, ni que la source elle-même est juste.

Statut et feuille de route

• Le format est stable : SPEC 1.0, publiée le 22 octobre 2026. Les fichiers écrits aujourd'hui resteront lisibles sur toute la série 1.x.
• L'outil est expérimental : version 0.3.0, publiée sur npm (@oufrid/hcs-cli) et PyPI (hcs-format). Une seconde implémentation en Python passe la même suite de conformité que la version TypeScript.
• La feuille de route suit quatre phases : fiabilité, standardisation, capacités nouvelles, écosystème. Elle est publique dans ROADMAP.md.

J'ai conçu HCS et dirigé son développement, qui a été réalisé avec un agent de code IA (Claude Code). L'histoire du projet, les choix et les mesures sont racontés dans l'article Vos fichiers de contexte IA vieillissent en silence.

Contribuer

Les retours sont bienvenus, en particulier :

• des résultats de benchmark sur de vrais projets et de vrais modèles ;
• des cas de localisation de symboles pour d'autres langages ;
• des remarques sur la spécification, qui évolue par un court processus de RFC.

Tout se passe sur GitHub, avec un guide de contribution. Pour signaler une faille, utilisez le bouton privé de signalement de vulnérabilité de GitHub, pas une issue publique.

Questions fréquentes

HCS remplace-t-il AGENTS.md ou CLAUDE.md ?

Non. HCS peut cohabiter avec eux. La commande hcs audit AGENTS.md vérifie les références cassées d'un fichier existant, et peut même mesurer ce qu'il transmet réellement à un modèle avec les mêmes questions vérifiées.

Mon code est-il envoyé quelque part ?

Seulement si vous lancez une commande qui appelle un modèle (compile, score, compare, snapshot), et uniquement au fournisseur que vous choisissez. La vérification, le rendu et le serveur MCP fonctionnent entièrement en local. Avec Ollama, rien ne sort de votre machine.

Faut-il payer un modèle pour l'utiliser ?

Non. Toute la chaîne a été testée sur les offres gratuites de Gemini et de Groq, et avec des modèles locaux. En cas de quota épuisé, la compilation garde son travail et reprend au lancement suivant. Les petits modèles locaux sur processeur ont toutefois donné des résultats faibles.

Quelle confiance accorder au score de fidélité ?

C'est une mesure sur un petit échantillon, toujours affichée avec son intervalle de confiance à 95 %. Avec une douzaine de questions, cet intervalle peut couvrir 50 points. Le score dépend du modèle qui répond, du juge et des questions : utilisez un juge d'une autre famille et comparez toujours à l'absence de contexte.

Le format va-t-il encore changer ?

Le format est figé en version 1.0 : syntaxe des ancres, empreintes, statuts de vérification. Les lecteurs acceptent aussi toutes les versions antérieures. Les évolutions passent par une RFC publique. C'est l'outil en ligne de commande, en version 0.3.0, qui reste expérimental.