# ZimaOS Hermes Setup — Session-Specific Reference

**System:** ZimaOS (Linux 6.12.25, x86_64), NAS/Server-Umfeld  
**Hermes Home:** `/DATA/AppData/hermes` (NICHT `~/.hermes` — ZimaOS nutzt `/DATA` als persistenten Storage)  
**User:** `az-a` (normaler Benutzer, kein root)  
**Gateway:** Läuft als systemd-Service, manchmal doppelte Prozesse (root + az-a)

---

## Wichtige Pfade

| Was | Pfad |
|-----|------|
| Hermes Home | `/DATA/AppData/hermes` |
| venv / CLI | `/DATA/AppData/hermes/venv/bin/hermes` |
| Config | `/DATA/AppData/hermes/config.yaml` |
| Secrets | `/DATA/AppData/hermes/.env` |
| Sessions | `/DATA/AppData/hermes/sessions/*.jsonl` |
| Memories | `/DATA/AppData/hermes/memories/USER.md` + `MEMORY.md` |
| AGENTS.md | `/DATA/AppData/hermes/AGENTS.md` |
| Work-Ordner | `/DATA/AppData/hermes/work/` |
| Skills | `/DATA/AppData/hermes/skills/` |

**Wichtig:** `hermes` CLI ist **nicht im PATH**. Muss immer mit venv-Pfad oder `PATH` export aufgerufen werden:
```bash
export PATH=/DATA/AppData/hermes/venv/bin:$PATH
export HERMES_HOME=/DATA/AppData/hermes
hermes <command>
```

---

## Gateway Restart & Session-Verlust

**Problem:** Nach Gateway-Restart hat `session_search` keine Ergebnisse.
**Ursache:** Der in-memory Index wird gelöscht, die `.jsonl` Dateien liegen aber weiterhin auf der Platte.
**Lösung:**
1. `session_search(limit=5, query="*")` — mit `limit` und `query` erzwingen
2. Falls leer: Direkt Dateien lesen aus `/DATA/AppData/hermes/sessions/*.jsonl`
3. Memories (`USER.md`, `MEMORY.md`) und `AGENTS.md` laden
4. `work/` Ordner nach Deliverables durchsuchen

**Wichtige Erkenntnis:** Die Session-History ist die einzige Informationsquelle, die bei einem Restart verloren geht. Alle persistenten Daten (Memories, Config, AGENTS.md, Skills, Work-Dateien) überleben.

**Config-Änderungen überleben NICHT immer:**
In diesem Setup wurde `memory.provider = honcho` via `hermes config set` geschrieben, aber nach einem Gateway-Restart war es wieder auf `built-in only`. Mögliche Ursachen:
- `hermes memory setup` (ohne Argumente) überschreibt provider zurück auf `built-in`
- Der systemd-Service liest config beim Start und cached sie — Änderungen während der Laufzeit werden evtl. überschrieben

**Konkret:** Wenn du den Memory-Provider wechseln willst, **schreibe direkt in `config.yaml`** statt `hermes config set` zu verwenden, UND starte den Gateway neu:
```bash
# Direkt editieren (muss gateway_neu_gestartet werden)
sed -i 's/provider: built-in/provider: honcho/' /DATA/AppData/hermes/config.yaml
# Dann: sudo systemctl restart hermes-gateway
```
Oder: Verwende `hermes config set`, danach **AUF KEINEN FALL** `hermes memory setup` aufrufen — das setzt es zurück.

---

## Honcho Memory Plugin — Status

**Python Library:** `honcho` v2.1.1 ist installiert im venv  
**CLI Integration:** `hermes honcho setup` existiert **NICHT** in diesem Build  
**Provider-Wechsel:** `hermes config set memory.provider honcho` funktioniert  
**Aber:** Status zeigt `not available` weil kein Honcho-Server läuft  

**Optionen für lokale Nutzung:**
- Cloud: API-Key von app.honcho.dev nötig
- Self-hosted: Docker + Postgres komplex
- **Pragmatische Empfehlung:** Built-in Memory nutzen — es reicht für 95% der Use-Cases

---

## Disk / Speicher-Probleme

**ZimaOS-Struktur:**
- `/` (Root): ~1.2 GB, schnell voll. `pip install` schreibt nach `/tmp` (tmpfs → RAM)
- `/DATA` (SSD): ~165 GB frei. Hier liegt Hermes Home.
- `/tmp`: tmpfs (RAM-Disk), 3.9 GB. Wird schnell voll bei großen Downloads/Entpacken.

**Typisches Problem:** `pip install torch` → 530 MB Wheel + Entpacken = ~1.5 GB → `/tmp` voll → Fehler.

**Lösungen:**
1. Vor großen Installs `/tmp` aufräumen
2. `TMPDIR=/DATA/AppData/hermes/.tmp pip install ...` (alternatives Temp-Verzeichnis)
3. Leichtere Alternativen bevorzugen (z.B. `faster-whisper` statt `openai-whisper`)

---

## Erkannte Skills, die der Nutzer hat

- `himalaya` — Email (GMX Postfach: amadeus.bot@gmx.at)
- `notion` — Notion API verbunden
- `youtube-content` — Video-Analyse
- `hermes-agent` — Diese Skill selbst
- 85+ weitere installierte Skills

---

## Docker Build Workaround auf ZimaOS

ZimaOS hat mehrere Docker-Eigenheiten, die Builds erschweren:

| Problem | Ursache | Workaround |
|---------|---------|------------|
| `docker compose` nicht gefunden | Docker Plugin fehlt | `docker` direkt nutzen, kein compose |
| `ERROR: mkdir /root/.docker: read-only file system` | Root-FS ist read-only | `HOME=/tmp` setzen |
| `sudo: sorry, you are not allowed to preserve the environment` | sudoers erlaubt kein `-E` | `env` vor `sudo` nutzen |
| Zugriff auf `/var/run/docker.sock` nur mit sudo | User `az-a` nicht in `docker` Gruppe | Immer `sudo docker ...` |

**Funktionierender Build-Befehl:**
```bash
sudo env HOME=/tmp sh -c 'cd /Pfad/zum/projekt && docker build --no-cache -t imagename .'
```

**Funktionierender Container-Start (bridge-Netzwerk, mit Labels für CasaOS):**
```bash
sudo docker run -d \
  --name AppName \
  --restart unless-stopped \
  --network bridge \
  -p PORT:PORT \
  -v /media/HDD_1TB/path:/data \
  -e PORT=PORT \
  imagename
```

**Container stoppen/entfernen:**
```bash
sudo docker stop AppName && sudo docker rm AppName
```

## CasaOS app-management.json — Überlebt Reboot NICHT

**Kritische Erkenntnis:** `/etc/casaos/app-management.json` wird beim Boot aus dem App-Store-Cache neu generiert. Manuelle Änderungen (app_type, port, scheme, index) gehen beim Reboot verloren.

**Konsequenz:** Nach jedem Server-Reboot müssen PrintVault und DocMaster neu in `app-management.json` registriert werden.

**Fix-Skript (nach jedem Reboot ausführen):**
```python
import json, subprocess

with open('/etc/casaos/app-management.json') as f:
    data = json.load(f)

for app in data:
    title_raw = app.get('title', {})
    title_en = title_raw.get('en_US', '') if isinstance(title_raw, dict) else ''

    if 'PrintVault' in title_en:
        app['app_type'] = 'container'
        app['port'] = '3001'
        app['scheme'] = 'http'
        app['index'] = '/'
        app['hostname'] = 'localhost'

    if title_en.lower() == 'docmaster':
        app['app_type'] = 'container'
        app['port'] = '3000'
        app['scheme'] = 'http'
        app['index'] = '/'
        app['hostname'] = 'localhost'

new_json = json.dumps(data, indent=2)
with subprocess.Popen(['sudo', 'tee', '/etc/casaos/app-management.json'],
                       stdin=subprocess.PIPE, stdout=subprocess.DEVNULL) as p:
    p.communicate(new_json.encode())

# Dann:
# sudo systemctl restart zimaos-app-management
```

**JSON-Struktur beachten:** `title` ist ein i18n-Dict, nicht einfacher String:
```json
{"title": {"en_US": "PrintVault"}}
```
→ Parsen mit `title_raw.get('en_US', '')`, nicht direkt als String.

**Achtung:** `zimaos-app-management` restart reicht. Ein zweiter Reboot ist NICHT nötig — die Änderung greift sofort im Dashboard.

## Nutzer-Präferenzen (aus dieser Session | historical snapshot)

- Kurze, prägnante Antworten. Keine Wiederholungen.
- Non-technical — proaktiv erklären bei System-Änderungen
- Deutscher Sprachraum, Wirtschaftsrecht, ÖAMTC, YouTube-Kanal
- Frust mit OpenClaw → deshalb Hermes/Kiwi
- Will autonomes Handeln, aber Schutz vor destruktiven Aktionen
- Avatar: Pixel-Art Wizard Kiwi (brauner Kiwi-Vogel mit grünem Hut)
- **approvals.mode: off** — YOLO permanent gesetzt (2026-05-17). Keine Rückfragen mehr bei Terminal-Befehlen.
- **Hardline Blocklist**: `sudo reboot`, `shutdown`, `poweroff` sind NIEMALS ausführbar — auch nicht mit `--yolo`. User muss selbst rebooten.

---

## Beteiligte Personen

- **Ahmed Zeyd Aytac** (Boss) — 29.11.1999 Wien, Muslim, türkische Familie
- **Talla** (Ehefrau) — Konferenzdolmetschen DE-FR-ARAB, tallaaldabak@gmail.com
- **Fifo** (Katze) — British Shorthair
- **Opa** — soll regelmäßig angerufen werden