# VoiceMem einrichten — Anleitung für deinen Coding-Agenten

> **So benutzt du diese Datei:** Leg sie in dein Projektverzeichnis und sag
> deinem Agenten: *„Halte dich an voicemem-einrichten.md."* Das funktioniert mit Claude
> Code, Codex, Cursor, Cline und allem anderen, was Dateien lesen kann.
> Wenn dein Agent von selbst eine bestimmte Datei liest, kannst du sie auch
> in `AGENTS.md` umbenennen oder den Inhalt in deine `CLAUDE.md` kopieren.

**Projekt:** [github.com/xzf-thu/VoiceMem](https://github.com/xzf-thu/VoiceMem) · **Stand:** 2026-09-05 · Zusammengestellt von
[localdev.ai](https://localdev.ai/)

---

## Ziel

VoiceMem als lokale Offline-Memory-Engine installieren und mit dem interaktiven Web-Demo oder einem minimalen Python-Skript lauffähig machen.

## Voraussetzungen

- Python 3.10+
- Git
- pip
- OPENAI_API_KEY (für Chat/TTS/Realtime-Funktionen; Memory-Retrieval läuft lokal)
- huggingface_hub installiert (für Modelldownload)
- ca. 10 GB freier Speicher für lokale Modelle (VoiceMem_Default_Models_Env)
- Optional: CUDA-fähige GPU für schnellere Inferenz; CPU-Modus ist langsamer

## Das fragst du mich, bevor du anfängst

- Hast du einen OPENAI_API_KEY? Ohne diesen funktionieren Chat, TTS und Realtime-Features nicht (Memory-Retrieval läuft aber lokal).
- Hast du ein HuggingFace-Token mit Accept auf den VoiceMem-Modellen? Die Modelle müssen vorab heruntergeladen werden.
- Willst du nur die Python-Library nutzen oder auch das Web-Demo (erfordert `git clone`, nicht nur `pip install`)?
- Hast du mindestens 10 GB freien Speicher für die lokalen Modelle?
- Läuft dein System auf CPU oder CUDA-GPU?

## Einrichtung

### 1. Repository klonen

```bash
git clone https://github.com/xzf-thu/VoiceMem.git
cd VoiceMem
```

**Prüfen:** Verzeichnis VoiceMem/ existiert und enthält web/run.py sowie examples/

> ⚠️ Nur `pip install voicemem` reicht nicht für das Web-Demo; das Demo liegt nur im Repo, nicht im PyPI-Paket.

### 2. Python-Abhängigkeiten installieren

```bash
pip install voicemem
pip install "voicemem[slm]"
pip install -U huggingface_hub
```

**Prüfen:** `python -c "import voicemem; print(voicemem.__version__)"` läuft ohne ImportError

> ⚠️ Die `[slm]`-Extras sind für das Small Language Model; ohne fehlen möglicherweise Komponenten.

### 3. Lokale Modelle herunterladen

```bash
hf download zhifeixie/VoiceMem_Default_Models_Env --local-dir ./models
```

**Prüfen:** Verzeichnis ./models existiert und enthält heruntergeladene Modelldateien

> ⚠️ Dieser Schritt lädt mehrere GB herunter und erfordert HuggingFace-Zugang. Ohne die Modelle crasht die Initialisierung von VoiceMem.

### 4. OPENAI_API_KEY setzen

```bash
export OPENAI_API_KEY=sk-...
```

**Prüfen:** `echo $OPENAI_API_KEY` zeigt den Schlüssel an

> ⚠️ Kostenpflichtig: Jeder API-Aufruf bei OpenAI verursacht Kosten. Memory-Retrieval selbst ist lokal und kostenlos.

### 5. Web-Demo starten

```bash
python web/run.py
```

**Prüfen:** Terminal zeigt Uvicorn-Start an; die README nennt http://localhost:8787 als Zugriffsadresse

> ⚠️ Port 8787 muss frei sein. Ohne `git clone` existiert web/run.py nicht.


## Erster Test

Minimaler Offline-Test ohne Audio-Datei, nur text-basiertes Left-Brain-Memory.

```python
from voicemem import VoiceMem

vm = VoiceMem(
    mode="leftbrain_only",
    openai_key="api_xxx",
    top_k=5,
)

vm.ingest("I am vegetarian and allergic to nuts.")
result = vm.search("What are my dietary restrictions?")
print(result)
```

## Wenn es klemmt

| Symptom | Ursache | Lösung |
|---|---|---|
| ImportError: No module named 'voicemem' | Paket nicht installiert oder falsche Python-Umgebung | Prüfe `which python` und `pip --version`, dann erneut `pip install voicemem` in der korrekten Umgebung ausführen |
| FileNotFoundError: web/run.py | Nur `pip install` gemacht, aber Repo nicht geklont | `git clone https://github.com/xzf-thu/VoiceMem.git` ausführen und in das Verzeichnis wechseln |
| HuggingFace-Error oder Modelle nicht gefunden bei VoiceMem-Initialisierung | Lokale Modelle nicht heruntergeladen oder falscher Pfad | `hf download zhifeixie/VoiceMem_Default_Models_Env --local-dir ./models` ausführen und sicherstellen, dass ./models existiert |
| OpenAI-API-Fehler oder AuthenticationError | OPENAI_API_KEY fehlt, ist ungültig oder nicht exportiert | Schlüssel prüfen mit `echo $OPENAI_API_KEY`, ggf. neu exportieren |
| Langsame Performance oder OOM (Out of Memory) | Modelle laufen auf CPU oder GPU hat zu wenig VRAM | Für CPU: längere Wartezeiten akzeptieren oder kleinere Modelle prüfen. Für GPU: CUDA-Verfügbarkeit prüfen mit `python -c 'import torch; print(torch.cuda.is_available())'` |

## Grenzen — das kann das Projekt nicht

- Memory-Retrieval ist lokal, aber Chat/TTS/Realtime erfordern OpenAI-API mit Kosten
- Das Web-Demo ist nicht im PyPI-Paket enthalten, nur im Git-Repo
- Die vollständige Streaming-Architektur mit Audio erfordert zusätzliche Audio-Dateien und ist nicht rein text-basiert nutzbar
- Finetuning erfordert ms-swift==4.5.2, bitsandbytes und eigene Trainingsdaten
- Die Evaluation benötigt spezifische Benchmark-Datensätze (LoCoMo, PersonaMem), die nicht automatisch mitgeliefert werden
- v0.0.2 ist eine sehr junge Version (erste Release August 2026), API kann sich noch ändern

## Regeln für dich als Agent

- Nie `--log-file` oder `--no-file-log` erfinden; nur die in der README dokumentierten Flags verwenden
- OPENAI_API_KEY niemals hardcoden, immer über Umgebungsvariable oder sicheren Secret-Manager
- Vor jedem `hf download` oder API-Aufruf den Nutzer explizit fragen, ob er die Kosten/Datenübertragung akzeptiert
- Bei Fehlern immer zuerst prüfen, ob ./models existiert und web/run.py vorhanden ist
- Keine Versionen raten: `ms-swift==4.5.2` exakt verwenden, nicht `ms-swift` ohne Pin
- Falls der Nutzer kein HuggingFace-Token hat, ihn darauf hinweisen und nicht automatisch einen Account anlegen

---

### Wichtig

Diese Datei wurde aus der Liesmich-Datei des Projekts vom 2026-09-05
zusammengestellt und ist keine offizielle Dokumentation. Sie ersetzt nicht den
Blick in das Repository — wenn ein Befehl hier nicht funktioniert, gilt
[die Quelle](https://github.com/xzf-thu/VoiceMem), nicht diese Datei.

*Erklärvideos und Merkblätter zu Werkzeugen wie diesem:
[localdev.ai](https://localdev.ai/m/) — ohne Anmeldung.*
