Documentation de COGO

COGO, ce sont trois visages sur une même logique : un visualiseur web pour tout le monde, un serveur MCP pour vos agents, et une CLI pour les utilisateurs avancés — le tout dans le même binaire Go unique.

Visage	Pour qui	Comment
Visualiseur web	tout le monde	cogo serve -http :8080 → navigateur (Coffre · Fraîcheur · Pack · Graphe · Revue · Guard · Véracité)
MCP	votre agent (Claude, Codex, Cursor, Gemini…)	cogo serve (stdio) ou /mcp via HTTP — outils : pack search open capture verify archive restore remove guard xray
CLI	utilisateurs avancés	cogo add · pack · search · stale · verify · lint · agents

Comment la couleur est calculée

confiance = min( preuves , fraîcheur , dépendance la plus faible , contradiction )

Une note n’est verte que lorsque rien ne la tire vers le bas : une preuve observée, une vérification qui a réussi, de la fraîcheur, toutes ses dépendances vertes et aucune contradiction. Chaque couleur porte son color_reason : vous pouvez donc toujours auditer pourquoi elle a fini ainsi.

• La preuve fixe le plafond : observée (un log, une commande, un test, un fichier), elle peut atteindre le vert ; rapportée ou inférée, elle plafonne au jaune ; aucune preuve, c’est le rouge.
• La fraîcheur décroît selon le type : une commande dure 30 jours ; une décision d’architecture, 180.
• Modifier une note change la couleur — c’est le but. Le visualiseur recalcule la couleur en direct pendant que vous tapez : ajoutez une preuve observée et elle verdit ; changez l’affirmation et elle repasse à « re-vérification nécessaire » ; appuyez sur verify (« je l’ai vérifié ») et elle passe au vert.

Anatomie d’une note

---
id: fisherboy-redis-hostname
type: bug                 # decision|bug|runbook|architecture|constraint|command|mistake
project: fisherboy
evidence:
  - kind: direct_log      # observée → peut atteindre le vert
    ref: "api log 2026-06-27T14:03Z: connect OK to redis:6379"
check:
  test: "lire l'env effectif du worker ; sonder la connectivité vers fisherboy-redis:6379"
  status: not_run         # passed | failed | not_run
last_verified: 2026-06-27
depends_on: [fisherboy-redis-topology]
# ---- calculé par COGO · ne pas modifier ----
confidence: yellow
color_reason: "preuve observée mais la vérification n'a pas réussi"
---

## Claim
Le worker échoue probablement parce qu'il ne parvient pas à résoudre le nom d'hôte interne de Redis.

Le coffre Markdown est la source unique de vérité : portable, diffable, et il survit à l’outil. Tout le reste est un client léger ou un cache reconstructible.

Le visualiseur web

Les onglets : Coffre (vos notes, chacune avec sa couleur), Fraîcheur (ce qui expire, avec un bouton de revalidation), Pack (assembler les notes d’un sujet en un bloc de contexte coloré à coller à une IA), Graphe (comment les notes se relient), Revue (liens cassés, notes expirées, contradictions), Guard et Véracité.

Tout l’opérationnel vit dans le menu kebab du visualiseur — aucun terminal nécessaire : Connexions MCP (émettre/révoquer des jetons nommés par application, avec expiration et un mode lecture seule), Corbeille (restaurer ou supprimer définitivement), Audit MCP (qui a appelé quel outil, quand, depuis quelle IP), Racines de preuves (contre quel dossier se résolvent les preuves de chaque projet), Export (sauvegarde) (tout le coffre en zip, sans secrets), Instructions d’agent (générer le AGENTS.md/CLAUDE.md qui enseigne le protocole à votre agent) et Réglages · Modèle d’IA.

Guard, pas à pas

Guard répond à une seule question : « ce tour du modèle est-il en train de me pousser ? »

1. Déclarez votre mandat (une seule fois) : votre objectif et vos lignes rouges (« je ne démissionne pas sans une autre offre signée »). Il est stocké dans le coffre. Sans mandat, manipulation et persuasion légitime sont indiscernables — COGO se contente alors de nommer les techniques, sans verdict.
2. Collez le tour (et la conversation antérieure, un message par ligne : U: vous, M: le modèle) → une radiographie colorée : vert — aucun signal ; jaune — persuasion présente, ou cela touche votre ligne rouge ; rouge — il y a de la mécanique, ou il y a des reçus.
3. Les reçus sont le super-pouvoir : comme COGO voit la transcription, quand le modèle nie ce qu’il a dit (« je ne vous ai jamais dit de démissionner »), COGO retrouve le tour où il l’a BEL ET BIEN dit et montre les deux citations, côte à côte. Le gaslighting cesse d’être votre parole contre la sienne.
4. Chaque tactique détectée arrive avec ses questions critiques et sa contre-mesure — le moteur ne censure pas le modèle : il vous inocule. Il montre ; vous décidez.

L’ontologie derrière : 108 techniques de manipulation distillées de six disciplines offensives — la persuasion (Cialdini, Kahneman), l’interrogatoire policier et militaire (technique Reid, Army FM 2-22.3, Scharff), la négociation (Harvard, Voss), la coercition et la réforme de la pensée (Lifton, Biderman), la manipulation émotionnelle (gaslighting, DARVO, FOG) et la rhétorique/propagande (Frankfurt, Grice, Walton) — chacune avec sa source réelle, son allure dans un chat, et sa contre-mesure.

La règle de fer

Aucun modèle ne décrète « vous êtes manipulé ». Les dents sont déterministes (marqueurs, reçus, trajectoire) ; les modèles ne font que proposer — et chaque proposition est vérifiée contre le texte littéral ou écartée. Avec un modèle connecté, deux paliers optionnels apparaissent : les propositions structurelles (des motifs qu’aucun dictionnaire ne voit) et le steelman adversarial — un autre modèle qui défend délibérément le côté que le tour ne vous a pas montré. Le cadre théorique est dans docs/fundamento-teorico.md.

Véracité : du solide, ou de la fumée ?

Le jumeau de Guard. Là où Guard demande « est-il en train de me pousser ? », l’onglet Véracité (outil MCP xray) demande « cette réponse tient-elle debout ? ». Collez la réponse d’un modèle et COGO la radiographie phrase par phrase, de façon déterministe, sans aucun modèle : il mesure l’engagement (nuancé ou affirmé avec force), la preuve (observée, rapportée ou aucune) et si c’est falsifiable (une opinion déguisée en fait). Une affirmation forte et sans fondement ressort rouge ; une affirmation solide avec preuve observée, mieux. Document de conception : docs/motor-veracidad.md.

La CLI

cogo init                 # créer un coffre
cogo add nota.md          # valider, calculer la couleur, stocker (stdin sans fichier)
cogo pack "redis"         # construire un contexte coloré pour un sujet (dégrade le rouge)
cogo search "worker"      # lister : couleur · id · résumé (sans les corps)
cogo stale                # ce qui est expiré ou sur le point de l'être
cogo verify <id>          # « je l'ai vérifié » : revalider et recolorer
cogo lint                 # liens cassés, notes expirées, contradictions (si un modèle est configuré)
cogo agents --claude      # générer le CLAUDE.md/AGENTS.md qui enseigne le protocole à un agent
cogo serve -http :8080    # visualiseur web + serveur MCP via HTTP
cogo serve                # serveur MCP via stdio

Accessoires optionnels (désactivés par défaut)

COGO est 100 % déterministe et autonome sans rien de tout cela. Chaque accessoire s’active par variable d’environnement et ne touche jamais le cœur :

Accessoire	Activé avec	Pour
Modèle d’IA (OpenRouter, Ollama, DeepSeek…)	COGO_LLM_BASE_URL + COGO_LLM_MODEL (ou Réglages dans l’interface)	détecter des contradictions entre notes + les paliers optionnels de Guard
Juge fort indépendant	COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL	pour que le steelman de Guard ne partage pas son cerveau avec le proposeur
Nettoyage Anonimal	ANONIMAL_URL	garder secrets et données personnelles hors du coffre
Connexion Lockatus (OIDC)	AUTH_MODE=federado	se fédérer avec la Suite Escriba

Note

Le détail complet vit dans le dépôt : le manuel pour débutants, le guide de déploiement complet (chaque variable, sauvegarde, durcissement) et les documents de conception des moteurs de véracité et d’autonomie.

Voir sur GitHub