Initial commit: Documentation Effi v1.0

- Structure complète du projet - Docker compose de production - Documentation organisée par thèmes - Guides d'installation et configuration - Section dépannage détaillée - Journal historique
2026-04-04 08:45:59 +02:00
commit d1e12cff60
35 changed files with 4656 additions and 0 deletions
@@ -0,0 +1,262 @@
+# 🧠 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
+```