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 — l’interface est en espagnol, voici donc les noms que vous verrez réellement : Vault (vos notes, chacune avec sa couleur : recherche BM25, filtres, plage de dates de création et pagination), Vigencia (validité — ce qui a expiré ou va expirer, avec un bouton de revalidation), Agentes (agents — rédigez et versionnez le AGENTS.md / CLAUDE.md que vos agents lisent au démarrage), Grafo (graphe — comment les notes se relient et comment le rouge se propage), Revisión (revue — liens cassés, notes périmées, contradictions), Guard et Veracidad (véracité).

Vous pouvez aussi connecter un dépôt GitHub et le parcourir depuis la visionneuse : arborescence classique, ou carte en graphe colorée par confiance montrant quelles parties du code ont des connaissances vérifiées derrière elles.

Tout l’opérationnel vit dans le menu kebab — sans terminal : Connexions MCP (émettre et révoquer des jetons nommés par application, avec expiration et mode lecture seule), Corbeille, Audit MCP (quel jeton a appelé quel outil, quand, depuis quelle IP — téléchargeable et élagable), Racines de preuve, Exporter (sauvegarde), Instructions pour les agents 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.

Des preuves qui sont revérifiées

La preuve d’une note n’est pas une impression : c’est une référence que COGO peut aller vérifier à nouveau. Au-delà des chemins locaux, deux schémas la rendent durable :

evidence:
  - kind: command_output
    ref: github://acme/api@main/internal/db.go:88   # ancrée au SHA du blob
  - kind: direct_log
    ref: artifact://9f2a…                           # adressée par contenu, immuable

Les références GitHub sont ancrées au SHA du blob. Cela redonne ses dents au moteur de couleur sur une instance hébergée (qui n’a aucune copie de travail de votre code) et active la fraîcheur ancrée à git : la note reste verte tant que le fichier cité ne change pas, et passe au jaune dès qu’il change. Citez un commit fixe et la preuve devient immuable.

Les artefacts (stash) sont stockés sous le SHA-256 de leur contenu, sur disque ou sur Cloudflare R2. Comme la clé est le hash, verify le recalcule au lieu de faire confiance à une citation qui pourrit. Un scanner de secrets s’exécute avant tout stockage et refuse par défaut : un identifiant fuité n’est jamais immortalisé.

Plusieurs agents, un seul vault

Avec MCP sur HTTP et un jeton, des agents sur des machines différentes partagent un vault :

• recall est le curseur qui transforme le vault d’archive en canal. Appelé sans argument, il renvoie la mémoire porteuse (le mandat, les décisions vertes) et un curseur ; rendez ce curseur en since et vous n’obtenez que ce qui a changé.
• lease prend un droit limité dans le temps sur une ressource avant un travail risqué et non idempotent — migration, déploiement, édition en masse — pour que deux agents ne le lancent pas en même temps.
• Chaque note enregistre qui l’a capturée, et la visionneuse filtre par agent.
• Le journal d’audit enregistre quel outil chaque jeton a appelé, quand et depuis quelle IP. Il se télécharge et s’élague, entrée par entrée ou en entier.

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