# Hermes

Verbinden Sie Hermes Agent über dessen natives Speicher-Plugin auf PyPI mit Sitzungs-Checkpointing, automatischer Erfassung und dauerhaftem Projektspeicher.

- Canonical: https://docs.xmemo.dev/de/docs/connect/hermes
- Locale: de-DE
- Content-Locale: de-DE
- Canonical-Content-Digest: bc9df4e1a62a317f42328c5fb35b354a1666ef85ea9f18ff6c96dbf5dccbdd9f
- Edition-Digest: 16036f218e009743f94b7f71ed67711f3301a2f5811272c780f1e55be2fffb00
- Source-Revision: sha256:c1c2001f12dcea28dab430debe91620cc57ef3d7fced5162a27e2afa3fe87072

## Zielgruppe und konkrete Schnittstelle

Diese Anleitung verbindet Hermes Agent mit dem persistenten Speicher von XMemo. Hermes integriert sich über das gepflegte native Speicher-Plugin-Paket hermes-xmemo (Version 1.1.3) auf PyPI, verankert im aktiven Repository yonro/hermes-xmemo-plugin @ 30fe1bc20a (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md). Beachten Sie, dass das archivierte Repository yonro/xmemo-hermes-plugin @ eb47797a08 lediglich als Referenz für Legacy-Migrationen dient; alle Neuinstallationen nutzen hermes-xmemo.

## Voraussetzungen

Stellen Sie sicher, dass vor dem Verbinden die folgenden Laufzeitabhängigkeiten und Werkzeuge vorhanden sind:

- Hermes Agent CLI und Laufzeitumgebung installiert (Python 3.10+).
- Python-Paketmanager (pip).
- Gültiges XMemo-Konto unter https://xmemo.dev.
- Netzwerkzugriff auf https://xmemo.dev/mcp über HTTPS.

## Installation

Installieren Sie den Hermes XMemo-Provider über den offiziellen Hermes-Plugin-Marktplatz. Falls Ihre Hermes-Version den Marktplatz-Befehl nicht bereitstellt, verwenden Sie den festgelegten PyPI-Fallback.

```bash
hermes plugins install xmemo

# Fallback for older Hermes versions
pip install hermes-xmemo
hermes memory setup xmemo
```

## Autorisierung und Konfiguration der Anmeldedaten

Konfigurieren Sie die Authentifizierung über eine Umgebungsvariable oder die Hermes-Konfiguration. Hinterlegen Sie niemals rohe Bearer-Token in der Versionskontrolle:

- Umgebungsvariable (empfohlen): Setzen Sie XMEMO_KEY in der Shell oder Umgebung, die Hermes startet (export XMEMO_KEY='<your-xmemo-token>').
- Hermes-Einrichtungsassistent: Das Ausführen von hermes memory setup xmemo fragt Anmeldedaten ab und konfiguriert ~/.hermes/config.yaml.
- Konfigurationsprüfung: Vergewissern Sie sich, dass in ~/.hermes/config.yaml memory.provider auf xmemo gesetzt ist.

## Lade- und Neustartverhalten

Verfahren zum Neustart des Daemons oder zum Neuladen von Sitzungen sind in der README des hermes-xmemo-Plugins (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md) nicht explizit dokumentiert; konsultieren Sie die Host-Dokumentation von Hermes Agent oder starten Sie Ihre aktive Hermes-Terminalsitzung neu.

## Verbindungsprüfung (schreibgeschützt)

Überprüfen Sie die Verbindung mit einer rein lesenden Abrufanfrage, bevor Sie dauerhafte Daten schreiben. Diese Prüfung verändert den Speicherzustand nicht:

- Prüfung: Starten Sie eine Hermes-Testsitzung und führen Sie eine rein lesende aktive Abfrage nach bestehendem Projektkontext aus.
- Erfolgssignal: Hermes liefert strukturierte Speicherergebnisse mit gültigen Reference- und Location-Feldern aus dem autorisierten Arbeitsbereich zurück.

## Erste nützliche Aufgabe: Synthetischer Speicherlebenszyklus

Verifizieren Sie Speicherpersistenz, zustandslosen Sitzungsübergang, quellenzugeordneten Abruf und Korrektur:

- 1. Synthetischen Fakt speichern: Speichern Sie eine Projektkonvention ("Hermes demo conventions: UTC logging with ISO 8601 timestamps.") unter "projects/demo-hermes/conventions".
- 2. Zustandsloser Übergang: Beenden Sie die aktuelle Hermes-Unterhaltung und starten Sie eine neue Sitzung.
- 3. Abruf mit Quellenzuordnung: Fragen Sie "demo conventions timestamp format" ab. Bestätigen Sie die zurückgegebenen Felder Reference und Location.
- 4. Speicher korrigieren: Aktualisieren Sie die gespeicherte Konvention mit update_memory unter Angabe aktualisierter Formatierungsregeln.
- 5. Optionale Bereinigung: Führen Sie ein Soft-Delete (forget) für die Demo-Konvention durch, sobald die Onboarding-Verifizierung abgeschlossen ist.

## Automatische Erfassung und Duplikatvermeidung

Hermes Agent bietet eine automatische Kontexterfassung über Ausführungsgrenzen hinweg:

- Sitzungs-Checkpointing: Wenn in ~/.hermes/config.yaml aktiviert, erfasst Hermes Sitzungszusammenfassungen und wichtige Entscheidungen an Meilensteinen von Sitzungsgrenzen.
- Duplikatvermeidung: Eine integrierte Inhaltshash-Deduplizierung stellt sicher, dass identische Fakten und Entscheidungen bei iterativen Ausführungsschleifen nicht wiederholt geschrieben werden.
- Bereichsgrenze: Jeder erfasste Speicher ist strikt auf den Arbeitsbereich des authentifizierten Benutzers und den aktiven Projektbereich isoliert.

## Provider-Konflikte und Speichergrenzen

Verstehen Sie die Laufzeitisolation und die Speicherzuständigkeit:

- Provider-Konflikte: Aktivieren Sie nicht mehrere Speicher-Provider gleichzeitig in ~/.hermes/config.yaml. Die gleichzeitige Ausführung überlappender Provider führt zu geteilten Abrufen (Split-Brain).
- Speicherzuständigkeit: Alle dauerhaften Speicher verbleiben im benutzerkontrollierten XMemo-Cloud-Backend. Hermes verwaltet lediglich einen kurzlebigen lokalen Cache für die Reaktionsfähigkeit der Sitzung.
- Offline- und Replay-Grenzen: Vorübergehende Netzwerkunterbrechungen werden von einem begrenzten lokalen Schreibpuffer abgefangen; Offline-Schreibvorgänge schlagen fehl, wenn das Pufferlimit oder der Token-Ablauf erreicht ist, und nicht übertragene Aktionen werden erst nach Wiederherstellung der Verbindung zu anderen Agenten repliziert.

## Wiederherstellung, Aktualisierung und Entfernung

Verfahren zur Fehlerbehebung, Aktualisierung und Entfernung für Hermes:

- Wiederherstellung (401 invalid_token): Überprüfen Sie, ob XMEMO_KEY in der aktuellen Shell-Umgebung oder der Hermes-Konfiguration gesetzt ist.
- Aktualisierung: Befehle zur Plugin-Aktualisierung sind in der README des hermes-xmemo-Plugins (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md) nicht dokumentiert; führen Sie pip install --upgrade hermes-xmemo aus oder konsultieren Sie die Host-Dokumentation von Hermes.
- Entfernung (README Zeile 292): Um den Speicher-Provider in Hermes zu deaktivieren, führen Sie den dokumentierten Entfernungsbefehl aus: hermes config set memory.provider "".
- Entfernung im Vergleich zu Remote-Löschung: Das Deaktivieren des lokalen Providers löscht keine gespeicherten Remote-Speicher und widerruft keine API-Anmeldedaten; löschen Sie Speicher oder widerrufen Sie Schlüssel unter https://xmemo.dev/me.

```bash
hermes config set memory.provider ""
```