/sibyl-save - Synchronisation de la mémoire de session + Extraction de compétences (Sibyl Memory Plugin)
Fait partie de la collection de compétences open source de Sibyl Labs. Licence MIT. Développé par Sibyl Labs, LLC.
Une compétence compagnon pour le Sibyl Memory Plugin. Elle capture tout ce qui s'est passé pendant la session et l'injecte dans la base de données mémoire locale du plugin (~/.sibyl-memory/memory.db) via sa propre interface, puis extrait des motifs réutilisables sous forme de nouvelles compétences.
Elle n'écrit pas directement de fichiers mémoire bruts. Toute la mémoire transite par le plugin, de sorte que le tiering, l'indexation plein texte et la limite du niveau gratuit sont respectés. Comme le plugin expose les mêmes outils MCP sur tous les harnais qu'il prend en charge (Claude Code, Codex et tout hôte MCP ; Hermes via le SDK Python), cette unique compétence est multi-harnais par construction.
Prérequis
Le Sibyl Memory Plugin doit être installé et configuré :
pip install sibyl-memory-cli
sibyl init # activation navigateur/portefeuille, écrit ~/.sibyl-memory/
sibyl setup claude-code # ou : codex | hermes (branche l'interface mémoire à votre harnais)
Cette compétence communique ensuite avec le plugin via l'une des deux surfaces :
- MCP (Claude Code, Codex, Cursor, tout hôte MCP) : les 8 outils
memory_*ci-dessous. - SDK Python (Hermes ou tout agent Python) :
sibyl_memory_client.MemoryClient/sibyl_memory_hermes.SibylMemoryProvider.
L'interface du plugin
| Objectif | Outil MCP | SDK Python |
|---|---|---|
| Enregistrer un fait / une entité | memory_remember(category, name, body) | client.set_entity(category, name, body) |
| Rappeler une entité | memory_recall(category, name) | client.get_entity(category, name) |
| Lister les entités | memory_list(category, limit) | client.list_entities(category) |
| Recherche plein texte | memory_search(query, limit, tiers) | client.search(query) |
| Définir un document d'état | memory_set_state(key, body) | client.set_state(key, body) |
| Obtenir un document d'état | memory_get_state(key) | client.get_state(key) |
| Enregistrer un événement de journal | memory_record_event(kind, body, category, name) | client.write_event(...) |
| Archiver / oublier | memory_forget(category, name, reason) | client.archive_entity(category, name, reason) |
Les exemples ci-dessous utilisent les noms MCP. Pour Hermes ou un agent Python, utilisez la colonne SDK.
Correspondance des niveaux (tiers)
| Contenu de session | Niveau | Appel |
|---|---|---|
| Pointeur / résumé / éléments à venir de session | CHAUD (état) | memory_set_state("session", ...) |
| Priorités classées | CHAUD (état) | memory_set_state("priorities", ...) |
| Entrée de journal de session | FROID (journal) | memory_record_event("session_save", ...) |
| Projets / personnes / produits | TIÈDE (entités) | memory_remember(category, name, body) |
| Éléments fermés / morts | ARCHIVE | memory_forget(category, name, reason) |
| Configuration de cette compétence + marqueur delta | CHAUD (état) | memory_set_state("sibyl_save:config" / "sibyl_save:last_save", ...) |
Modes
- run (par défaut) :
/sibyl-save,save session,sync memory. Injecte le contexte de session dans le plugin, puis propose une extraction de compétences. - setup :
/sibyl-save setup,/sibyl-save config. Interactif. Crée ou modifie la configuration (stockée dans le plugin sous la clé d'étatsibyl_save:config). À exécuter une fois avant la première utilisation. - preview (simulation) :
/sibyl-save preview,/sibyl-save --dry-run. Exécute l'analyse complète et signale chaque écriture prévue. N'appelle aucune fonction qui modifie la base de données. N'avance pas le marqueur delta.
Mode : setup (configuration dynamique)
Objectif : écrire la configuration dans le plugin sous la clé d'état sibyl_save:config. Soyez interactif et minimal. Déduisez ce que vous pouvez ; ne demandez que ce qui est indispensable.
- Harnais. Détectez ou demandez le harnais utilisé (claude-code, codex, cursor, hermes, autre). Ceci détermine où la Phase 2 écrit les fichiers de compétences.
- Sortie des compétences. Où les nouvelles compétences sont écrites pour ce harnais. Par défaut pour Claude Code :
.claude/skills/<nom>/SKILL.md. Pour les autres harnais, confirmez l'emplacement et le format. Stockez sous formeskill_output: {dir, format}. - Priorités. Clé d'état pour la liste classée (par défaut
priorities) et un plafond. Plafond par défaut : 15. Plafond absolu : 30, n'acceptez jamais une valeur supérieure à 30. Une liste de plus de 30 éléments est un backlog, pas un ensemble de priorités. - Catégories d'entités. Quelles catégories TIÈDES vous suivez (par défaut
project,person,product). L'utilisateur ajoute ou supprime. - Capture supplémentaire. Optionnellement, nommez des clés d'état ou catégories d'entités supplémentaires que la sauvegarde doit remplir à chaque exécution (un document d'état de métriques, une catégorie de contacts). C'est le point d'extension.
- Valeur par défaut du mode simulation. Basculez
dry_run_default(par défaut false). - Écrivez la configuration via
memory_set_state("sibyl_save:config", {...}). Ne touchez pas au marqueur delta.
Structure de la configuration : voir examples/sibyl-save-config.example.json. Relancer le mode setup la modifie sur place.
Mode : run
Phase 1 : Synchronisation mémoire (dans la base de données du plugin)
Étape 0 - Charger la configuration et le delta
memory_get_state("sibyl_save:config"). Si absent, passer en mode setup. memory_get_state("sibyl_save:last_save") pour l'ancre delta (ce qui a changé depuis la dernière sauvegarde). Si dry_run_default est true et qu'aucun mode n'a été donné, exécutez en mode preview.
Étape 1 - Lire l'état actuel
memory_get_state("session")etmemory_get_state(<clé des priorités>)memory_list(category, limit)pour les catégories suivies, etmemory_recall/memory_searchpour les entités touchées pendant cette session- toutes les clés d'état ou catégories supplémentaires nommées dans la configuration
Étape 1.5 - Vérification et réconciliation des priorités
Lisez le document d'état des priorités et réconciliez-le sur place (réécrivez avec memory_set_state). Conditions et actions requises :
- Élément TERMINÉ toujours listé : supprimez-le ; enregistrez la clôture via
memory_record_event("priority_closed", {...}). - RANK_DRIFT / DUP_RANK (rangs non contigus de 1 à N, ou un rang qui se répète) : renumérotez de 1 à N.
- OVER_CAP (plus d'éléments que le plafond) : déplacez les éléments de priorité la plus basse vers un document d'état de backlog jusqu'à atteindre ou être en dessous du plafond.
- STALE_ITEM (>14 jours sans modification) : signalez-le à l'utilisateur.
- Entité TERMINALE (l'entité référencée est archivée/morte) : fermez la priorité.
- Référence d'entité CASSÉE (ne pointe vers aucune entité réelle) : corrigez-la en une
catégorie/nomréelle.
Appliquez le plafond à chaque écriture (ne dépassez jamais 30).
Étape 2 - Analyser la session
Passez en revue la conversation depuis l'ancre delta (ou depuis le début de la session lors de la première sauvegarde). Extrayez :
- Entités touchées - projets, personnes, produits créés, lus ou modifiés
- Actions effectuées - choses concrètes qui se sont passées, avec identifiants
- Décisions prises - choix stratégiques et leur justification
- Éléments à venir - actions pour la prochaine session, commençant par un verbe ("déployer...", "suivre...", "vérifier...")
- Avertissements - risques actifs, obstacles, échéances, quasi-accidents
- Leçons apprises - améliorations opérationnelles (qui alimentent la Phase 2)
- Captures supplémentaires - données pour toute clé d'état / catégorie supplémentaire dans la configuration
Étape 3 - Injecter dans la base de données du plugin
En mode preview, n'appelez rien qui modifie. Signalez les écritures prévues (Étape 4) et arrêtez.
- État de session -
memory_set_state("session", { last_session, summary, forward, entities_touched, warnings }). Les éléments à venir sont uniquement des références d'actions, jamais d'instantanés de solde ou quoi que ce soit qui deviendrait obsolète. - Événement de journal -
memory_record_event("session_save", { evaluated, acted, forward, extra }). Un événement par sauvegarde (append-only par conception). - Priorités -
memory_set_state(<clé des priorités>, { updated, cap, items }), plafonné. Trop-plein vers un document d'état de backlog. - Entités - pour chaque entité modifiée,
memory_remember(category, name, body). Les nouvelles entités sont simplement de nouveaux appelsmemory_remember; le plugin les indexe, donc il n'y a pas de registre séparé à maintenir. - Fermé / mort -
memory_forget(category, name, reason). - Captures supplémentaires - appliquez chaque clé d'état / catégorie supplémentaire configurée.
- Marqueur delta -
memory_set_state("sibyl_save:last_save", { ts: <maintenant> }). Ignoré en mode preview.
Étape 4 - Rapport
Résumé concis : entités écrites, documents d'état mis à jour, identifiant d'événement de journal, priorités ajoutées/fermées, captures supplémentaires et éléments à venir pour la prochaine session. En mode preview, marquez chaque ligne avec "serait" et confirmez que rien n'a été écrit.
Phase 2 : Extraction de compétences (natif du harnais)
Les compétences sont présentées de la même manière quel que soit le harnais : identifier, proposer, puis créer en tant que fichier de compétence natif pour le harnais actuel.
Étape 5 - Identifier les motifs réutilisables
Parcourez la session à la recherche d'opérations remplissant N'IMPORTE LEQUEL de ces critères : répétée (plus d'une fois cette session), récurrente (probablement à nouveau), multi-étapes (3+ étapes séquentielles), non évidente (un contournement qui mérite d'être conservé), sujette aux erreurs (nécessite une liste de contrôle). Pour chaque candidat, évaluez le nom (phrase verbale impérative courte), le déclencheur, les paramètres, la complexité (toute étape dangereuse), la fréquence.
Étape 6 - Proposer les candidats
Présentez chacun sous forme d'une ligne avec nom, description et fréquence estimée. Demandez ensuite : "Créer ces compétences ? ou en sauter ?"
Étape 7 - Créer les compétences approuvées (natif du harnais)
Lisez skill_output depuis la configuration pour savoir où et dans quel format ce harnais attend les compétences. Valeurs par défaut :
| Harnais | Emplacement de la compétence | Format |
|---|---|---|
| claude-code | .claude/skills/<nom>/SKILL.md | Frontmatter YAML (nom, description) + corps Markdown |
| codex | ~/.codex/prompts/<nom>.md (confirmer en setup) | Invite Markdown |
| cursor | .cursor/ commande/règle (confirmer en setup) | selon la convention Cursor |
| autre | depuis skill_output.dir | depuis skill_output.format |
Pour chaque compétence approuvée, écrivez le fichier à l'emplacement configuré avec des phrases de déclenchement, des instructions étape par étape, des descriptions de paramètres, des vérifications de sécurité pour toute étape dangereuse et un exemple d'invocation. Signalez le chemin.
NE CRÉEZ PAS de compétences qui : dupliquent une compétence existante (vérifiez d'abord l'emplacement), sont trop spécifiques à une session pour se reproduire, encapsulent une seule commande triviale, ou nécessitent de modifier des fichiers que vos règles d'exploitation protègent (signalez-les, ne les modifiez pas vous-même).
Règles (non négociables)
- Ne stockez jamais de données volatiles (soldes, prix, comptages) comme des faits durables. Capturez des références, pas des instantanés.
- Les éléments à venir de session sont orientés action et commencent par un verbe.
- Un événement de journal par sauvegarde (append-only ; ne réécrivez jamais l'historique).
- Les priorités sont plafonnées (défaut 15, jamais au-dessus de 30). Trop-plein vers un document d'état de backlog.
- Les entités sont adressées par
catégorie+nom; laissez le plugin être l'index. Pas de registre parallèle. - Toutes les écritures mémoire passent par l'interface du plugin. N'écrivez jamais de fichiers
~/.sibyl-memory/et n'ouvrez pasmemory.dbdirectement : le client gère le verrouillage et la limite du niveau gratuit. - Considérez les compétences existantes comme en lecture seule. Créez-en de nouvelles plutôt que de modifier sur place, sauf demande explicite.
Licence et provenance
MIT (voir LICENSE). Le commentaire de filigrane en haut de chaque fichier Markdown est une attribution et une provenance, pas une restriction d'utilisation. Vérifiez une copie avec node scripts/watermark.mjs verify. Détails dans WATERMARK.md.