firm-hebbian-memory

name	firm-hebbian-memory
version	1.0.0
description	Système de mémoire adaptative hebbienne pour Claude.md — transforme les logs de sessions en patterns pondérés qui renforcent ou atrophient les règles de travail selon l'usage réel. Implémente le Cahier des Charges v1.0.0 "Système de Mémoire Adaptative Hebbienne + Base Vectorielle pour Claude.md".
author	romainsantoli-web
license	MIT
metadata	{"openclaw":{"registry":"ClawHub","requires":["mcp-openclaw-extensions >= 1.2.0"],"cdc_version":"1.0.0"}}
tags	["hebbian","memory","adaptive","pgvector","sessions","pii-stripping","neuroscience"]

firm-hebbian-memory

⚠️ Contenu généré par IA — validation humaine requise avant déploiement en production.

Purpose

Ce skill rend le Claude.md vivant et auto-évolutif via des mécanismes inspirés de la plasticité synaptique hebbienne. Les patterns de travail qui se répètent sont renforcés, ceux qui deviennent obsolètes s'atrophient naturellement.

Inspiration neurobiologique :

• Plasticité hebbienne → renforcement des poids Layer 2 par co-activation
• Mémoire hippocampique → stockage épisodique en base vectorielle (pgvector)
• Consolidation néocorticale → job d'analyse transformant les épisodes en schémas

Architecture — 4 couches Claude.md (CDC §3.3)

Couche	Nom	Modification
Layer 1	CORE (immuable)	Humain uniquement
Layer 2	CONSOLIDATED PATTERNS	Auto-mise à jour (poids hebbiens)
Layer 3	EPISODIC INDEX	Auto-mise à jour (pointeurs sessions)
Layer 4	META INSTRUCTIONS	Lecture seule pour le système auto

Tools activés (8 tools)

Runtime (2 tools)

openclaw_hebbian_harvest        — ingest JSONL session logs → SQLite (PII stripped)
openclaw_hebbian_weight_update  — calcul/application des poids hebbiens (dry_run par défaut)

Audit (6 tools)

openclaw_hebbian_analyze           — analyse co-activation patterns (Jaccard)
openclaw_hebbian_status            — dashboard poids, atrophie, promotions
openclaw_hebbian_layer_validate    — validation structure 4 couches
openclaw_hebbian_pii_check         — audit config PII stripping
openclaw_hebbian_decay_config_check — validation paramètres hebbiens
openclaw_hebbian_drift_check       — détection drift sémantique vs baseline

Formule de mise à jour des poids (CDC §4.3)

nouveau_poids = ancien_poids + (learning_rate × activation) - (decay × (1 - activation))

# Paramètres par défaut
learning_rate = 0.05    # Renforcement si activée
decay         = 0.02    # Atrophie si non-activée
poids_min     = 0.0     # Floor — suppression si < 0.10
poids_max     = 0.95    # Ceiling — promotion CORE si > 0.95

Seuils de consolidation

Transition	Condition
Épisodique → Émergent	Activé 5 sessions consécutives
Émergent → Fort	poids > 0.8 sur 20 sessions
Fort → CORE	Validation humaine obligatoire
Atrophie → Suppression	poids < 0.10 pendant 4 semaines + PR humaine

Sécurité (CDC §5.2)

• PII stripping obligatoire : regex sur emails, phones, IPs, API keys, SSN, JWT, AWS keys, chemins Unix home
• Secrets détectés : session rejetée + alerte immédiate
• Accès BDD : localhost/VPN uniquement
• Rotation embeddings : policy de ré-embedding si fuite suspectée
• Réversibilité : chaque modification = 1 commit Git atomique
• Path whitelist : configurable via HEBBIAN_ALLOWED_DIRS (env) — protège containers/multi-user

Limitations connues (PII)

Le stripping regex couvre les catégories les plus courantes (10 patterns) mais ne détecte pas les credentials embarqués dans des URLs de connexion (e.g. postgres://user:password@host/db) ni les variables d'environnement loguées dans des stack traces (DB_URL=...). Un scanner de secrets dédié (e.g. trufflehog, detect-secrets) est recommandé en complément pour les environnements à haute sensibilité.

Anti-dérive (CDC §5.1)

• Aucune règle ne peut atteindre poids = 1.0 automatiquement (max 0.95)
• Détecteur de drift : alerte si cosine similarity vs baseline < 0.7
• 3 changements auto consécutifs → review forcée
• Snapshot mensuel archivé en Git tag

Pipeline global

[ Session Claude Code ]
         ↓ fin de session
[ openclaw_hebbian_harvest ] → extrait résumé + tags + règles (PII stripped)
         ↓
[ SQLite local ] → stockage épisodique structuré
         ↓
[ openclaw_hebbian_analyze ] → clustering Jaccard + co-activations
         ↓
[ openclaw_hebbian_weight_update ] → mise à jour Layer 2 (dry_run=True)
         ↓
[ Human Review ] → validation avant application (dry_run=False)

Hook post-session (MVP)

Sans hook automatique, l'ingestion reste manuelle — adoption = zéro. Voici le minimum pour boucler le pipeline dès le MVP.

Option A — Script shell (le plus simple)

Créer ~/.openclaw/hooks/post-session.sh :

#!/usr/bin/env bash
# Hook post-session: ingest le dernier JSONL automatiquement
set -euo pipefail

SESSION_LOG="${1:-$(ls -t ~/.openclaw/sessions/*.jsonl 2>/dev/null | head -1)}"
[ -z "$SESSION_LOG" ] && exit 0

# Appel MCP via curl (le serveur doit tourner sur :8012)
curl -s -X POST http://localhost:8012/mcp \
  -H "Content-Type: application/json" \
  -d "{
    \"method\": \"tools/call\",
    \"params\": {
      \"name\": \"openclaw_hebbian_harvest\",
      \"arguments\": {\"session_jsonl_path\": \"$SESSION_LOG\"}
    }
  }" | jq '.result.ingested // .error'

Option B — Entrée cron (automatisation passive)

# Toutes les 30 min, ingérer les nouveaux JSONL
*/30 * * * * /bin/bash ~/.openclaw/hooks/post-session.sh >> ~/.openclaw/hebbian-harvest.log 2>&1

Option C — Intégration pi-coding-agent

Si le projet utilise pi-coding-agent, ajouter dans sa config :

{
  "hooks": {
    "post_session": {
      "command": "~/.openclaw/hooks/post-session.sh",
      "trigger": "on_session_end"
    }
  }
}

Note : Le hook ne déclenche que le harvest (lecture). La mise à jour des poids (weight_update) reste toujours manuelle avec dry_run=True par défaut — conformément à la règle absolue n°1 du CDC.

Adaptation OpenClaw

Composant CDC	Adaptation OpenClaw
Hook post-session	Lecture fichiers .jsonl de pi-coding-agent
Claude.md Layer 2	Skills OpenClaw (.md ou .json)
Claude.md Layer 4	Extension pi-coding-agent dédiée
GitHub PR for review	PR sur repo privé skills
Secrets stripping	Renforcé — 9 patterns regex + détection runtime

Configuration requise

{
  "hebbian": {
    "parameters": {
      "learning_rate": 0.05,
      "decay": 0.02,
      "poids_min": 0.0,
      "poids_max": 0.95
    },
    "thresholds": {
      "episodic_to_emergent": 5,
      "emergent_to_strong": 0.8
    },
    "pii_stripping": {
      "enabled": true,
      "patterns": ["email", "phone", "ip", "api_key", "ssn"]
    },
    "security": {
      "secret_detection": true,
      "access_restriction": "localhost",
      "embedding_rotation": "on_breach"
    },
    "anti_drift": {
      "max_consecutive_auto_changes": 3
    }
  }
}

Référence

• CDC : cahier_des_charges_memoire_hebbienne.md v1.0.0
• Module : src/hebbian_memory.py
• Modèles : 8 classes Pydantic dans src/models.py

---

💎 Support

Si ce skill vous est utile, vous pouvez soutenir le développement :

Dogecoin : DQBggqFNWsRNTPb6kkiwppnMo1Hm8edfWq