Fournisseurs de Mémoire Externes

Que fait Fournisseurs de Mémoire Externes ?

Installez, configurez et vérifiez les fournisseurs de mémoire tiers pour Hermes Agent. Considérez « installé » et « actif dans Hermes » comme des critères d'acceptation distincts.

Principes

1. Partez de la documentation officielle actuelle. Chargez le skill hermes-agent, puis récupérez à la fois la page d'installation du fournisseur et sa page d'intégration complète Hermes. Suivez le chemin recommandé par la documentation ; utilisez une solution de repli documentée uniquement si une contrainte réelle de compatibilité l'exige.
2. Gardez les dépendances en dehors du venv géré par Hermes. Les mises à jour d'Hermes peuvent reconstruire ce venv. Privilégiez pipx ou un venv persistant dédié.
3. Faites correspondre les ABI Python à la frontière du pont. Un environnement pipx peut utiliser un Python plus récent qu'Hermes. Ajouter ses site-packages au sys.path d'Hermes est dangereux lorsque des wheels natives sont impliquées. Utilisez un venv dédié créé avec le Python d'Hermes lorsqu'un wrapper exécute des imports dans le processus.
4. Utilisez la CLI Hermes pour la configuration. Ne modifiez jamais config.yaml manuellement ; appliquez les paramètres avec hermes config set.
5. Ne désactivez pas l'ensemble d'outils mémoire partagés. Lorsque vous remplacez la mémoire fichier existante, désactivez uniquement les indicateurs fichier/profil intégrés documentés pour le fournisseur. Une désactivation générique hermes tools disable memory peut également masquer les outils du fournisseur.
6. Tenez compte de la mise en cache des invites (prompt caching). Les modifications du fournisseur/outils s'appliquent aux sessions nouvellement initialisées. Ne modifiez pas l'invite système ni le schéma d'outils d'une conversation existante ; redémarrez la passerelle et indiquez clairement qu'une session TUI déjà en cours doit être remplacée.

Workflow d'Installation

1. Auditez avant de modifier l'état

Enregistrez :

• hermes --version et la version/chemin Python d'Hermes
• les versions des paquets du fournisseur et leurs environnements d'installation
• la sortie de l'installateur/statut du fournisseur
• hermes plugins list --plain --no-bundled
• hermes config get memory.provider
• hermes memory status
• le statut de la passerelle

N'extrapolez pas [all] ou des extras équivalents à partir de la version du paquet de base. Importez ou inspectez chaque dépendance de capacité nommée par la documentation du fournisseur.

2. Choisissez une topologie d'isolation

• Utilisez pipx lorsque le fournisseur communique hors processus ou qu'Hermes découvre un point d'entrée de paquet sûr.
• Utilisez un venv dédié construit à partir du Python d'Hermes lorsque ce dernier importe le code du fournisseur dans le processus et que le paquet inclut des extensions natives.
• Ne considérez jamais importlib.util.find_spec() comme une preuve de compatibilité. Il localise des modules sans charger de code natif. Effectuez des imports réels sous l'interpréteur qui exécutera le fournisseur.

3. Installez le fournisseur et le pont

Installez le profil de fonctionnalité complet demandé et son wrapper Hermes. Si le wrapper fournit une commande d'installation/statut, utilisez-la pour créer le pont de plugin persistant sous $HERMES_HOME/plugins/ et vérifiez son import.

Activez explicitement les plugins utilisateur lorsque Hermes les liste comme optionnels :

hermes plugins enable <manifest-name>

La sélection du fournisseur et l'activation des plugins généraux peuvent être des mécanismes séparés. Vérifiez les deux.

4. Configurez sans duplication

Définissez le fournisseur externe et, si la documentation du fournisseur l'indique, désactivez la mémoire fichier existante tout en conservant l'ensemble d'outils mémoire :

hermes config set memory.provider <provider>
hermes config set memory.memory_enabled false
hermes config set memory.user_profile_enabled false

Utilisez les clés documentées actuelles du fournisseur plutôt que de supposer qu'elles sont universelles.

5. Redémarrez et vérifiez

Redémarrez la passerelle uniquement une fois l'installation, l'activation et la configuration terminées. Vérifiez ensuite :

• La passerelle est active.
• Le pont du plugin/statut indique installé et importable.
• La liste des plugins généraux indique activé lorsque des hooks/outils en dépendent.
• hermes memory status indique que le fournisseur sélectionné est installé, disponible et actif.
• Les diagnostics du fournisseur ne contiennent aucun enregistrement d'erreur/d'échec réel. Ne confondez pas les compteurs, les mesures, les vérifications ignorées ou les remplacements optionnels non définis avec des échecs.

6. Testez le chemin de l'agent Hermes

Un test simple du SDK autonome est nécessaire mais insuffisant. Chargez le fournisseur via le chargeur de fournisseur mémoire d'Hermes ou démarrez un nouvel agent Hermes, puis vérifiez :

1. la construction et l'initialisation du fournisseur ;
2. le bloc d'invite système du fournisseur est actif ;
3. les schémas d'outils du fournisseur sont exposés ;
4. écrivez une mémoire de test avec un tag unique ;
5. rappelez ce tag exact ;
6. supprimez la mémoire de test ;
7. confirmez que la base de données/chemin du fournisseur est le magasin Hermes prévu.

Utilisez des assertions et échouez la commande de vérification si une étape échoue. Rapportez les versions/statuts exacts observés, pas des attentes plausibles.

Pièges Courants

• Les venv pipx séparés ne sont pas « côte à côte » pour les imports dans le processus. Le cœur et le wrapper peuvent chacun fonctionner seuls tandis qu'Hermes ne peut pas importer les deux de manière sécurisée.
• Plugin découvert ne signifie pas plugin activé. La découverte du fournisseur peut réussir tandis que l'enregistrement des hooks/outils reste optionnel.
• L'absence de commande CLI ne prouve pas l'échec du fournisseur. Hermes peut charger le fournisseur tandis qu'un installateur a omis le cli.py frère utilisé pour la découverte argparse. Diagnostiquez les chemins du fournisseur et de la CLI indépendamment, puis réparez uniquement avec un pont testé.
• Le redémarrage de la passerelle ne met pas à jour la session actuelle. Les nouvelles sessions de passerelle et de CLI utilisent le fournisseur ; un processus TUI ancien conserve sa surface d'invite/outils figée.
• Une commande d'installation réussie n'est pas une fin. Exigez une configuration relue, un statut de fournisseur actif et un cycle réel d'écriture/rappel/nettoyage.

Références des Fournisseurs

• Mnemosyne + intégration Hermes, gestion des ABI Python, pont CLI et test déterministe : references/mnemosyne-hermes.md