Skip to main content

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

Project description

Grimoire Kit — Composable AI Agent Platform

CI PyPI Docs Version License Tests Python Tools Ruff Mypy Codecov

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 StartPourquoi ?ArchitectureFeaturesOutils CLIConceptsGuide completChangelog



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
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

graph 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 -.- VISION
    ENGINE -.- BUILD
    ENGINE -.- OPS

    style VISION fill:#1a1040,stroke:#a371f7,color:#c9d1d9
    style BUILD fill:#0d2818,stroke:#3fb950,color:#c9d1d9
    style OPS fill:#2d1a02,stroke:#d29922,color:#c9d1d9
    style ENGINE fill:#0d1117,stroke:#58a6ff,color:#c9d1d9

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


Features

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. Intelligence é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

Innovation autonome : reinforcement learning, closed-loop reward, prototypage automatique, seed memory, gap-analysis.

Et bien plus encore... (15+ features avancées)
Feature Description
Adversarial Consensus Protocole BFT : 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 Blockchain légère de décisions architecturales 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

Stars

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

grimoire_kit-3.4.0.tar.gz (1.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

grimoire_kit-3.4.0-py3-none-any.whl (1.3 MB view details)

Uploaded Python 3

File details

Details for the file grimoire_kit-3.4.0.tar.gz.

File metadata

  • Download URL: grimoire_kit-3.4.0.tar.gz
  • Upload date:
  • Size: 1.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for grimoire_kit-3.4.0.tar.gz
Algorithm Hash digest
SHA256 47a023a38a1c0b70427fc87ddfd973558421bca69b2be26ad295000ae96a872a
MD5 837eb8e470ea0134058a648973c21bc4
BLAKE2b-256 2299c45f8d3ad3ba4181cf6a99b4ffa00fc0b3280dd9df23e6399424d13badae

See more details on using hashes here.

Provenance

The following attestation bundles were made for grimoire_kit-3.4.0.tar.gz:

Publisher: publish.yml on Guilhem-Bonnet/Grimoire-kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file grimoire_kit-3.4.0-py3-none-any.whl.

File metadata

  • Download URL: grimoire_kit-3.4.0-py3-none-any.whl
  • Upload date:
  • Size: 1.3 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for grimoire_kit-3.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 687c6b7960e7b7ecaeda1d870730ce00a4e2430165185630e7a614a1490de67e
MD5 6ba6dc072397022448ff671f31ea4e18
BLAKE2b-256 a90f30de8d8b733631890ad5daa6b55879d33375b4770532aea8b9593459dc74

See more details on using hashes here.

Provenance

The following attestation bundles were made for grimoire_kit-3.4.0-py3-none-any.whl:

Publisher: publish.yml on Guilhem-Bonnet/Grimoire-kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page