Mémoire persistante OpenClaw pour le contexte dbt

Les alertes de surveillance qui incluent le contexte business — “les doublons signifient un chiffre d’affaires double-compté dans tous les dashboards commerciaux” plutôt que “le test d’unicité a échoué avec 3 lignes” — nécessitent que l’agent ait accès à la documentation du projet dbt. La mémoire persistante d’OpenClaw stocke ce contexte sous forme de fichiers Markdown qui survivent entre les sessions. Là où un fichier skill donne à un agent une procédure opérationnelle, la mémoire persistante lui donne une base de connaissances.

Ce qu’il faut stocker en mémoire

Trois catégories d’informations appartiennent à la mémoire persistante pour la surveillance dbt :

Documentation des modèles et colonnes — les descriptions de vos fichiers schema.yml, traduites dans le contexte de l’agent. Pas le YAML brut, mais un format lisible que l’agent peut rechercher et référencer.

Informations sur les dépendances en aval — un résumé compact du graphe de dépendances du modèle dérivé de manifest.json. Quels modèles dépendent de quels autres, notamment quels modèles mart sont en aval de chaque source ou modèle de base.

Historique des investigations — un journal des événements d’échec que vous avez traités, incluant vos conclusions. C’est ce qui permet à l’agent de vous dire “vous avez investigué cela mardi et décidé que c’était un délai du fournisseur” plutôt que de traiter chaque échec récurrent comme un événement nouveau.

Stocker la documentation des modèles

Extrayez les descriptions de modèles et colonnes de vos fichiers schema.yml et stockez-les sous forme de fichier Markdown dans la mémoire d’OpenClaw. Le format importe — vous voulez que l’agent puisse retrouver les sections pertinentes rapidement, pas analyser du YAML brut :

# Documentation du projet dbt

## mrt__sales__customers
Dimension client dédupliquée pour tous les reportings commerciaux.
Utilisée par : dashboards de chiffre d'affaires, analyse de cohortes, segmentation client.
Propriétaire : équipe data
Criticité : élevée

### Colonnes
- customer__id : Clé primaire. Identifiant client dédupliqué depuis Shopify.
  L'unicité est critique — les doublons signifient un chiffre d'affaires double-compté.
- customer__email : Email de contact. Utilisé pour le matching CRM.
- customer__first_ordered_at : Timestamp du premier achat. Détermine l'assignation de cohorte.

## mrt__finance__orders
Mart au niveau des commandes pour tous les reportings de chiffre d'affaires.
Utilisé par : dashboard CFO, rapports mensuels de chiffre d'affaires, sync Salesforce.
Propriétaire : équipe finance
Criticité : élevée

### Colonnes
- order__id : Clé primaire. Source : ID de commande Shopify.
- order__customer_id : Clé étrangère vers mrt__sales__customers. Non nullable.
- order__revenue_usd : Chiffre d'affaires brut en USD. Inclut la TVA, exclut les remboursements.

Avec cela chargé, l’agent transforme la sortie brute d’échec en alertes avec contexte business. Quand unique_mrt__sales__customers_customer__id échoue, l’agent recherche mrt__sales__customers, lit que “l’unicité est critique — les doublons signifient un chiffre d’affaires double-compté,” et l’inclut dans son rapport. Vous obtenez l’implication business sans faire la recherche vous-même.

Cela ne nécessite pas de code personnalisé. Chargez le fichier avec la commande mémoire d’OpenClaw et demandez au skill de le consulter lors du reporting des échecs :

## Cross-référencement de la documentation

Quand un test échoue sur un modèle :
1. Rechercher le modèle dans votre document mémoire "dbt-project-docs.md"
2. Inclure la description du modèle dans le rapport d'échec
3. Inclure la description de la colonne concernée
4. Noter quels rapports ou systèmes en aval sont affectés
5. Inclure le propriétaire du modèle pour le routage d'escalade

La limitation est la maintenance. Il n’y a pas de synchronisation automatique entre votre schema.yml et le fichier mémoire. Quand les modèles changent, quelqu’un doit mettre à jour le document mémoire. C’est la principale surcharge opérationnelle de cette approche — planifiez-la dans le cadre de votre processus de changement de modèle, pas comme une réflexion après coup.

Impact en aval depuis manifest.json

Le manifest.json de dbt contient le graphe complet de dépendances du projet. Chaque modèle connaît ses parents et ses enfants. L’agent peut analyser cela pour répondre à “quels modèles dépendent du modèle qui vient d’échouer ?” — une information qui détermine immédiatement la sévérité et l’urgence de la réponse.

Le défi avec les grands projets est la taille. Un manifest pour un projet avec 300+ modèles peut peser plusieurs mégaoctets de JSON, ce qui est difficile à intégrer dans la fenêtre de contexte d’un modèle de langage. La solution est le pré-traitement : extraire le graphe de dépendances dans un format compact et stocker cela en mémoire persistante à la place.

Un résumé compact de dépendances ressemble à ceci :

# Résumé des dépendances dbt

## Modèles au niveau mart et leurs sources clés

mrt__sales__customers
  Parents directs : int__customers_deduplicated
  Ancêtres clés : base__shopify__customers, base__shopify__orders
  En aval de ce mart : (aucun — c'est un nœud feuille)

mrt__finance__orders
  Parents directs : int__orders_enriched
  Ancêtres clés : base__shopify__orders, base__shopify__refunds, stg__exchange_rates
  En aval de ce mart : (aucun)

int__orders_enriched
  Parents directs : base__shopify__orders, stg__exchange_rates, int__customers_deduplicated
  Marts en aval : mrt__finance__orders, mrt__marketing__attribution
  Nombre de marts en aval : 2

base__shopify__customers
  Nombre d'intermédiaires en aval : 3
  Nombre de marts en aval : 4
  Dépendants haute criticité : mrt__sales__customers, mrt__finance__orders

Générer ce résumé peut être scripté — itérer sur les nœuds de manifest.json, extraire les relations parent/enfant, et écrire la sortie formatée. Une fois en mémoire, l’agent peut rechercher tout modèle en échec et connaître immédiatement son empreinte en aval sans re-analyser le manifest au moment de la surveillance.

Demandez au skill de l’utiliser :

## Recherche d'impact en aval

Quand un test échoue sur un modèle :
1. Rechercher le modèle dans "dbt-dependency-summary.md" en mémoire
2. Trouver combien de modèles mart en aval en dépendent
3. Inclure dans le rapport : "X marts en aval affectés, incluant [noms des critiques]"
4. Si 3 ou plus de modèles mart sont en aval, signaler comme impact aval élevé

Suivi de l’historique des échecs

L’utilisation la plus puissante de la mémoire persistante pour la surveillance est le suivi de l’historique des échecs. Une simple tâche cron qui lance dbt test n’a pas de mémoire. Elle voit chaque échec comme un nouvel événement et le rapporte identiquement que ce soit la première ou la quatorzième fois.

La mémoire persistante change cela. Après chaque exécution de surveillance, l’agent met à jour un fichier d’historique structuré :

# Historique des échecs dbt

## unique_mrt__sales__customers_customer__id
Dernier échec : 2026-03-25
Premier échec : 2026-03-25
Total des occurrences sur les 30 derniers jours : 1
Statut : actif
Notes : Première occurrence. Investigation de la logique de déduplication dans base__shopify__customers.

## not_null_int__orders_enriched_order__customer_id
Dernier échec : 2026-03-27
Premier échec : 2026-03-14
Total des occurrences sur les 30 derniers jours : 6
Statut : récurrent — intermittent
Notes : 2026-03-18 investigué. Probablement lié aux délais de fraîcheur de la source Shopify.
  Les échecs corrèlent avec les chargements source tardifs. Surveiller mais ne pas escalader immédiatement.

## source_freshness_raw_ga4_events
Dernier échec : 2026-03-22
Premier échec : 2026-02-15
Total des occurrences sur les 30 derniers jours : 4
Statut : récurrent — connu
Notes : Attendu le week-end (timing batch du fournisseur). Aucune action nécessaire pour les échecs Sam/Dim.
  Escalader uniquement si cela échoue un jour de semaine.

Le skill demande à l’agent de consulter ce fichier lors du reporting et de le mettre à jour après chaque exécution :

## Contexte historique

Avant de rapporter un échec :
1. Vérifier "dbt-failure-history.md" en mémoire pour les occurrences précédentes de ce test
2. Si trouvé : inclure le comptage des occurrences et les notes des investigations précédentes
3. Si non trouvé : marquer comme "Première occurrence" — urgence maximale

Après avoir rapporté tous les échecs :
1. Mettre à jour "dbt-failure-history.md" pour chaque échec rencontré aujourd'hui
2. Incrémenter le comptage des occurrences
3. Mettre à jour la date "Dernier échec"
4. Préserver les notes existantes ; ajouter de nouvelles notes si l'investigation révèle de nouvelles informations

Chaque exécution ajoute à la connaissance institutionnelle que l’agent transmet. Au fil du temps, le résumé matinal distingue les nouveaux échecs des patterns récurrents qui ont déjà été catégorisés.

La réalité de la maintenance

Soyez réaliste sur ce que cette configuration nécessite pour rester utile. Les documents mémoire qui deviennent obsolètes sont pires qu’aucune mémoire du tout — un agent qui rapporte confidemment un mauvais contexte business crée plus de confusion qu’un agent qui n’en rapporte aucun.

L’engagement minimum de maintenance :

Documentation des modèles : mettre à jour quand des modèles sont ajoutés, renommés, ou significativement modifiés
Résumé des dépendances : régénérer quand le DAG du projet change significativement (mensuel est généralement suffisant pour les projets stables)
Historique des échecs : l’agent le maintient lui-même après chaque exécution, mais révisez-le mensuellement pour archiver les problèmes résolus et garder le fichier lisible

La documentation et le résumé des dépendances sont les éléments de maintenance les plus lourds. Si votre projet dbt change fréquemment, automatisez la régénération plutôt que de dépendre des mises à jour manuelles. Un simple script qui lit les fichiers schema.yml et manifest.json et régénère les documents mémoire peut s’exécuter dans le cadre de votre pipeline CI/CD à chaque merge de PR.