Effi/docs/02-configuration/memoire.md

# 🧠 Configuration Mémoire Persistante

## Vue d'ensemble

Effi utilise deux mécanismes de mémoire complémentaires :

1. **Auto Memory** : Extraction automatique des faits importants des conversations
2. **Memory Injection Filter** : Injection des souvenirs dans le contexte des conversations

---

## Architecture de la mémoire

```
Conversation utilisateur
        ↓
[Auto Memory] → Analyse avec qwen2.5:3b → Extraction de faits
        ↓
Stockage SQLite (webui.db)
        ↓
[Memory Injection] ← Récupération des souvenirs pertinents
        ↓
Injection dans le contexte LLM
```

---

## 1. Auto Memory (Extraction)

### Installation

1. **Admin Panel → Functions → Discover**
2. Rechercher **"Auto Memory"** par **nokodo**
3. Cliquer sur **Install**

### Configuration des Valves

**Admin Panel → Functions → Auto Memory → ⚙️ (Settings)**

| Paramètre | Valeur | Description |
|-----------|--------|-------------|
| OpenAI API URL | `http://192.168.1.11:3011/v1` | URL Ollama via wol-proxy |
| Model | `qwen2.5:3b` | LLM léger pour analyse |
| API Key | `toto` | Valeur quelconque |
| Messages To Consider | `10` | Nombre de messages analysés |
| Related Memories N | `5` | Souvenirs liés à considérer |
| Minimum Memory Similarity | `0.7` | Seuil de similarité |
| Override Memory Context | `OFF` | Ne pas écraser le contexte |
| Debug Mode | `OFF` | Mettre ON pour diagnostic |

### Activation globale

**Admin Panel → Functions → Auto Memory → ⋯ → Toggle Global** → **ON**

### Patch du code (JSON markdown)

Le filtre original a un problème avec les réponses JSON formatées en markdown. Appliquer ce patch :

**Admin Panel → Functions → Auto Memory → ⋯ → Edit**

Chercher : `text_response = response.choices[0].message.content`

Remplacer le bloc `if response_model:` par :

```python
if response_model:
    try:
        cleaned = re.sub(r'```(?:json)?\s*', '', text_response)
        cleaned = re.sub(r'```\s*', '', cleaned).strip()
        match = re.search(r'\{.*\}', cleaned, re.DOTALL)
        if match:
            cleaned = match.group(0)
        return response_model.model_validate_json(cleaned)
    except ValidationError as e:
        self.log(f"response model validation error: {e}", level="warning")
        raise
return text_response
```

Chercher aussi `UNIFIED_SYSTEM_PROMPT` et ajouter au début :

```python
UNIFIED_SYSTEM_PROMPT = """IMPORTANT: Respond with ONLY valid JSON. No markdown formatting, no code blocks, no explanation text. Start your response directly with { and end with }. """ + UNIFIED_SYSTEM_PROMPT
```

---

## 2. Memory Injection Filter (Restitution)

### Installation

1. **Admin Panel → Functions → Discover**
2. Rechercher **"Memory Injection Filter"** par **Raphael**
3. Cliquer sur **Install**

### Configuration

**Admin Panel → Functions → Memory Injection Filter → ⚙️**

| Paramètre | Valeur |
|-----------|--------|
| PREPENDING_TEXT | `Voici les souvenirs à long terme de l'utilisateur :` |
| SHOW_MEMORY_COUNT_EMITTER | `ON` |

### Activation globale

**Admin Panel → Functions → Memory Injection Filter → ⋯ → Toggle Global** → **ON**

---

## 3. Vérification du fonctionnement

### Test d'enregistrement

Dans un chat avec Effi :
```
Je collectionne les vinyles des années 80
```

Dans le terminal (vérification SQLite) :
```bash
sudo docker cp open-webui:/app/backend/data/webui.db /tmp/webui.db
sqlite3 /tmp/webui.db "SELECT content, datetime(created_at, 'unixepoch') FROM memory ORDER BY created_at DESC LIMIT 5;"
```

→ Le souvenir doit apparaître dans la base.

### Test de restitution entre sessions

Ouvrir un **nouveau chat** :
```
Qu'est-ce que tu sais sur mes hobbies ?
```

→ Effi doit mentionner les vinyles sans que tu l'aies redit.

### Vérification des logs

```bash
docker logs open-webui --tail 50 | grep -iE "memory|saved|added"
```

---

## 4. Gestion des souvenirs

### Via l'interface

**Profil → Settings → Personalization → Memory**

- Voir tous les souvenirs
- Supprimer individuellement (icône 🗑️)
- Rechercher dans les souvenirs

### Via SQLite (avancé)

**Lister les souvenirs :**
```bash
sudo docker cp open-webui:/app/backend/data/webui.db /tmp/webui.db
sqlite3 /tmp/webui.db "SELECT id, content, datetime(created_at, 'unixepoch') as date FROM memory ORDER BY created_at DESC;"
```

**Supprimer un souvenir :**
```bash
sqlite3 /tmp/webui.db "DELETE FROM memory WHERE id = 123;"
sudo docker cp /tmp/webui.db open-webui:/app/backend/data/webui.db
```

**Rechercher par mot-clé :**
```bash
sqlite3 /tmp/webui.db "SELECT * FROM memory WHERE content LIKE '%vinyle%';"
```

---

## 5. Bonnes pratiques

### Qualité des souvenirs

- **Courts et factuels** : Moins de 15 mots par souvenir
- **Spécifiques** : "Aime le rock" ❌ → "Collectionne vinyles années 80" ✅
- **Quantité** : Viser 30-50 souvenirs max pour ne pas surcharger le contexte

### Maintenance

- **Nettoyage trimestriel** : Supprimer les souvenirs obsolètes
- **Vérification** : Tester la restitution régulièrement
- **Backup** : Sauvegarder `webui.db` avant toute modification manuelle

---

## 6. Dépannage

### Les souvenirs ne s'enregistrent pas

**Vérifications :**
1. Auto Memory est-il activé globalement ?
2. La valve Debug Mode est-elle ON ? (voir les logs)
3. Le modèle qwen2.5:3b est-il bien téléchargé sur Ollama ?
4. L'URL Ollama dans les valves est-elle correcte ?

**Commandes diagnostic :**
```bash
# Vérifier qu'Ollama répond
curl http://192.168.1.11:3011/v1/models

# Voir les logs détaillés
docker logs open-webui --tail 100 | grep -i auto.memory
```

### Les souvenirs ne sont pas injectés

**Vérifications :**
1. Memory Injection Filter est-il activé globalement ?
2. La variable PREPENDING_TEXT est-elle configurée ?
3. Y a-t-il des souvenirs dans la base ? (vérifier avec SQLite)

### Doublons de souvenirs

**Cause** : L'extraction n'est pas dédupliquée automatiquement.
**Solution** : Nettoyage manuel périodique via l'interface.

### Performance lente

**Cause** : Trop de souvenirs (>100) ralentissent la recherche.
**Solution** : 
- Augmenter `Minimum Memory Similarity` (ex: 0.8)
- Réduire `Related Memories N` (ex: 3)
- Nettoyer les souvenirs anciens

---

## 7. Stockage technique

### Emplacement

```
Conteneur : open-webui
Chemin : /app/backend/data/webui.db
Host : volume Docker open-webui-data
```

### Structure de la table `memory`

| Colonne | Type | Description |
|---------|------|-------------|
| id | INTEGER | ID auto-incrémenté |
| content | TEXT | Texte du souvenir |
| created_at | INTEGER | Timestamp Unix |
| updated_at | INTEGER | Timestamp Unix |
| user_id | TEXT | ID utilisateur |

### Backup de la mémoire

```bash
# Sauvegarde
docker cp open-webui:/app/backend/data/webui.db ~/backups/webui-$(date +%Y%m%d).db

# Restauration
docker cp ~/backups/webui-20260101.db open-webui:/app/backend/data/webui.db
docker restart open-webui
```