grimoire-kit 3.17.0

Composable AI agent platform — personas, memory, workflows, and quality automation for any project.

The missing operating system for AI agents in your IDE.

Transformez votre IDE en entreprise virtuelle peuplée d'agents IA spécialisés.
_{Teams · Personas · Mémoire sémantique · Workflows · Qualité automatisée · Self-Healing}

Quick Start • Pourquoi ? • Architecture • Features • Outils CLI • Standard agentique • Concepts • Guide complet • Changelog

Pourquoi Grimoire Kit ?

Le problème Les assistants IA génériques manquent de contexte, de spécialisation et de mémoire. Chaque session repart de zéro. Aucune coordination entre les tâches. Pas de contrôle qualité. La solution Grimoire Kit déploie des équipes d'agents IA qui fonctionnent comme une vraie entreprise : Chaque agent a une persona forte et un domaine d'expertise Mémoire persistante et sémantique entre les sessions Protocoles standardisés de livraison et qualité Self-improvement — le système apprend de ses erreurs

Votre Projet │ ┌────┴────┐ │ _grimoire/ │ ← "Les bureaux" de votre │ │ entreprise virtuelle ├─────────┤ │ agents/ │ ← Les employés spécialisés │ memory/ │ ← La mémoire collective │ config/ │ ← Le règlement intérieur │ tools/ │ ← La boîte à outils (93+) └─────────┘ │ ┌────┴────────────┐ │ IDE / Copilot │ ← Interface naturelle └─────────────────┘

Quick Start

# Installation via pipx (recommandé)
pipx install grimoire-kit

# Ou via pip dans un venv
python3 -m venv .venv && source .venv/bin/activate
pip install grimoire-kit

# Initialiser un nouveau projet
grimoire init mon-projet --archetype web-app

# Depuis un projet existant
cd votre-projet/
grimoire init . --name "Mon Projet"

# Vérifier la santé du projet
grimoire doctor

# Migrer un projet v2 → v3
grimoire upgrade --dry-run   # aperçu
grimoire upgrade             # exécuter

# Cockpit local — dashboard multi-projets (arrière-plan + navigateur)
grimoire cockpit             # démarre + ouvre ; 'stop' pour arrêter

Multi-assistant — grimoire init génère des entrypoints portables (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules) pointant vers .github/copilot-instructions.md : le projet fonctionne avec Copilot, Claude Code, Codex, Gemini CLI et Cursor sans duplication. Un .mcp.json enregistre aussi le serveur MCP Grimoire (OS-neutre, via grimoire-mcp).

Cockpit local — gouverne tous tes projets

Le cockpit est un dashboard web local qui réunit tous tes projets Grimoire de la machine : portefeuille, observabilité (coûts/traces), santé CI, et gestion mémoire gouvernée (statut, lint, recherche + écritures gc/delete/sync sous confirmation). Le site est embarqué dans le paquet — aucune installation séparée.

grimoire cockpit              # démarre en arrière-plan + ouvre le navigateur
grimoire cockpit status       # ● en cours → URL  /  ○ arrêté
grimoire cockpit stop         # arrête proprement
grimoire cockpit open         # rouvre l'onglet
grimoire cockpit serve        # mode premier-plan (logs, Ctrl-C)

# Gérer les projets gouvernés
grimoire cockpit add .        # enregistre le projet courant (auto au 'grimoire init')
grimoire cockpit list         # liste les projets
grimoire cockpit remove <slug>

grimoire init enregistre automatiquement le projet scaffoldé (désactivable via GRIMOIRE_NO_COCKPIT). Le cockpit sert sur 127.0.0.1 uniquement : les actions de pilotage sont actives en local et verrouillées sur la vitrine publique — toute écriture passe par l'API Memory OS, jamais d'accès brut. Registre : ~/.grimoire/cockpit/registry.json.

Installation par besoins (commencer petit)

Plutôt que de tout activer, déclarez ce que votre projet doit faire : Grimoire résout le bon profil, les patterns à activer et les technologies à installer. On commence par l'essentiel, on grandit au besoin.

# 1. Voir les besoins, groupés par tier, avec leur empreinte (profil · patterns · services)
grimoire standard needs

# 2. Prévisualiser le plan d'un besoin sans rien écrire (profil + patterns + techno + pip)
grimoire standard plan --needs solo-prototyping

# 3. Scaffolder le projet pour ce besoin (point de départ minimal recommandé)
grimoire standard init . --needs solo-prototyping

# Assistant interactif : essentials d'abord, départ recommandé pré-sélectionné
grimoire standard init . --interactive

# Vérifier que les technologies optionnelles sont disponibles (dégradation sûre sinon)
grimoire standard doctor

Détails et matrice complète besoins → patterns → technologie : docs/agentic-standard-install-by-needs.md.

Standard agentique gouverné (depuis v3.5)

Le besoin choisi mappe sur un profil (starter → controlled → orchestrated → governed → production) qui active des patterns gouvernés vérifiables — 36 au catalogue (sécurité, gouvernance, contexte, mémoire, observabilité, runtime, qualité…). Chaque pattern pose un artefact déclaratif (_grimoire/standard/*.yaml) et un contrôle fail-closed vérifié en continu :

grimoire standard verify   # artefacts présents + conformes au profil
grimoire standard audit    # rapport de conformité
grimoire standard score    # score de conformité multidimensionnel
grimoire standard gate     # gate CI : échoue si une preuve obligatoire manque

Exemples de contrôles : blast-radius outil, séparation de privilèges controller/agent (ScrubTokenEnv), firewall d'injection de prompt, council de décision, intégrité mémoire, registre de coût LLM + SLO, contrat de guardrails (input/output/tool/model), preuve visuelle, isolation workspace, policy par environnement. Voir docs/agentic-standard-integration.md.

Installation classique (clone)

git clone https://github.com/Guilhem-Bonnet/Grimoire-kit.git
cd Grimoire-kit/
pip install -e ".[dev]"

Premier pas ? Lisez docs/concepts.md — tous les concepts expliqués avec des analogies.

Architecture

flowchart TB
  subgraph VISION[TEAM VISION]
    PM[PM]
    AN[Analyst]
    UX[UX Designer]
  end

  subgraph BUILD[TEAM BUILD]
    DEV[Dev]
    ARCH[Architect]
    QA[QA]
    SM[Scrum Master]
  end

  subgraph OPS[TEAM OPS]
    INFRA[Infra]
    SEC[Security]
    MON[Monitoring]
  end

  subgraph ENGINE[GRIMOIRE ENGINE]
    MEM[Semantic Memory]
    TOOLS[93+ Tools]
    PROTO[Protocols]
    HEAL[Self-Healing]
  end

  VISION -- Delivery Contract --> BUILD
  BUILD -- Delivery Contract --> OPS
  ENGINE -. support .-> VISION
  ENGINE -. support .-> BUILD
  ENGINE -. support .-> OPS

Règle fondamentale : aucune team ne commence sans un Delivery Contract signé de la team précédente. Zéro handoff informel.

Features

Maturité : l'icône marque les features expérimentales / R&D (fonctionnent et testées, mais surface exploratoire) ; sans icône = cœur mûr. Le différenciateur le plus mûr est le standard agentique gouverné — 36 patterns vérifiés (grimoire standard verify / audit / score / gate), cf. la section Quick Start ci-dessus.

Team of Teams Trois teams autonomes : Vision, Build, Ops. Chacune avec ses agents, workflows et contrats de livraison inter-teams.	Mémoire Sémantique Recherche vectorielle Qdrant + fallback JSON. Détection de contradictions, consolidation automatique, failure museum.	Completion Contract cc-verify.sh détecte le stack et vérifie build + tests + lint avant tout "terminé". Zéro livraison sans validation.
Boomerang Orchestration L'orchestrateur décompose, délègue en parallèle à des sous-agents, et agrège les résultats. Coordination invisible.	Session Branching Explorez plusieurs approches en parallèle — comme des branches Git, mais pour vos sessions d'agents. Diff, merge, cherry-pick.	Plan / Act / Think Switch explicite entre planification, exécution autonome et délibération profonde [THINK] pour les décisions critiques.
Self-Healing Système immunitaire : détecte les anomalies, diagnostique, et propose des réparations automatiques. Failure museum intégré.	Agent Darwinism Sélection naturelle des agents : fitness multi-dimensionnelle, évolution par générations, leaderboard, hybridation.	Stigmergy Coordination indirecte par phéromones numériques : émission, détection, amplification, évaporation. Coordination émergente.
Dream Mode Consolidation hors-session : croise mémoire, trace, décisions et failure museum pour produire des insights émergents.	MCP Server Expose Grimoire comme serveur MCP local. Compatible Cursor, Cline, Claude Desktop et tout IDE MCP.	R&D Engine v2.1 Boucle d'innovation : bandit ε-greedy à reward closed-loop, prototypage automatique, seed memory, gap-analysis.

Et bien plus encore... (15+ features avancées expérimentales)

Feature	Description
Installation par besoins	Déclarez le besoin du projet → profil, patterns et technos résolus ; commencer petit, grandir au besoin (grimoire standard needs)
Adversarial Consensus	Quorum à 3 votants + 1 avocat du diable pour les décisions critiques
Anti-Fragile Score	Mesure la résilience adaptative (recovery, learning velocity, signal trend)
Reasoning Stream	Flux structuré : HYPOTHESIS, DOUBT, ASSUMPTION, ALTERNATIVE
Cross-Project Migration	Exporte/importe learnings, rules, DNA, agents entre projets
Digital Twin	Jumeau numérique : snapshot, simulation d'impact, scénarios "what if"
Quantum Branch	Timelines parallèles : fork, compare, merge de configurations alternatives
Time-Travel	Archéologie temporelle : checkpoints, replay, restore, bisect
CRISPR	Édition chirurgicale de workflows : scan, splice, excise, transplant
Decision Log	Journal de décisions architecturales hash-chaîné (sha256, prev_hash) avec vérification d'intégrité
Mirror Agent	Neurones miroirs : observation et transfert de patterns inter-agents
Sensory Buffer	Mémoire sensorielle court terme à décroissance exponentielle
Self-Improvement Loop	Analyse les patterns d'échec → améliore le framework automatiquement
Context Budget Guard	Mesure le budget LLM consommé par chaque agent
Harmony Check	Score d'harmonie architecturale et détection de dissonances
Dashboard	Santé, entropie Shannon, Pareto Gini, activité git — en un coup d'œil

SDK Python (v3)

Le SDK v3 expose toute la puissance de Grimoire en tant que package Python installable :

pip install grimoire-kit

CLI

Commande	Description
grimoire init [path]	Initialiser un projet Grimoire
grimoire doctor	Vérifier la santé du projet
grimoire status	Afficher l'état courant
grimoire up	Réconcilier l'état avec la config
grimoire add <agent>	Ajouter un agent
grimoire remove <agent>	Retirer un agent
grimoire validate	Valider la config YAML
grimoire merge <source>	Fusionner des fichiers Grimoire
grimoire merge --undo	Annuler le dernier merge
grimoire upgrade	Migrer un projet v2 → v3
grimoire registry list	Lister les archétypes disponibles
grimoire registry search <q>	Chercher un agent

SDK — Outils programmatiques

from pathlib import Path
from grimoire.tools import (
    HarmonyCheck, PreflightCheck, MemoryLint,
    ContextRouter, ContextGuard, Stigmergy, AgentForge,
)

root = Path(".")
report = PreflightCheck(root).run()
print(report.status)  # GO / GO-WITH-WARNINGS / NO-GO

MCP Server

grimoire-mcp                    # Démarrer le serveur MCP
grimoire-mcp --transport sse    # Mode SSE pour IDE distants

10 outils exposés : init, doctor, status, memory, debugger, harmony_check, preflight, memory_lint, context_route, stigmergy_sense.

Debug runtime minimal :

grimoire debugger status
grimoire debugger claims
grimoire debugger generate

La commande generate produit un tableau de bord HTML local dans _grimoire-output/agent-debugger.html.

Archétypes

Des packs d'agents pré-configurés selon votre type de projet :

minimal Atlas · Sentinel · Mnemo Point de départ universel	web-app + agents stack auto-détectés SPA + API + DB	infra-ops Forge · Vault · Flow · Hawk Helm · Phoenix · Probe Infrastructure & DevOps	meta Atlas · Sentinel · Mnemo Auto-amélioration du kit
creative-studio Agents créatifs Design & Contenu	platform-engineering Agents plateforme Developer Experience	fix-loop Agents correctifs Bug fixing rapide	stack Gopher · Pixel · Serpent Container · Terra · Kube Auto-détection stack

# Déployer un archétype
bash grimoire-init.sh --archetype infra-ops

# Mode auto : détecte le stack → choisit les bons agents
bash grimoire-init.sh --auto

Outils CLI

93 outils Python organisés par domaine. Tous accessibles via CLI et programmables en Python.

Cognition & Mémoire — 12 outils

Outil	Description
dream.py	Consolidation hors-session, insights émergents
reasoning-stream.py	Hypothèses, doutes, alternatives structurées
sensory-buffer.py	Mémoire court terme à décroissance exponentielle
procedural-memory.py	Mémoire procédurale persistante
semantic-cache.py	Cache sémantique intelligent
semantic-chain.py	Chaînes de pensée sémantiques
memory-lint.py	Validation de cohérence mémoire
memory-sync.py	Synchronisation mémoire multi-agents
context-guard.py	Garde-fou du budget contexte LLM
context-router.py	Routage intelligent du contexte
context-merge.py	Fusion de contextes multi-sources
context-summarizer.py	Résumé intelligent de contexte

Évolution & Innovation — 10 outils

Outil	Description
r-and-d.py	Moteur R&D v2.1 avec reinforcement learning
agent-darwinism.py	Sélection naturelle, fitness, hybridation
dna-evolve.py	Évolution du DNA depuis l'usage réel
incubator.py	Incubateur d'idées et de prototypes
agent-forge.py	Génération de squelettes d'agents
agent-bench.py	Benchmarks de performance agents
mirror-agent.py	Observation et transfert de patterns
cognitive-flywheel.py	Boucle d'auto-amélioration continue
fitness-tracker.py	Suivi de fitness des agents
new-game-plus.py	Redémarrage enrichi de sessions

Résilience & Qualité — 11 outils

Outil	Description
agent-debugger.py	Vérification reality-first des preuves runtime agentiques
self-healing.py	Diagnostic et réparation automatique
immune-system.py	Détection d'anomalies et auto-réparation
antifragile-score.py	Score de résilience adaptative
early-warning.py	Système d'alerte précoce
harmony-check.py	Score d'harmonie architecturale
preflight-check.py	Validation pre-flight du projet
failure-museum.py	Catalogue structuré des échecs
bug-finder.py	Détection automatique de bugs
quality-score.py	Score de qualité multi-dimensionnel
schema-validator.py	Validation des fichiers YAML

Architecture & Workflows — 11 outils

Outil	Description
crispr.py	Édition chirurgicale de workflows
digital-twin.py	Simulation d'impact "what if"
quantum-branch.py	Timelines parallèles
time-travel.py	Checkpoints, replay, bisect
decision-log.py	Blockchain de décisions
project-graph.py	Graphe de dépendances
dashboard.py	Tableau de bord santé projet
oracle.py	CTO virtuel : SWOT, maturité
dark-matter.py	Détection de patterns cachés
desire-paths.py	Chemins de désir émergents
workflow-adapt.py	Adaptation dynamique de workflows

Coordination & Communication — 10 outils

Outil	Description
stigmergy.py	Phéromones numériques émergentes
adversarial-consensus.py	Consensus BFT avec avocat du diable
swarm-consensus.py	Consensus en essaim
nso.py	Nervous System Orchestrator
orchestrator.py	Orchestration multi-agents
nudge-engine.py	Nudges comportementaux doux
bias-toolkit.py	12 biais cognitifs documentés
mycelium.py	Réseau mycelium inter-agents
message-bus.py	Bus de messages inter-agents
rosetta.py	Traduction cross-format

Intégrations & DevTools — 10 outils

Outil	Description
grimoire-mcp-tools.py	Serveur MCP Grimoire
mcp-proxy.py	Proxy MCP multi-server
cross-migrate.py	Migration cross-projet
auto-doc.py	Synchronisation README ↔ code
gen-tests.py	Générateur de tests automatique
llm-router.py	Routage intelligent LLM
token-budget.py	Gestion budget tokens
tool-registry.py	Registre des outils disponibles
tool-advisor.py	Conseiller d'outils contextuel
observatory.py	Observatoire de métriques

Voir framework/tools/README.md pour la référence complète des 93 outils.

MCP Server

Compatible avec tout IDE supportant le Model Context Protocol :

// Claude Desktop / Cursor / Cline
{
  "mcpServers": {
    "grimoire": {
      "command": "node",
      "args": ["/chemin/vers/grimoire-kit/framework/mcp/server.js"],
      "env": { "Grimoire_PROJECT_ROOT": "/votre-projet" }
    }
  }
}

Tools exposés : get_project_context · get_agent_memory · run_completion_contract · get_workflow_status · list_sessions · get_failure_museum · spawn_subagent_task

Tests

3 957+ tests couvrant l'intégralité du framework : # Tous les tests python3 -m pytest tests/ -q --tb=short # Un fichier spécifique python3 -m pytest tests/test_dream.py -v # Smoke tests Bash (122 assertions) bash tests/smoke-test.sh

Catégorie Tests Cognition & Mémoire 380+ Évolution & R&D 350+ Résilience & Qualité 280+ Architecture & Workflows 250+ Coordination 200+ Intégrations 180+ Robustesse (fuzzing) 38 Total 3 957+

Grimoire vs. Alternatives

	CrewAI	AutoGen	LangGraph	Aider	Cline	Grimoire Kit
Local / IDE-native	—	—	—	✓	✓	✓
Team of Teams	—	—	—	—	—	✓
Delivery Contracts	—	—	—	—	—	✓
Semantic Memory	—	—	—	—	—	✓
Session Branching	—	—	~	—	—	✓
Agent Orchestration	~	✓	✓	—	✓	✓
MCP Server	—	—	—	—	—	✓
Self-Improvement	—	—	—	—	—	✓
Agent Evolution	—	—	—	—	—	✓
Plan/Act/Think	—	—	—	—	✓	✓
Failure Museum	—	—	—	—	—	✓
Anti-Fragile Score	—	—	—	—	—	✓

Structure du Kit

grimoire-kit/
├── grimoire-init.sh                     # Script d'initialisation + session-branch
├── project-context.tpl.yaml         # Template contexte projet
│
├── framework/                       # Moteur générique (ne pas modifier par projet)
│   ├── agent-base.md                   # Protocole activation + CC + Plan/Act + [THINK]
│   ├── cc-verify.sh                    # Completion Contract verifier (multi-stack)
│   ├── sil-collect.sh                  # Self-Improvement Loop collector
│   ├── teams/                          # Team manifests (Vision, Build, Ops)
│   ├── tools/                          # 93 outils Python CLI
│   ├── memory/                         # Système de mémoire à 4 niveaux
│   ├── mcp/                            # MCP Server spec
│   ├── sessions/                       # Session Branching
│   ├── workflows/                      # Boomerang, orchestration, state checkpoint
│   └── hooks/                          # Git hooks & lifecycle
│
├── archetypes/                      # 9 starter kits thématiques
│   ├── minimal/                        # Point de départ universel
│   ├── web-app/                        # Applications web
│   ├── infra-ops/                      # Infrastructure & DevOps
│   ├── stack/                          # Agents par techno (Go, Python, TS...)
│   ├── meta/                           # Auto-amélioration du kit
│   ├── creative-studio/                # Design & contenu
│   ├── platform-engineering/           # Developer Experience
│   ├── fix-loop/                       # Bug fixing rapide
│   └── features/                       # Feature-driven development
│
├── docs/                            # Documentation complète
├── tests/                           # 3 957+ tests Python + smoke tests Bash
└── src/                             # Package Python installable

Système de Mémoire

Un système à 4 niveaux pour ne jamais repartir de zéro :

graph LR
    A["Mémoire<br>Sémantique"] --> B["Learnings<br>par Agent"]
    B --> C["Contexte<br>Partagé"]
    C --> D["Failure<br>Museum"]

    A -.- E["Qdrant / JSON"]
    B -.- F["agent-learnings/"]
    C -.- G["shared-context.md"]
    D -.- H["failure-museum.md"]

    style A fill:#1a1040,stroke:#a371f7,color:#fff
    style B fill:#0d2818,stroke:#3fb950,color:#fff
    style C fill:#2d1a02,stroke:#d29922,color:#fff
    style D fill:#3d0d0d,stroke:#f85149,color:#fff

Qualité automatisée : détection de contradictions, consolidation des learnings, state checkpoints avec resume automatique.

Gestion du Kit

# Version actuelle
bash grimoire-init.sh --version

# Mise à jour depuis upstream
bash grimoire-init.sh upgrade              # met à jour framework/ et archetypes/
bash grimoire-init.sh upgrade --dry-run    # preview sans modification

# Completion Contract — vérifier avant "terminé"
bash _grimoire/_config/custom/cc-verify.sh

# Self-Improvement Loop — analyser les patterns d'échec
bash _grimoire/_config/custom/sil-collect.sh

Commandes avancées complètes

# Bench — mesurer les scores de performance des agents
bash grimoire-init.sh bench --summary
bash grimoire-init.sh bench --report
bash grimoire-init.sh bench --improve

# Forge — générer des squelettes d'agents
bash grimoire-init.sh forge --from "migrations DB PostgreSQL"
bash grimoire-init.sh forge --from-gap

# Guard — budget de contexte LLM
bash grimoire-init.sh guard
bash grimoire-init.sh guard --agent atlas --detail --model gpt-4o
bash grimoire-init.sh guard --suggest

# Evolve — DNA vivante
bash grimoire-init.sh evolve
bash grimoire-init.sh evolve --apply

# Dream — consolidation hors-session
bash grimoire-init.sh dream
bash grimoire-init.sh dream --agent dev
bash grimoire-init.sh dream --multi-project ../proj-a ../proj-b

# Consensus — protocole adversarial
bash grimoire-init.sh consensus --proposal "Utiliser PostgreSQL pour le cache sessions"
bash grimoire-init.sh consensus --history

# Anti-Fragile Score
bash grimoire-init.sh antifragile
bash grimoire-init.sh antifragile --detail --trend

# Reasoning Stream
bash grimoire-init.sh reasoning log --agent dev --type HYPOTHESIS --text "Redis > memcached"
bash grimoire-init.sh reasoning analyze

# Cross-Project Migration
bash grimoire-init.sh migrate export --only learnings,rules
bash grimoire-init.sh migrate import --bundle migration-bundle.json --dry-run

# Agent Darwinism
bash grimoire-init.sh darwinism evaluate
bash grimoire-init.sh darwinism leaderboard
bash grimoire-init.sh darwinism evolve

# Stigmergy
bash grimoire-init.sh stigmergy emit --type NEED --location "src/auth" --text "review sécurité"
bash grimoire-init.sh stigmergy landscape
bash grimoire-init.sh stigmergy trails

# NSO — Nervous System Orchestrator
bash grimoire-init.sh nso run
bash grimoire-init.sh nso retro

# Digital Twin / Quantum Branch / Time-Travel / CRISPR / Decision Log
# Mirror Agent / Sensory Buffer / R&D Engine
# → Voir framework/tools/README.md pour la doc complète

Prérequis

Requis	Version
Python	3.12+
Git	2.x+
Grimoire Framework	v6.0+

Optionnel	Pour
Node.js 18+	MCP Server
Qdrant	Recherche sémantique avancée
Ollama	LLM local

Shell Completion

# Bash
grimoire --install-completion bash

# Zsh
grimoire --install-completion zsh

# Fish
grimoire --install-completion fish

Contribuer

Les contributions sont les bienvenues ! Voir CONTRIBUTING.md pour les guidelines.

_{MIT License · Made with Grimoire by Guilhem Bonnet · Changelog}