~/ devbyben
#MIRA#Hermes Agent#MCP

Brancher MIRA à Hermes Agent : une mémoire longue durée qui reste utile

Un tutoriel pour installer MIRA à côté d'Hermes Agent, le connecter avec MCP et garder une mémoire de projet locale, ciblée et économe en tokens.

10 min de lecture
Résumé IA

Générez un résumé de cet article en un clic.

Hermes Agent sait déjà garder des sessions, des fichiers de contexte et une mémoire de travail. Quand ton agent change de modèle, de canal ou de projet, tu as vite besoin d'un rappel plus précis : quelle décision a été prise, pourquoi elle l'a été et quelle contrainte doit rester valable.

MIRA répond à ce besoin. C'est un serveur MCP local qui conserve les souvenirs sous plusieurs formes, puis choisit la représentation qui apporte le plus d'information dans le budget de tokens disponible.

Dans ce tutoriel, tu vas ajouter MIRA à l'installation Docker d'Hermes Agent. Hermes restera l'agent que tu utilises depuis le terminal, Telegram ou le WebUI. MIRA sera un service séparé, avec son propre stockage persistant.

Note

Ce guide part duboilerplate Docker Hermes Agent présenté dans mon article sur Hermes. Si tu utilises Hermes directement sur ta machine, je te donne aussi la variante stdio plus bas.

Ce que MIRA ajoute à Hermes

Hermes possède une mémoire utile pour ses sessions et ses profils. MIRA ajoute une couche spécialisée dans le rappel de décisions et de faits, avec une organisation par projet.

Chaque souvenir existe en trois niveaux :

  • T0 garde le texte original quand tu dois relire le détail ;
  • T1 conserve une empreinte structurée avec les faits, les entités et les décisions ;
  • T2 sert à la recherche sémantique avec un embedding local.

Lors d'un rappel, MIRA combine recherche vectorielle et recherche textuelle. Son algorithme CBA sélectionne ensuite les souvenirs selon leur pertinence, leur densité d'information, leur récence et le budget demandé.

Tu peux donc demander à Hermes :

Pourquoi avons-nous gardé PostgreSQL pour ce projet ?

Tu récupères la décision et sa raison sans charger plusieurs anciennes conversations dans le contexte.

MIRA propose aussi des outils soul_* pour conserver une continuité d'identité entre les modèles. Ils sont utiles si tu veux que ton agent garde certaines habitudes de collaboration. L'intégration ci-dessous commence avec les outils mémoire mira_*.

L'architecture

Le montage tient en trois blocs :

Telegram / WebUI / CLI
          │
          ▼
   Hermes Agent ───── MCP HTTP ─────► MIRA
       │                              │
       └── data_runtime/              └── volume mira-data

Le réseau Docker permet à Hermes d'appeler MIRA avec http://mira:3001/mcp. Le port MCP n'a pas besoin d'être publié sur ta machine : seuls les services du même réseau doivent y accéder.

Cette séparation garde les fichiers Hermes à part de la base SQLite de MIRA. Tu peux mettre à jour l'un sans déplacer les données de l'autre.

1. Préparer les dépôts

Depuis le dossier qui contient ton installation hermes-agent-docker, clone MIRA à côté du projet :

git clone https://github.com/benoitpetit/mira.git
cd hermes-agent-docker

Le dépôt MIRA fournit déjà un Dockerfile multi-stage. Il compile le binaire avec Go 1.25 et SQLite/FTS5, puis l'exécute dans une image Alpine avec un utilisateur non privilégié.

Tu peux vérifier que le sous-dossier attendu existe :

hermes-agent-docker/
├── config/
├── data_runtime/
├── docker-compose.yml
└── mira/
    ├── Dockerfile
    ├── go.mod
    └── cmd/mira/

2. Ajouter MIRA au Compose

Ouvre docker-compose.yml et ajoute ce service sous services: :

  mira:
    build:
      context: ./mira
      dockerfile: Dockerfile
    command:
      - server
      - --transport
      - http
      - --mcp-addr
      - 0.0.0.0:3001
    environment:
      MIRA_STORAGE_TYPE: sqlite
      MIRA_DATA_PATH: /home/mira/.mira
    expose:
      - "3001"
    volumes:
      - mira-data:/home/mira/.mira
    restart: unless-stopped

  # ... services hermes et hermes-webui déjà présents ...

volumes:
  hermes-agent-src:
  mira-data:

Le command remplace le mode stdio par le transport HTTP stateless de MIRA. expose rend le port visible aux autres services Docker sans l'ouvrir sur localhost.

Le volume mira-data contient la base, les embeddings et le modèle téléchargé lors du premier démarrage. Ne le remplace pas par un dossier temporaire si tu veux retrouver tes souvenirs après une recréation des conteneurs.

Avertissement

N'ajoute pas3001:3001 dans la configuration finale si Hermes est le seul client. Un port publié expose MIRA à l'extérieur de Docker. Si tu dois tester l'API depuis l'hôte, lie-le à 127.0.0.1:3001:3001 et active un jeton d'accès dès que le service sort de la machine.

3. Déclarer MIRA dans Hermes

Le dépôt Hermes utilise la clé mcp_servers dans config/config.yaml. Ajoute l'entrée suivante :

mcp_servers:
  mira:
    url: "http://mira:3001/mcp"
    timeout: 120
    connect_timeout: 60
    trust: full

Si ton fichier contient déjà mcp_servers, ajoute seulement le bloc mira sous cette clé. Ne crée pas un second bloc YAML avec le même nom.

Le paramètre trust: full correspond ici à un serveur que tu compiles et exécutes dans la même stack. Si tu remplaces l'URL par un serveur MIRA qui ne t'appartient pas, utilise plutôt trust: untrusted et vérifie chaque outil d'écriture.

Cette configuration HTTP évite aussi de transmettre des variables d'environnement au processus MIRA. Le service ne reçoit aucune clé de fournisseur de modèle : MIRA calcule ses embeddings localement.

4. Synchroniser et démarrer

Le boilerplate Hermes garde config/ comme source et copie les fichiers vers data_runtime/. Synchronise la configuration avant de lancer les conteneurs :

./scripts/sync-runtime-config.sh
docker compose build mira
docker compose up -d mira hermes hermes-webui

Le premier démarrage peut prendre un peu plus de temps : MIRA prépare sa base et télécharge son modèle d'embedding local. Surveille les journaux avec :

docker compose logs -f mira

Tu dois voir le serveur écouter sur 0.0.0.0:3001. Vérifie ensuite que les conteneurs sont actifs :

docker compose ps
docker compose logs hermes | grep -i mira

Si tu modifies config/config.yaml alors qu'Hermes tourne déjà, redémarre au minimum le service Hermes :

./scripts/sync-runtime-config.sh
docker compose restart hermes

Hermes découvre les outils MCP au démarrage. Après la connexion, ils apparaissent avec un préfixe du type mcp__mira__mira_recall ou mcp__mira__mira_store, selon la version d'Hermes utilisée.

5. Tester la mémoire

Commence par demander à Hermes d'enregistrer une décision explicite :

Enregistre dans MIRA, wing hermes-demo, room decisions :
pour ce projet, on utilise PostgreSQL parce que l'équipe maîtrise déjà
les migrations et que JSONB couvre nos besoins.

Puis demande un rappel ciblé :

Rappelle-moi pourquoi la base de données de hermes-demo est PostgreSQL.

Tu peux aussi utiliser les outils directement si ton interface affiche les appels MCP :

{
  "query": "Pourquoi PostgreSQL pour hermes-demo ?",
  "wing": "hermes-demo",
  "budget": 1200
}

Le champ wing est important. Utilise le même nom pour toutes les mémoires d'un projet, par exemple hermes-demo, puis réserve general aux préférences qui s'appliquent à tous tes agents.

Faire travailler la mémoire

Donne à Hermes une règle simple : rappeler le contexte avant de décider, puis enregistrer ce qui mérite de survivre à la session.

Pour une décision d'architecture :

  1. demande un mira_recall sur le projet concerné ;
  2. vérifie que l'ancienne décision s'applique toujours ;
  3. demande un mira_store de type decision si tu confirmes ou modifies le choix.

Pour un bug, stocke la cause et la correction comme debug_log. Pour une préférence de collaboration, utilise preference. Les notes de session conviennent au contexte temporaire, avec une durée de vie plus courte.

Tu peux ajouter cette consigne à config/SOUL.md :

## Mémoire MIRA

Pour le projet courant, utilise le wing `hermes-demo`.
Avant une décision technique, rappelle les décisions existantes avec MIRA.
Après une décision, un fait durable ou la résolution d'un bug, stocke un résumé
court dans le room adapté. N'enregistre jamais de secret, de token ou de mot de passe.

Adapte hermes-demo au nom réel de ton projet. Cette règle indique à Hermes quand consulter la mémoire et quoi conserver.

Variante sans Docker

Si Hermes et MIRA tournent directement sur la même machine, tu peux rester en stdio. Compile MIRA ou installe un binaire depuis ses releases, puis déclare son chemin absolu dans la configuration Hermes :

mcp_servers:
  mira:
    command: "/home/ben/bin/mira"
    args:
      - "--config"
      - "/home/ben/.config/mira/config.yaml"
      - "server"
    timeout: 120
    connect_timeout: 60

Dans cette variante, configure le stockage dans le fichier MIRA et laisse le serveur en transport stdio. Le chemin doit être accessible par le même utilisateur que celui qui lance Hermes. Dans un conteneur, un chemin de l'hôte comme /home/ben/bin/mira n'existe pas automatiquement : utilise le service Docker décrit plus haut ou monte explicitement le binaire et ses données.

Dépannage rapide

Les outils MIRA n'apparaissent pas

Vérifie la clé mcp_servers, l'indentation YAML et l'URL http://mira:3001/mcp. Si tu as modifié config/config.yaml, relance sync-runtime-config.sh puis redémarre Hermes.

Hermes ne joint pas MIRA

Depuis le réseau Compose, le nom à utiliser est mira, pas localhost. localhost pointerait vers le conteneur Hermes lui-même. Consulte ensuite les logs :

docker compose logs mira hermes

Le premier lancement est lent

Le modèle d'embedding est téléchargé lors de la première initialisation. Attends la fin du téléchargement avant de conclure à un problème de connexion. Le volume mira-data évite de recommencer à chaque recréation du conteneur.

La mémoire est trop bavarde

Réduis le budget passé à mira_recall, précise la requête et sépare les sujets avec des rooms. Un budget de 500 à 1 000 tokens convient à un rappel ponctuel ; garde 2 000 à 4 000 tokens pour le contexte de travail courant.

Ce que cette intégration ne règle pas

MIRA ne transforme pas Hermes en agent infaillible. Une mémoire peut être incomplète, mal classée ou dépassée par un nouveau choix. Vérifie les décisions rappelées avant de les appliquer.

La mémoire reste locale dans cette architecture, mais les messages envoyés par Hermes à ton fournisseur de modèle suivent les règles de ce fournisseur. Évite donc d'enregistrer des secrets et protège les interfaces Hermes si tu ajoutes un accès distant.

Pour sauvegarder les souvenirs, traite le volume MIRA comme une donnée applicative. Le projet fournit des scripts d'export JSON ou Markdown ; tu peux aussi sauvegarder le volume avec ta stratégie Docker habituelle. Teste une restauration avant d'en avoir besoin.

Hermes conserve ses canaux et ses outils. Les décisions que tu stockes dans MIRA restent disponibles entre deux sessions.

Pour aller plus loin

Article co-écrit avec l'IA · Images générées avec l'IA.