# 🧠 Argus Memory System

> *"Se souvenir pour mieux voir, apprendre pour mieux prévoir"*

## Architecture

```
memory/
├── working/          # Mémoire de travail (session courante)
├── episodic/         # Historique des événements
│   ├── analyses/     # Analyses réalisées
│   ├── decisions/    # Décisions prises
│   ├── incidents/    # Incidents et échappés
│   └── executions/   # Résultats de tests
├── semantic/         # Connaissances générales apprises
├── projects/         # Profils par projet
└── relational/       # Graphe d'associations
```

## Niveaux de Mémoire

### 1. Working Memory (`working/`)
- **Durée** : Session uniquement
- **Contenu** : Contexte immédiat, analyses en cours
- **Format** : Fichiers temporaires, auto-nettoyés

### 2. Episodic Memory (`episodic/`)
- **Durée** : Permanent (avec politique de rétention)
- **Contenu** : Journal des analyses, décisions, incidents
- **Format** : Un fichier YAML par entrée, nommé `{timestamp}_{type}_{id}.yaml`

### 3. Semantic Memory (`semantic/`)
- **Durée** : Permanent, évolutif
- **Contenu** : Patterns de défauts, heuristiques, savoirs technos
- **Format** : Fichiers YAML thématiques

### 4. Project Memory (`projects/`)
- **Durée** : Permanent par projet
- **Contenu** : Profil qualité, hotspots, conventions
- **Format** : Un fichier YAML par projet

### 5. Relational Memory (`relational/`)
- **Durée** : Permanent, évolutif
- **Contenu** : Associations entre entités
- **Format** : Fichier YAML de graphe

## Conventions de Nommage

### Fichiers Épisodiques
```
{YYYY-MM-DD}_{HH-MM}_{type}_{short_id}.yaml
```
Exemples :
- `2026-02-15_14-30_analysis_a1b2c3.yaml`
- `2026-02-15_09-00_incident_p0-auth-failure.yaml`

### Identifiants
- **Analyses** : `ANL-{YYYYMMDD}-{seq}` (ex: `ANL-20260215-001`)
- **Décisions** : `DEC-{YYYYMMDD}-{seq}` (ex: `DEC-20260215-001`)
- **Incidents** : `INC-{YYYYMMDD}-{seq}` (ex: `INC-20260215-001`)
- **Patterns** : `PAT-{category}-{seq}` (ex: `PAT-NULL-001`)
- **Projets** : Slug du nom de projet (ex: `my-awesome-api`)

## Cycle de Vie

```
┌─────────────────────────────────────────────────────────────┐
│                     ENCODING (Entrée)                       │
│  Événement → Filtrage → Structuration → Indexation          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    STORAGE (Stockage)                       │
│  working/ → episodic/ → semantic/ (consolidation)           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   RETRIEVAL (Accès)                         │
│  Direct | Similarity | Pattern | Temporal | Associative     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  MAINTENANCE (Entretien)                    │
│  Consolidation | Decay | Archival | Reflection              │
└─────────────────────────────────────────────────────────────┘
```

## Politique de Rétention

| Type | Rétention | Action après expiration |
|------|-----------|------------------------|
| Incidents critiques (P0/P1) | ∞ Permanent | Jamais supprimé |
| Analyses significatives | 2 ans | Résumé dans semantic/ |
| Exécutions de tests | 6 mois | Agrégé en statistiques |
| Working memory | Session | Supprimé |

## Consolidation

La consolidation transforme les épisodes répétés en savoirs sémantiques :

```
N analyses similaires    ─┐
                          ├──► Pattern sémantique
Feedback positif        ─┘

Épisodes marqués "consolidés" → Peuvent être archivés
```

## Utilisation

### Enregistrer une analyse
1. Créer un fichier dans `episodic/analyses/`
2. Utiliser le template `_template_analysis.yaml`
3. Remplir tous les champs requis

### Consulter l'historique d'un projet
1. Charger `projects/{project-slug}.yaml`
2. Filtrer `episodic/` par `project: {project-slug}`

### Ajouter un pattern appris
1. Éditer `semantic/defect_patterns.yaml`
2. Ajouter une entrée avec les références aux épisodes sources

---

## 🛡️ Validation & Qualité

### Hook Pre-commit

Un hook Git est configuré pour exécuter automatiquement **5 validations** avant chaque commit :

1. **Validation YAML** — Vérifie la syntaxe de tous les fichiers YAML staged
2. **Synchronisation compteurs** — Vérifie que l'index mémoire est à jour
3. **Validation des références croisées** — Détecte les références orphelines entre fichiers
4. **Validation d'encodage** — Détecte BOM, mojibake et corruptions
5. **Synchronisation des enums JSON Schema** — Vérifie la cohérence schemas/données

**Comportement :**
```
git commit → Hook pre-commit
                    │
    Step 1: YAML syntax validation
    Step 2: Counter synchronization
    Step 3: Cross-file reference validation
    Step 4: Encoding validation
    Step 5: JSON Schema enum synchronization
                    │
        ┌───────────┴───────────┐
        │                       │
    ✓ 5/5 Success           ✗ Any failure
        │                       │
   Commit OK             Commit blocked
```

**Bypass (déconseillé) :**
```bash
git commit --no-verify
```

### Script de validation YAML

Le script `tests/validate_yaml.py` vérifie la syntaxe des fichiers YAML :

```bash
# Valider tous les YAML du projet
python tests/validate_yaml.py

# Valider uniquement les fichiers staged
python tests/validate_yaml.py --staged

# Valider un fichier spécifique
python tests/validate_yaml.py --file memory/semantic/defect_patterns.yaml

# Mode silencieux (exit code uniquement)
python tests/validate_yaml.py --quiet
```

### Script de synchronisation des compteurs

Le script `tests/sync_counters.py` vérifie et corrige la synchronisation entre l'index (`_index.yaml`) et le contenu réel des fichiers :

```bash
# Vérifier la synchronisation (mode détection)
python tests/sync_counters.py

# Corriger automatiquement les désynchronisations
python tests/sync_counters.py --fix

# Mode silencieux (exit code uniquement)
python tests/sync_counters.py --quiet

# Sortie JSON (pour intégration CI)
python tests/sync_counters.py --json
```

**Compteurs vérifiés :**
| Compteur | Source |
|----------|--------|
| `semantic.defect_patterns.count` | Nombre de patterns dans `defect_patterns.yaml` |
| `semantic.testing_heuristics.count` | Nombre d'heuristics dans `testing_heuristics.yaml` |
| `episodic.{type}.count` | Nombre de fichiers dans `episodic/{type}/` |
| `projects.count` | Nombre de fichiers projet dans `projects/` |
| `statistics.totals.*` | Totaux globaux |
| `sequences.*` | Compteurs de séquence pour génération d'IDs |

**Exit codes :**
| Code | Signification |
|------|---------------|
| 0 | Index synchronisé |
| 1 | Désynchronisation détectée |
| 2 | Erreur d'exécution |

### Script de validation des références croisées

Le script `tests/validate_references.py` détecte les références orphelines entre fichiers :

```bash
# Mode détection (affiche les orphelins)
python tests/validate_references.py

# Générer un graphe de dépendances Mermaid
python tests/validate_references.py --graph

# Mode silencieux (exit code uniquement)
python tests/validate_references.py --quiet

# Sortie JSON (pour intégration CI)
python tests/validate_references.py --json
```

**Types d'IDs validés :**
| Type | Pattern | Exemple |
|------|---------|---------|
| Pattern | `PAT-{CAT}-{SEQ}` | `PAT-NULL-001` |
| Heuristic | `HEU-{CAT}-{SEQ}` | `HEU-SEL-002` |
| Analysis | `ANL-{YYYYMMDD}-{SEQ}` | `ANL-20260215-001` |
| Decision | `DEC-{YYYYMMDD}-{SEQ}` | `DEC-20260215-001` |
| Incident | `INC-{YYYYMMDD}-{SEQ}` | `INC-20260215-001` |
| Execution | `EXE-{YYYYMMDD}-{SEQ}` | `EXE-20260215-001` |
| File | `*.yaml` | `memory/_index.yaml` |
| Project | Slug | `argus` |

**Fonctionnalités :**
- Détection des références orphelines (IDs mentionnés mais non définis)
- Suggestions "Did you mean?" pour les fautes de frappe
- Génération de graphe de dépendances au format Mermaid

**Exit codes :**
| Code | Signification |
|------|---------------|
| 0 | Toutes les références sont valides |
| 1 | Références orphelines détectées |
| 2 | Erreur d'exécution |

### Script de validation d'encodage

Le script `tests/validate_encoding.py` détecte les problèmes d'encodage (BOM, mojibake, corruption) :

```bash
# Vérifier tous les fichiers
python tests/validate_encoding.py

# Vérifier uniquement les fichiers staged
python tests/validate_encoding.py --staged

# Corriger automatiquement les BOM
python tests/validate_encoding.py --fix

# Mode silencieux
python tests/validate_encoding.py --quiet
```

### Script de synchronisation des enums JSON Schema

Le script `tests/sync_schemas.py` vérifie la cohérence entre les enums des JSON Schemas et les valeurs réelles dans les YAML :

```bash
# Vérifier la synchronisation
python tests/sync_schemas.py

# Corriger automatiquement les désynchronisations
python tests/sync_schemas.py --fix

# Mode silencieux
python tests/sync_schemas.py --quiet

# Sortie JSON (pour intégration CI)
python tests/sync_schemas.py --json
```

### Script de validation des schémas JSON

Le script `tests/validate_schemas.py` valide les fichiers YAML contre leurs schémas JSON respectifs :

```bash
# Valider tous les fichiers
python tests/validate_schemas.py

# Mode verbose
python tests/validate_schemas.py --verbose

# Valider uniquement les fichiers staged
python tests/validate_schemas.py --staged

# Mode silencieux
python tests/validate_schemas.py --quiet
```

### Script de validation du risk scoring

Le script `tests/validate_risk_scoring.py` valide les sections de scoring de risque dans les analyses :

```bash
# Vérifier le risk scoring
python tests/validate_risk_scoring.py

# Mode verbose
python tests/validate_risk_scoring.py --verbose

# Mode silencieux
python tests/validate_risk_scoring.py --quiet
```

---

## 🧪 Cycle Cognitif

Le cycle cognitif est le mécanisme d'entretien automatique de la mémoire. Il enchaîne trois phases :

```
┌─────────────────────────────────────────────────────────────┐
│  Phase 1: Consolidation                                     │
│  Épisodes répétés → Patterns sémantiques                    │
│  Renforce les connaissances confirmées par l'expérience     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: Decay (Oubli)                                     │
│  Connaissances non utilisées → Perte de confidence          │
│  Grâce: 60 jours | Taux: 0.05/mois | Seuil: 0.2            │
│  Catégories protégées: security, critical                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 3: Reflection                                        │
│  12 health checks: cohérence, complétude, fraîcheur,        │
│  équilibre. Diagnostic global: OK | DEGRADED | CRITICAL     │
└─────────────────────────────────────────────────────────────┘
```

### Utilisation

```bash
# Exécuter le cycle complet (mode scan, dry-run)
python tests/cognitive_cycle.py

# Appliquer les corrections (decay, consolidation)
python tests/cognitive_cycle.py --apply

# Exécuter une seule phase
python tests/cognitive_cycle.py --phase decay

# Avec date de référence spécifique
python tests/cognitive_cycle.py --reference-date 2026-03-14

# Sortie JSON
python tests/cognitive_cycle.py --json
```

**Exit codes :**
| Code | Signification |
|------|---------------|
| 0 | Mémoire saine (HEALTHY) |
| 1 | Actions requises ou avertissements |
| 2 | Erreur d'exécution |

---

## 🔄 CI/CD

Une pipeline GitHub Actions (`.github/workflows/validate.yml`) exécute la validation complète sur chaque push/PR :

- **Branches** : `main`, `develop`
- **Matrice Python** : 3.11, 3.12, 3.13
- **Étapes** : YAML validation → Counter sync → Schema validation → Reference validation → Risk scoring → Full pytest suite (330 tests)

---

### Réinstaller le hook

Si le hook est supprimé ou corrompu :

```powershell
.\scripts\install-hooks.ps1
```

Options :
- `-Force` : Écraser un hook existant
- `-Uninstall` : Supprimer le hook

---

*"Les cent yeux d'Argus voient le présent, mais sa mémoire lui permet de voir le passé et d'anticiper l'avenir."*

