Add CPU embeddings for OpenClaw memory

docs/OPENCLAW_MEMORY.md

@@ -0,0 +1,90 @@
+# OpenClaw Memory über Athena
+
+Stand: **21. September 2026**
+
+OpenClaw verwendet für seine Memory-Suche einen eigenen, dauerhaft laufenden
+Embedding-Dienst auf Athena. Der Chat-Router auf Port 8081 bleibt unverändert;
+Embeddings laufen getrennt auf Port 8082.
+
+## Aufbau
+
+- Container: `mike-ai-embedding`
+- Modell: `ggml-org/embeddinggemma-300m-qat-q8_0-GGUF`, Q8_0
+- Datei: `/data/models/embeddinggemma/embeddinggemma-300m-qat-Q8_0.gguf`
+- SHA-256: `6fa0c02a9c302be6f977521d399b4de3a46310a4f2621ee0063747881b673f67`
+- Laufzeit: eigener, auf Athenas CPU nativ optimierter CPU-only-Build von
+  llama.cpp ohne CUDA-Abhängigkeit, zusätzlich erzwungen durch
+  `--n-gpu-layers 0`
+- API: `http://192.168.1.212:8082/v1/embeddings`
+- Zugriff: privater WireGuard-Netzwerk-Namespace; kein öffentlicher Host-Port
+- Ergebnisdimension: 768
+- vier CPU-Slots mit insgesamt 4096 Kontexttoken
+- logische Batchgröße 4096 und physische Micro-Batchgröße 1024; damit passen
+  auch größere OpenClaw-Memory-Chunks in einen Slot und mehrere Chunks werden
+  beim Indexaufbau gemeinsam verarbeitet
+
+Der Dienst benötigt im Leerlauf rund 86 MiB und während eines vollständigen
+Indexaufbaus rund 1,1 GiB RAM. Die abschließende Netzwerkprobe von Unraid aus
+lag bei 0,044 Sekunden. Ein Betrieb auf der RTX 3060
+wurde verworfen: Im Ultra-Profil blieben nur 372 MB VRAM Reserve, während der
+Zeitgewinn lediglich rund 0,06 Sekunden betrug.
+
+## OpenClaw-Konfiguration
+
+OpenClaw nutzt den offiziellen generischen Anbieter `openai-compatible`. Die
+bestehenden Quellen-, Scope- und Chunking-Einstellungen unter `memory.search`
+bleiben dabei erhalten.
+
+```json5
+{
+  memory: {
+    search: {
+      provider: "openai-compatible",
+      model: "embeddinggemma",
+      fallback: "none",
+      remote: {
+        baseUrl: "http://192.168.1.212:8082/v1",
+        apiKey: "local"
+      }
+    }
+  }
+}
+```
+
+`local` ist hier nur ein nicht geheimes Kompatibilitätskennwort. Der Dienst
+liegt im privaten VPN und llama.cpp verlangt selbst keinen Schlüssel.
+
+## Prüfung
+
+Auf Athena:
+
+```bash
+docker inspect -f '{{.State.Health.Status}}' mike-ai-embedding
+docker exec mike-ai-embedding curl -fsS \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"embeddinggemma","input":["Athena Speicherprobe"]}' \
+  http://127.0.0.1:8082/v1/embeddings
+```
+
+Auf Unraid:
+
+```bash
+docker exec OpenClaw openclaw memory status --deep --agent main
+docker exec OpenClaw openclaw memory index --force --agent main
+docker exec OpenClaw openclaw memory search --agent main "GPU-Aufteilung"
+```
+
+Nach einem Wechsel von Anbieter oder Modell muss der Index ausdrücklich neu
+aufgebaut werden. OpenClaw erledigt das absichtlich nicht still im Hintergrund.
+Der produktive Neuaufbau am 21. September umfasste 107 Dateien und 1.139
+Chunks. Danach meldete OpenClaw `dirty: false`, einen vollständigen
+768-dimensionalen Vektorindex, aktive semantische Suche und eine erfolgreiche
+Anbieterprobe. Eine Suchprobe lieferte drei Treffer.
+
+## Wiederherstellung
+
+Der Athena-Installer lädt das Modell anhand der fest hinterlegten URL und
+Prüfsumme. Danach startet `./manage.sh deploy core` den Embedding-Dienst mit.
+Auf Unraid werden die vier oben dokumentierten `memory.search`-Werte gesetzt
+und anschließend der Index erzwungen neu aufgebaut. Weder API-Schlüssel noch
+Memory-Inhalte liegen in diesem Git-Repository.