Tetardtek-Cortex/brain-template
1
0
Fork 0
Code Pull Requests Activity
Files
78323a00946fa125a4c7b33f49007a65578b9da3
brain-template/docs/sessions.md
Tetardtek 8244a07881 feat: brain-engine + brain-ui + docs — template full stack standalone 
- brain-engine: server, embed, search, RAG, MCP, start.sh (standalone)
- brain-ui: source React complète, build.sh, DocsView avec tier colors
- docs: 14 pages guides humains (getting-started, architecture, sessions, workflows, agents, vues tier)
- brain-compose.yml v0.9.0: tier featured ajouté, sessions/agents par tier, coach_level, API key schema
- DISTRIBUTION_CHECKLIST v1.2: brain-engine + brain-ui + docs dans la checklist
2026-03-20 20:25:40 +01:00

9.0 KiB
Raw Blame History

Guide des sessions — Brain

Ce guide explique comment fonctionnent les sessions du brain. Pour la reference technique complete : wiki/session-matrix.md

C'est quoi une session ?

Une session est une conversation avec le brain, du premier message au dernier commit. Chaque session a un type qui determine quels agents sont charges, quels fichiers sont accessibles, et ce que le brain peut ecrire.

Le cycle de vie est simple : boot → work → close.

  • Boot : le brain detecte le type de session, charge le contexte minimum necessaire
  • Work : tu travailles, les agents pertinents sont disponibles
  • Close : les scribes capturent les metriques, mettent a jour les todos, et ferment le claim BSI

Le brain demarre toujours en session. Si tu ne declares pas de type, tu es automatiquement en session navigate — la plus legere. C'est le lobby : tu peux regarder autour, poser des questions, et quand tu veux travailler, tu escalades vers le bon type.

Isolation et escalade

Chaque type de session a un perimetre strict. Le brain ne deborde jamais :

  • En navigate : lecture seule, orientation — pas de code, pas de modification brain
  • En work : code projet — pas de modification du brain (kernel, agents)
  • En brain : modification du brain — pas de code projet
  • En edit-brain : modification kernel — gate humain obligatoire

Si tu demandes quelque chose qui depasse le scope de ta session, le brain te propose d'escalader :

"Cette action depasse le scope navigate — brain boot mode work/superoauth pour continuer."

Tu confirmes, le brain ferme la session legere et ouvre la bonne. Deux claims dans l'historique, tout est trace.

Les types de sessions

Coder & produire

  • work — Developpement projet → brain boot mode work/<projet>
  • debug — Investigation bug → brain boot mode debug/<projet>
  • deploy — Ship en prod, config VPS → brain boot mode deploy/<projet>
  • infra — Maintenance VPS, monitoring → brain boot mode infra
  • urgence — Production down, hotfix → brain boot mode urgence

Construire le brain

  • brain — Travailler sur les agents, todos, focus → brain boot mode brain
  • edit-brain — Modifier le kernel (gate humain) → brain boot sudo
  • kernel — Lire le kernel sans le modifier → brain boot mode kernel
  • pilote — Session longue, copilotage actif → brain boot mode pilote

Explorer & reflechir

  • brainstorm — Explorer, challenger, structurer → brain boot mode brainstorm/<sujet>
  • navigate — Vue d'ensemble legere → brain boot navigate
  • coach — Progression, reflexion strategique → brain boot mode coach
  • capital — Bilan, objectifs, CV → brain boot mode capital
  • audit — Analyse lecture seule, rapport → brain boot mode audit/<projet>
  • handoff — Reprendre une session precedente → brain boot mode handoff/<id>

Comment ca se lance — les 4 couches

Le brain ne charge pas tout d'un coup. Il utilise 4 couches, comme des pelures d'oignon :

L0 — Toujours charge (~5%)
     KERNEL.md, PATHS.md, brain-compose.local.yml
     → L'identite du brain. Non negociable.

L1 — Selon le type de session (~10-18%)
     Les agents et fichiers specifiques a CE type de session.
     → work charge debug + coach, deploy charge vps + ci-cd, etc.

L2 — Selon le projet (~5-15%)
     Si tu declares un projet dans ta commande, ses fichiers sont charges.
     → projets/<nom>.md + todo/<nom>.md

L3 — Sur demande (0% au boot)
     Tout le reste. Charge en cours de session si tu en as besoin.
     → "Charge l'agent testing" → L3 → disponible

Resultat : ~20-30% du contexte utilise au boot, au lieu de 80%. La session demarre vite.

Ce que chaque session peut / ne peut pas faire

Sessions projet — ecrivent dans le code, pas dans le brain :

  • work · debug · deploy · infra · urgence — ecriture projet uniquement

Sessions brain — ecrivent dans le brain, pas dans le code :

  • brain — agents, profil (gate humain sur le kernel)
  • edit-brain — ecriture kernel autorisee (gate humain obligatoire)
  • kernel — lecture seule, aucune ecriture

Sessions mixtes :

  • pilote — ecriture projet + brain (gates architecturaux sur les forks irreversibles)

Sessions legeres — ecriture limitee ou aucune :

  • brainstorm — todo seulement
  • navigate — aucune ecriture
  • coach — progression seulement
  • capital — profil seulement
  • audit — rapport seul
  • handoff — herite du handoff

Ce qui se passe quand tu fermes une session

Quand tu dis fin, on wrappe ou c'est bon, le brain lance une sequence de fermeture automatique :

1. Metriques       → metabolism-scribe capture tokens, duree, commits, health_score
2. Todos           → todo-scribe ferme les ✅ et capture les nouveaux ⬜
3. Wiki            → wiki-scribe ajoute les nouveaux termes si besoin
4. Brain update    → scribe met a jour focus, projets, agents si changement
5. Coach           → rapport de session (sauf en navigate, deploy, infra, urgence, audit)
6. BSI close       → le claim est ferme, la session est tracee

Pas toutes les etapes a chaque fois. Le brain adapte selon le type de session :

  • navigate : juste metriques + BSI close (session legere)
  • work : metriques + todos + scribe + coach + BSI close (session complete)
  • brainstorm : metriques + todos emerges + BSI close (pas de commit attendu)
  • pilote : tout — metriques + todos + wiki + scribe + coach + BSI close

Le coach ne fait pas de rapport en session silencieuse (navigate, deploy, infra, urgence, audit) — il n'intervient que si risque critique.

Le metabolisme — ce qu'on mesure

A la fin de chaque session, le metabolism-scribe capture des metriques :

  • tokens_used : combien de tokens consommes
  • context_peak : pic d'utilisation du contexte (%)
  • duration_min : duree de la session
  • commits : nombre de commits produits
  • todos_closed : todos coches pendant la session
  • health_score : score calcule — se lit en tendance sur 7 jours

Le score n'est pas un jugement. Il detecte les patterns :

  • Score bas + context haut = session qui consomme sans produire
  • Score bas sur un brainstorm = normal (pas de livrable attendu)
  • Ratio use-brain/build-brain < 0.5 sur 7j = trop de travail sur le brain, pas assez de production

Les 3 profils de scoring

Toutes les sessions ne se mesurent pas pareil :

Profil Sessions Ce qui compte
Productif work, deploy, debug, infra, urgence Todos fermes, commits
Constructif brain, edit-brain, kernel, pilote Fichiers kernel touches, ADRs
Exploratoire brainstorm, navigate, coach, capital, handoff, audit Insights captures, duree

Les tiers

Le brain a un systeme de tiers qui controle l'acces aux agents et aux sessions :

🟢 free — 6 sessions (work, debug, brainstorm, brain, navigate, handoff). Pas de cle API. Le brain fonctionne quand meme.

🔵 featured — +2 sessions (coach, capital). Progression personnelle, RAG, coaching complet.

🟠 pro — +4 sessions (audit, deploy, infra, urgence). Tous les agents metier : code-review, security, vps, ci-cd, monitoring.

🟣 full — +3 sessions (kernel, edit-brain, pilote). Tous les agents, acces kernel complet, owner du brain.

→ Detail complet : voir Agents & Tiers dans la sidebar.

FAQ

Comment creer un nouveau type de session ?

  1. Creer contexts/session-<type>.yml avec le format L0/L1/L2/L3
  2. Declarer le tier_required et le context_target
  3. Ajouter le type dans brain-compose.yml > feature_sets > le bon tier
  4. Ajouter le handoff_default dans manifest.yml
  5. Ajouter la zone access dans KERNEL.md
  6. Mettre a jour wiki/session-matrix.md

Comment escalader depuis navigate ?

Dis simplement brain boot mode <type> (ex: brain boot mode work/superoauth). Le brain ferme navigate et ouvre la session demandee. Tu peux aussi decrire ce que tu veux faire — le brain detectera le debordement et proposera le bon type.

Pourquoi ma session est en mode conserve ?

Le mode conserve se declenche quand :

  • Le contexte depasse 70% ET le health_score est < 1.0
  • Le contexte a la fermeture depasse 60%
  • C'est une session urgence (conserve automatique)

En mode conserve, le brain cible < 40% de contexte et ne charge que l'essentiel.

C'est quoi un handoff ?

Un handoff est un fichier qui capture l'etat d'une session pour qu'une autre puisse reprendre. Niveaux :

  • NO : pas de handoff — la prochaine session repart de zero (cold start)
  • SEMI : Layer 0 + position
  • SEMI+ : SEMI + focus + projet
  • FULL : tout le contexte de reprise

Liens

  • Reference technique : wiki/session-matrix.md — matrice complete avec tous les champs
  • Cycle de vie : wiki/session-lifecycle.md — boot → work → close en detail
  • Context loading : wiki/context-loading.md — architecture BHP L0-L3
  • Metabolisme : profil/metabolism-spec.md — formules et seuils
View Git Blame Copy Permalink