gavdalf/total-recall

Total Recall — Mémoire Autonome pour Agent

La seule compétence mémoire qui surveille toute seule.

Aucune base de données. Aucun vecteur. Aucune sauvegarde manuelle. Juste un observateur LLM qui compresse vos conversations en notes priorisées, les consolide quand elles grandissent et récupère tout ce qui est manqué. Cinq couches de redondance, zéro maintenance. ~0,00€/mois (modèles gratuits).

Pendant que les autres compétences mémoire vous demandent de vous souvenir de vous souvenir, celle-ci se contente de prêter attention.

Architecture

Couche 1 : Observateur (cron, toutes les 15 à 30 min)
    ↓ compresse les messages récents → observations.md
Couche 2 : Réflecteur (déclenché automatiquement quand observations > 8000 mots)
    ↓ consolide, supprime les informations obsolètes → réduction de 40 à 60 %
Couche 3 : Récupération de session (s'exécute à chaque /new ou /reset)
    ↓ rattrape toute session manquée par l'observateur
Couche 4 : Watcher réactif (démon inotify, Linux uniquement)
    ↓ déclenche l'observateur après 40+ nouvelles écritures JSONL, intervalle de 5 min
Couche 5 : Crochet de pré-compaction (memoryFlush)
    ↓ capture d'urgence avant qu'OpenClaw ne compacte le contexte

Ce qu'il fait

• Observateur : lit les transcriptions de session récentes (JSONL), les envoie à un LLM et ajoute des observations compressées dans observations.md avec des niveaux de priorité (élevée, moyenne, faible)
• Réflecteur : intervient lorsque les observations deviennent trop volumineuses, en consolidant les éléments connexes et en supprimant les entrées obsolètes de faible priorité
• Récupération de session : s'exécute au démarrage de la session, vérifie si la session précédente a été capturée et effectue une observation d'urgence si ce n'est pas le cas
• Watcher réactif : surveille le répertoire de session avec inotify afin que les périodes de forte activité soient capturées plus rapidement que l'intervalle cron
• Crochet de pré-compaction : se déclenche lorsqu'OpenClaw s'apprête à compacter le contexte, garantissant qu'aucune information n'est perdue

Démarrage rapide

1. Installer la compétence

clawdhub install total-recall

2. Définir votre clé API

Ajoutez à votre .env ou à la configuration OpenClaw :

OPENROUTER_API_KEY=sk-or-v1-xxxxx

3. Exécuter le script d'installation

bash skills/total-recall/scripts/setup.sh

Ce script va :

• Créer la structure de répertoires mémoire (memory/, logs/, sauvegardes)
• Sur Linux avec inotify + systemd : installer le service de watcher réactif
• Afficher les instructions pour les tâches cron et la configuration de l'agent à ajouter manuellement

4. Configurer votre agent pour charger les observations

Ajoutez au contexte de l'espace de travail de votre agent (ex. MEMORY.md ou prompt système) :

Au démarrage de la session, lire `memory/observations.md` pour le contexte inter-sessions.

Ou utilisez memoryFlush.systemPrompt d'OpenClaw pour injecter une instruction de démarrage.

Support des plateformes

Plateforme	Observateur + Réflecteur + Récupération	Watcher réactif
Linux (Debian/Ubuntu, etc.)	Support complet	Avec inotify-tools
macOS	Support complet	Non disponible (cron uniquement)

Tous les scripts de base utilisent du bash portable. Les commandes stat, date et md5 sont gérées de manière multiplateforme via _compat.sh.

Configuration

Tous les scripts lisent les variables d'environnement avec des valeurs par défaut raisonnables :

Variable	Défaut	Description
OPENROUTER_API_KEY	(requis)	Clé API OpenRouter pour les appels LLM
MEMORY_DIR	$OPENCLAW_WORKSPACE/memory	Emplacement de observations.md
SESSIONS_DIR	~/.openclaw/agents/main/sessions	Transcriptions de session OpenClaw
OBSERVER_MODEL	stepfun/step-3.5-flash:free	Modèle principal pour la compression (gratuit)
OBSERVER_FALLBACK_MODEL	nvidia/nemotron-3-nano-30b-a3b:free	Modèle de secours si le principal échoue (gratuit)
OBSERVER_LOOKBACK_MIN	15	Minutes à examiner en arrière (journée)
OBSERVER_MORNING_LOOKBACK_MIN	480	Minutes à examiner en arrière (avant 8h)
OBSERVER_LINE_THRESHOLD	40	Lignes avant le déclenchement réactif (Linux)
OBSERVER_COOLDOWN_SECS	300	Temps d'attente entre les déclenchements réactifs (Linux)
REFLECTOR_WORD_THRESHOLD	8000	Mots avant l'exécution du réflecteur
REFLECTOR_MODEL	nvidia/nemotron-3-super-120b-a12b:free	Modèle pour consolider les observations (gratuit)
REFLECTOR_FALLBACK_MODEL	openrouter/hunter-alpha	Modèle de secours si le modèle réflecteur échoue (gratuit)
OPENCLAW_WORKSPACE	~/votre-espace-de-travail	Racine de l'espace de travail

Configuration du fournisseur LLM

Total Recall utilise toute API de complétion de chat compatible OpenAI. Changez de fournisseur en définissant des variables d'environnement :

Variable	Défaut	Description
LLM_BASE_URL	https://openrouter.ai/api/v1	Point de terminaison API
LLM_API_KEY	utilise OPENROUTER_API_KEY par défaut	Clé API
LLM_MODEL	deepseek/deepseek-v3.2	Modèle à utiliser

Exemples de fournisseurs

# OpenRouter (défaut)
export OPENROUTER_API_KEY="votre-clé"

# Ollama (local)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_API_KEY="ollama"
export LLM_MODEL="llama3.1:8b"

# Groq
export LLM_BASE_URL="https://api.groq.com/openai/v1"
export LLM_API_KEY="votre-clé-groq"
export LLM_MODEL="llama-3.3-70b-versatile"

Fichiers créés

memory/
  observations.md          # Journal d'observations principal (chargé au démarrage)
  observation-backups/     # Sauvegardes du réflecteur (les 10 dernières conservées)
  .observer-last-run       # Horodatage de la dernière exécution de l'observateur
  .observer-last-hash      # Hash de déduplication des derniers messages traités
logs/
  observer.log
  reflector.log
  session-recovery.log
  observer-watcher.log

Tâches Cron

Le script d'installation crée ces tâches cron OpenClaw :

Tâche	Planification	Description
memory-observer	Toutes les 15 min	Compresser la conversation récente
memory-reflector	Toutes les heures	Consolider si les observations sont volumineuses

Watcher réactif (Linux uniquement)

Le watcher réactif utilise inotifywait pour détecter l'activité de session et déclencher l'observateur plus rapidement que le seul cron. Nécessite Linux avec inotify-tools installé.

# Installer inotify-tools (Debian/Ubuntu)
sudo apt install inotify-tools

# Vérifier le statut du watcher
systemctl --user status total-recall-watcher

# Voir les logs
journalctl --user -u total-recall-watcher -f

Coût

En utilisant les modèles gratuits par défaut via OpenRouter :

• ~0,00€/mois (modèles gratuits) pour une utilisation typique (observateur + réflecteur)
• ~15 à 30 exécutions cron/jour, chacune traitant quelques centaines de tokens
• Tous les modèles par défaut sont des modèles gratuits

Remarques sur les modèles

Les scripts incluent une gestion défensive des champs .content et .reasoning dans les réponses API. Alors que la plupart des modèles renvoient le contenu dans le champ standard .content, le recours à .reasoning garantit la compatibilité avec les modèles pouvant utiliser des formats de réponse différents.

Comment ça fonctionne (technique)

Observateur

1. Trouve les fichiers JSONL de session récemment modifiés
2. Filtre les sessions de sous-agent/cron
3. Extrait les messages utilisateur + assistant de la fenêtre d'examen
4. Déduplique à l'aide d'une comparaison de hash MD5
5. Envoie au LLM avec le prompt observateur (compression basée sur la priorité)
6. Ajoute le résultat à observations.md
7. Si les observations dépassent le seuil de mots, déclenche le réflecteur

Réflecteur

1. Sauvegarde les observations actuelles
2. Envoie l'intégralité du journal au LLM avec des instructions de consolidation
3. Valide que la sortie est plus courte que l'entrée (vérification de cohérence)
4. Remplace les observations par la version consolidée
5. Nettoie les anciennes sauvegardes (conserve les 10 dernières)

Récupération de session

1. S'exécute à chaque /new ou /reset
2. Hash les lignes récentes du dernier fichier de session
3. Compare avec le hash stocké de la dernière exécution de l'observateur
4. En cas de divergence : exécute l'observateur en mode récupération (examen de 4 heures)
5. Solution de secours : extraction brute des messages si l'observateur échoue

Watcher réactif

1. Utilise inotifywait pour surveiller le répertoire de session
2. Compte les écritures JSONL uniquement sur les fichiers de session principaux
3. Après 40+ lignes : déclenche l'observateur (avec un intervalle de 5 min)
4. Réinitialise le compteur lorsqu'une exécution cron/externe de l'observateur est détectée

Personnalisation des prompts

Les invites système de l'observateur et du réflecteur se trouvent dans prompts/ :

• prompts/observer-system.txt — contrôle la façon dont les conversations sont compressées
• prompts/reflector-system.txt — contrôle la façon dont les observations sont consolidées

Modifiez-les pour les adapter à la personnalité et aux priorités de votre agent.

---

Cycle de rêve

Le Cycle de rêve est un agent nocturne optionnel qui s'exécute après les heures de travail pour consolider observations.md. Il archive les éléments obsolètes et ajoute des crochets sémantiques afin que rien d'utile ne soit réellement perdu. Le contexte reste léger ; tout reste trouvable.

Ce qu'il fait

• Classe chaque observation par impact (critique / élevé / moyen / faible / minimal) et par âge
• Archive les éléments qui ont dépassé leur seuil de pertinence
• Ajoute un crochet sémantique pour chaque élément archivé (mots-clés spécifiques + référence d'archive)
• Valide le résultat et annule automatiquement en cas de problème

Fonctionnalités

Récupération multi-crochets — 4 à 5 formulations de recherche alternatives par élément archivé. Les recherches utilisant des mots différents de l'original trouvent quand même la mémoire.

Score de confiance — chaque observation reçoit un score de confiance (0,0 à 1,0) et un type de source (explicit, implicit, inference, weak, uncertain). Les éléments à haute confiance sont conservés plus longtemps ; les éléments à faible confiance sont archivés plus tôt.

Système de types de mémoire — 7 types avec TTL par type : event (14j), fact (90j), preference (180j), goal (365j), habit (365j), rule (jamais), context (30j). Intégrés sous forme de commentaires HTML de métadonnées invisibles dans observations.md.

Regroupement d'observations — les clusters de 3 observations connexes ou plus sont compressés en une seule entrée récapitulative. Les observations sources sont archivées ; un crochet de groupe les remplace. Permet une réduction de tokens allant jusqu'à 75 %.

Déclin d'importance — déclin quotidien par type appliqué aux scores d'importance avant chaque décision d'archivage. Les éléments qui déclinent en dessous du seuil d'archivage sont mis en file d'attente pour suppression. Taux : event (-0,5/jour), fact (-0,1/jour), preference (-0,02/jour), rule/habit/goal (pas de déclin).

Promotion de motifs — analyse les journaux de rêve récents pour détecter les thèmes récurrents (3 occurrences ou plus sur 3 jours distincts ou plus). Écrit des propositions de promotion dans memory/dream-staging/ pour examen humain. Utilisez staging-review.sh pour lister, afficher, approuver ou rejeter les propositions. Le type context n'est jamais promu automatiquement.

Configuration

1. Exécutez bash skills/total-recall/scripts/setup.sh — crée automatiquement les répertoires du Cycle de rêve.

2. Ajoutez la tâche cron nocturne en tant que tour complet de l'agent :

   # Cycle de rêve — nocturne (3h recommandé ; ajustez à votre fuseau horaire)
   # Le cycle de rêve s'exécute en tant que tour complet de l'agent — PAS en tant qu'appel bash direct.
   # dream-cycle.sh est un assistant d'opérations sur les fichiers appelé PAR l'agent, pas le point d'entrée.
   #
   # 0 3 * * * bash -c 'source ~/.openclaw/shared/secrets/openclaw-secrets.env \
   #   && openclaw agent --agent main \
   #   --message "Exécutez le Cycle de rêve Total Recall. Suivez les instructions dans \
   # $WORKSPACE/skills/total-recall/prompts/dream-cycle-prompt.md exactement. \
   # Utilisez READ_ONLY_MODE=false et DREAM_PHASE=1." \
   #   --json >> $WORKSPACE/logs/dream-cycle.log 2>&1'
   

3. Configurez votre agent cron en utilisant prompts/dream-cycle-prompt.md comme prompt système. Modèles recommandés : Claude Sonnet pour le Rêveur (analyse + décisions), DeepSeek v3.2 pour l'Observateur (pas cher, rapide).

4. Commencez avec READ_ONLY_MODE=true pour les premières nuits. Vérifiez memory/dream-logs/ après chaque exécution pour voir ce qu'il aurait archivé.

5. Passez à READ_ONLY_MODE=false une fois satisfait.

Configuration

Variable	Défaut	Description
DREAM_TOKEN_TARGET	8000	Cible de tokens pour observations.md après consolidation
READ_ONLY_MODE	false	Définir true pour une analyse à blanc sans écritures

Fichiers

Fichier	Description
scripts/dream-cycle.sh	Assistant shell appelé par l'agent (pas un exécuteur autonome) : pré-vérification, archivage, mise à jour des observations, écriture du journal, écriture des métriques, validation, annulation
prompts/dream-cycle-prompt.md	Prompt de l'agent pour l'exécution nocturne du Cycle de rêve
dream-cycle/README.md	Référence rapide du Cycle de rêve
schemas/observation-format.md	Format étendu des métadonnées d'observation

Répertoires créés

memory/
  archive/
    observations/        # Éléments archivés (un fichier .md par nuit)
    chunks/              # Groupes d'observations regroupées
  dream-logs/            # Rapports d'exécution nocturnes
  dream-staging/         # Propositions de promotion de motifs en attente d'examen humain
  .dream-backups/        # Sauvegardes de sécurité avant exécution
research/
  dream-cycle-metrics/
    daily/               # Métriques JSON par nuit

---

Dépannage

L'observateur ne s'exécute pas ?

• Consultez logs/observer.log pour les erreurs
• Vérifiez que OPENROUTER_API_KEY est définie et valide
• Confirmez que cron est actif : crontab -l

Les observations ne sont pas chargées au démarrage de la session ?

• Assurez-vous que les instructions de démarrage de votre agent incluent la lecture de memory/observations.md
• Vérifiez que MEMORY_DIR pointe vers le bon emplacement

Le watcher réactif ne se déclenche pas (Linux) ?

• Exécutez systemctl --user status total-recall-watcher
• Vérifiez que inotify-tools est installé : which inotifywait
• Consultez les logs du watcher : journalctl --user -u total-recall-watcher -f

Le Cycle de rêve archive-t-il trop agressivement ?

• Activez READ_ONLY_MODE=true et examinez les journaux de rêve avant de passer en production
• Augmentez DREAM_TOKEN_TARGET pour archiver moins par exécution

Le Cycle de rêve n'archive-t-il pas assez ?

• Abaissez DREAM_TOKEN_TARGET pour déclencher une consolidation plus agressive

---

Inspiré par

Ce système est inspiré du fonctionnement de la mémoire humaine pendant le sommeil — l'hippocampe (observateur) capture les expériences, et pendant la consolidation du sommeil (réflecteur), les souvenirs importants sont renforcés tandis que le bruit est éliminé.

En savoir plus : Votre IA a un problème d'attention

"Amène ton cul sur Mars." — Eh bien, fais fonctionner la mémoire de ton agent.