linear-coding-agent/prompts/app_spec_ikario_rag_UI.txt

<project_specification>
  <project_name>Interface Utilisateur Ikario RAG Memory - My Project</project_name>

  <overview>
    Integration et interface utilisateur pour exploiter les outils MCP du serveur Ikario RAG existant.

    LE SERVEUR IKARIO RAG EXISTE DEJA:
    - Serveur MCP Python operationnel (C:/Users/david/SynologyDrive/ikario/ikario_rag/)
    - 8 outils MCP disponibles: add_thought, add_conversation, append_to_conversation, search_thoughts,
      search_conversations, trace_concept_evolution, check_consistency, search_memories
    - Base ChromaDB avec embeddings semantiques
    - Collections: thoughts (pensees), conversations (echanges)
    - Support optionnel du champ 'thinking' pour capturer le raisonnement LLM dans les conversations

    ON NE TOUCHE PAS au code Python ikario_rag.
    ON DEVELOPPE UNIQUEMENT dans generations/my_project/

    Cette specification ajoute:
    - Interface utilisateur React pour exploiter les outils MCP existants
    - Routes API backend (Express) pour exposer les outils MCP au frontend
    - Composants de visualisation de la memoire
    - Panel de gestion de memoire dans la sidebar
    - Integration avec le chat existant

    Objectif: Rendre les outils MCP ikario_rag accessibles et utilisables via l'interface my_project.
  </overview>

  <technology_stack>
    <existing_stack>
      Frontend:
      - React + Vite
      - Tailwind CSS
      - React Router
      - Contextes React existants

      Backend:
      - Node.js + Express
      - SQLite (better-sqlite3)
      - Client MCP deja configure (server/services/mcpClient.js)
      - Routes API existantes (server/routes/)

      Ikario RAG (externe, NE PAS MODIFIER):
      - Serveur MCP Python
      - 8 outils MCP disponibles (avec append_to_conversation + support thinking)
      - ChromaDB pour stockage
    </existing_stack>

    <new_components>
      Frontend (src/):
      - components/memory/MemoryPanel.jsx - Panel memoire dans sidebar
      - components/memory/ThoughtsList.jsx - Liste des pensees
      - components/memory/ConceptsGraph.jsx - Graphe des concepts
      - components/memory/MemorySearch.jsx - Recherche dans la memoire
      - components/memory/ThoughtForm.jsx - Formulaire ajout pensee
      - hooks/useMemory.js - Hook pour interagir avec API memoire

      Backend (server/):
      - routes/memory.js - Routes API pour la memoire
      - services/memoryService.js - Service pour appeler outils MCP
      - utils/memoryFormatter.js - Formatage donnees MCP pour frontend
    </new_components>
  </technology_stack>

  <prerequisites>
    <existing_system>
      - My Project fonctionnel (frontend + backend)
      - Client MCP configure (mcpClient.js)
      - Serveur Ikario RAG accessible via MCP
      - Variable env: MCP_IKARIO_SERVER_PATH definie
    </existing_system>

    <new_dependencies>
      Frontend:
      - recharts (graphiques): npm install recharts
      - react-force-graph-2d (graphe concepts): npm install react-force-graph-2d
      - date-fns (dates): npm install date-fns

      Backend:
      - Aucune nouvelle dependance (MCP SDK deja installe)
    </new_dependencies>

    <environment_variables>
      .env fichier:
      MCP_IKARIO_SERVER_PATH=C:/Users/david/SynologyDrive/ikario/ikario_rag/server.py
      MCP_MEMORY_ENABLED=true
      MCP_PYTHON_COMMAND=python
    </environment_variables>
  </prerequisites>

  <core_features>
    <!--
      FEATURES FRONTEND + BACKEND
      Developper UNIQUEMENT dans generations/my_project/
    -->

    <feature_1>
      <title>Backend - Routes API Memory</title>
      <description>
        Routes Express pour exposer les outils MCP ikario_rag au frontend.

        Fichier: server/routes/memory.js

        Routes a creer:
        - POST /api/memory/thoughts - Ajouter une pensee (appelle add_thought MCP)
        - GET /api/memory/thoughts - Rechercher pensees (appelle search_thoughts MCP)
        - POST /api/memory/conversations - Ajouter conversation complete (appelle add_conversation MCP)
        - POST /api/memory/conversations/append - Ajouter messages a conversation (appelle append_to_conversation MCP)
        - GET /api/memory/conversations - Rechercher conversations (appelle search_conversations MCP)
        - GET /api/memory/search - Recherche globale (appelle search_memories MCP)
        - GET /api/memory/concepts/:concept - Tracer concept (appelle trace_concept_evolution MCP)
        - GET /api/memory/consistency - Check coherence (appelle check_consistency MCP)

        IMPORTANT - append_to_conversation:
        Utiliser cet outil pour les conversations en cours (chat streaming).
        Supporte le champ 'thinking' optionnel pour capturer le raisonnement du LLM.
        Auto-create: cree la conversation si elle n'existe pas.

        Format message avec thinking:
        {
          "author": "assistant",
          "content": "Voici comment faire...",
          "thinking": "L'utilisateur demande...",  // OPTIONNEL
          "timestamp": "ISO date"
        }

        Technique:
        - Import mcpClient depuis services/mcpClient.js
        - Appeler mcpClient.callTool(toolName, arguments)
        - Formater reponse pour frontend (JSON clean)
        - Gestion erreurs + logging
        - Validation parametres entrants

        Integration:
        - Ajouter dans server/index.js: app.use('/api/memory', memoryRoutes)
      </description>
      <priority>1</priority>
      <category>backend</category>
      <files_to_create>
        - server/routes/memory.js
      </files_to_create>
      <test_steps>
        1. POST /api/memory/thoughts avec {"content": "test", "thought_type": "reflection"}
        2. GET /api/memory/thoughts?query=test
        3. Verifier reponse JSON valide
        4. Tester gestion erreurs (outil MCP indisponible)
      </test_steps>
    </feature_1>

    <feature_2>
      <title>Backend - Memory Service Layer</title>
      <description>
        Service intermediaire pour formater/transformer donnees MCP.

        Fichier: server/services/memoryService.js

        Fonctions:
        - addThought(content, thoughtType, context) → Promise
        - searchThoughts(query, filters) → Promise
        - addConversation(conversationId, messages) → Promise (conversation complete)
        - appendToConversation(conversationId, newMessages, options) → Promise (incremental, avec thinking)
        - searchConversations(query) → Promise
        - globalSearch(query) → Promise
        - traceConceptEvolution(concept) → Promise
        - checkConsistency() → Promise
        - getMemoryStats() → Promise (stats locales)

        IMPORTANT appendToConversation:
        Fonction principale pour les conversations en cours (chat). Supporte:
        - Auto-creation: cree la conversation si elle n'existe pas
        - Thinking optionnel: capture le raisonnement LLM
        - Incremental: ajoute seulement les nouveaux messages

        Exemple:
        await appendToConversation('conv_123', [
          { author: 'user', content: 'Bonjour', timestamp: '...' },
          {
            author: 'assistant',
            content: 'Salut!',
            thinking: 'L\'utilisateur me salue chaleureusement',  // OPTIONNEL
            timestamp: '...'
          }
        ], {
          participants: ['user', 'assistant'],  // Requis si nouvelle conversation
          context: { category: 'chat', date: '2025-12-20' }
        })

        Technique:
        - Wrapper autour de mcpClient.callTool()
        - Formatage reponses (timestamps, scores, etc.)
        - Cache optionnel pour stats
        - Retry logic si echec MCP
        - Logging detaille

        Integration:
        - Importe par routes/memory.js
        - Gestion centralisee des appels MCP
      </description>
      <priority>1</priority>
      <category>backend</category>
      <files_to_create>
        - server/services/memoryService.js
      </files_to_create>
      <test_steps>
        1. Tester chaque fonction avec donnees reelles
        2. Verifier formatage reponses
        3. Tester retry logic (simuler echec MCP)
        4. Verifier logs clairs
      </test_steps>
    </feature_2>

    <feature_3>
      <title>Frontend - Memory Panel Component</title>
      <description>
        Panel memoire dans la sidebar gauche pour visualiser et gerer la memoire.

        Fichier: src/components/memory/MemoryPanel.jsx

        UI:
        - Titre "Memoire Ikario"
        - Onglets: "Pensees" | "Conversations" | "Concepts"
        - Zone recherche rapide (input + bouton)
        - Liste scrollable des resultats
        - Bouton "Ajouter Pensee" (ouvre modal)
        - Stats en bas: X pensees, Y conversations

        Fonctionnalites:
        - Afficher dernieres pensees/conversations
        - Recherche temps reel (debounce 500ms)
        - Click sur item → affiche details
        - Indicateur chargement
        - Gestion erreurs (MCP indisponible)

        Technique:
        - Hook useMemory() pour appels API
        - State local pour onglet actif
        - Composants enfants: ThoughtCard, ConversationCard
        - Responsive (collapse sur mobile)

        Integration:
        - Ajouter dans src/components/Sidebar.jsx
        - Position: Entre "Conversations" et parametres
        - Icone brain/memory dans menu
      </description>
      <priority>2</priority>
      <category>frontend</category>
      <files_to_create>
        - src/components/memory/MemoryPanel.jsx
        - src/components/memory/ThoughtCard.jsx
        - src/components/memory/ConversationCard.jsx
      </files_to_create>
      <test_steps>
        1. Affichage panel dans sidebar
        2. Switch entre onglets
        3. Recherche pensees/conversations
        4. Click sur item affiche details
        5. Test responsive mobile
      </test_steps>
    </feature_3>

    <feature_4>
      <title>Frontend - Add Thought Modal</title>
      <description>
        Modal pour ajouter une nouvelle pensee rapidement.

        Fichier: src/components/memory/AddThoughtModal.jsx

        UI:
        - Titre "Nouvelle Pensee"
        - Textarea pour contenu (required)
        - Select pour thought_type: reflection, synthesis, question, abduction, dream, doubt, resolution
        - Section optionnelle "Contexte" (collapse):
          * Tags/concepts (input multi-valeurs)
          * Etat emotionnel (slider intensity 0-1)
          * Lien conversation (select conversations recentes)
        - Boutons: Annuler | Sauvegarder

        Fonctionnalites:
        - Validation client-side (contenu non vide)
        - Auto-save draft dans localStorage
        - Bouton rapide "Sauvegarder depuis conversation courante"
        - Notification succes/erreur
        - Raccourci clavier: Cmd/Ctrl+Shift+T

        Technique:
        - React Hook Form pour gestion formulaire
        - POST /api/memory/thoughts pour sauvegarder
        - Optimistic UI update (ajoute dans liste immediatement)
        - Error handling avec toast notifications

        Integration:
        - Ouvre depuis MemoryPanel
        - Ouvre depuis menu chat (bouton "Memoriser cette conversation")
        - Contexte: useMemoryModal() pour gestion globale
      </description>
      <priority>2</priority>
      <category>frontend</category>
      <files_to_create>
        - src/components/memory/AddThoughtModal.jsx
        - src/hooks/useMemoryModal.js
      </files_to_create>
      <test_steps>
        1. Ouvrir modal depuis panel
        2. Remplir formulaire et sauvegarder
        3. Verifier POST /api/memory/thoughts
        4. Verifier pensee apparait dans liste
        5. Test auto-save draft
        6. Test validation erreurs
      </test_steps>
    </feature_4>

    <feature_5>
      <title>Frontend - Concepts Graph Visualization</title>
      <description>
        Visualisation graphique des concepts et leurs relations.

        Fichier: src/components/memory/ConceptsGraph.jsx

        UI:
        - Graph 2D interactif (force-directed)
        - Nodes: Concepts (taille = frequence)
        - Edges: Relations entre concepts (co-occurrence)
        - Legende: Couleurs par categorie
        - Controls: Zoom, Pan, Reset view
        - Sidebar: Details du concept selectionne

        Fonctionnalites:
        - Click node → affiche pensees/conversations liees
        - Hover node → tooltip avec stats
        - Filtre par date range
        - Filtre par type (pensees seules, conversations seules, tout)
        - Export PNG du graphe

        Technique:
        - react-force-graph-2d pour rendu
        - GET /api/memory/concepts/graph pour data
        - Calcul layout cote client
        - Cache graph data (5 min)
        - Animations fluides

        Integration:
        - Onglet "Concepts" dans MemoryPanel
        - OU page separee /memory/graph
        - Responsive (fallback liste sur mobile)
      </description>
      <priority>3</priority>
      <category>frontend</category>
      <files_to_create>
        - src/components/memory/ConceptsGraph.jsx
        - src/components/memory/ConceptDetails.jsx
      </files_to_create>
      <test_steps>
        1. Afficher graphe avec concepts reels
        2. Click sur node affiche details
        3. Tester zoom/pan
        4. Tester filtres date
        5. Export PNG fonctionnel
      </test_steps>
    </feature_5>

    <feature_6>
      <title>Frontend - Memory Search Interface</title>
      <description>
        Interface de recherche avancee dans la memoire semantique.

        Fichier: src/components/memory/MemorySearch.jsx

        UI:
        - Barre recherche proeminente (top)
        - Filtres:
          * Type: Pensees | Conversations | Tout
          * Date range picker
          * Tags/concepts (multi-select)
          * Tri: Pertinence | Date | Frequence
        - Resultats:
          * Liste avec preview
          * Score de pertinence (barre)
          * Highlight des mots cles
          * Pagination
        - Stats: X resultats en Y ms

        Fonctionnalites:
        - Recherche semantique (via search_memories MCP)
        - Debounce 300ms sur typing
        - Historique recherches recentes
        - Sauvegarde filtres dans URL params
        - Raccourci: Cmd/Ctrl+K ouvre recherche

        Technique:
        - GET /api/memory/search?q=query&type=all&limit=20
        - State pour filtres + resultats
        - URL params pour deep linking
        - Infinite scroll (load more)
        - Cache resultats par query

        Integration:
        - Page /memory/search (route React Router)
        - Accessible depuis header (icone loupe)
        - Shortcut global Cmd+K
      </description>
      <priority>2</priority>
      <category>frontend</category>
      <files_to_create>
        - src/components/memory/MemorySearch.jsx
        - src/components/memory/SearchResult.jsx
        - src/components/memory/SearchFilters.jsx
      </files_to_create>
      <test_steps>
        1. Rechercher "conscience"
        2. Verifier resultats pertinents
        3. Appliquer filtres (type, date)
        4. Tester pagination
        5. Verifier URL params saved
        6. Test Cmd+K shortcut
      </test_steps>
    </feature_6>

    <feature_7>
      <title>Frontend - Chat Integration: Save to Memory</title>
      <description>
        Bouton dans le chat pour sauvegarder conversation/message dans la memoire.

        Fichier: src/components/chat/SaveToMemoryButton.jsx

        UI:
        - Bouton "Memoriser" (icone brain) sur chaque message
        - Bouton "Sauvegarder conversation" en haut du chat
        - Dropdown rapide:
          * "Comme pensee" (ouvre modal AddThought avec contenu pre-rempli)
          * "Comme conversation complete"
          * "Concepts cles seulement"
        - Badge "Memorise" sur messages deja sauvegardes

        Fonctionnalites:
        - Pre-remplit modal avec contenu message/conversation
        - Auto-detection concepts depuis messages
        - Link bi-directionnel: conversation ↔ memoire
        - Notification succes
        - Desactivation si MCP indisponible

        Technique:
        - Composant dans MessageActions
        - POST /api/memory/conversations/append pour sauvegarder conversation en cours
        - IMPORTANT: Utiliser append_to_conversation (pas add_conversation) pour chat streaming
        - Support du champ 'thinking' si Extended Thinking actif
        - State partagé pour tracking memoire
        - Optimistic UI updates

        Exemple POST /api/memory/conversations/append:
        {
          "conversation_id": "conv_20251220_0010",
          "new_messages": [
            { "author": "user", "content": "Bonjour", "timestamp": "..." },
            {
              "author": "assistant",
              "content": "Salut!",
              "thinking": "L'utilisateur me salue...",  // OPTIONNEL si Extended Thinking
              "timestamp": "..."
            }
          ],
          "participants": ["user", "assistant"],
          "context": { "category": "chat", "date": "2025-12-20" }
        }

        Integration:
        - Ajouter dans src/components/chat/Message.jsx
        - Ajouter dans src/components/chat/ChatHeader.jsx
        - Context useMemory() pour state global
      </description>
      <priority>2</priority>
      <category>frontend</category>
      <files_to_modify>
        - src/components/chat/Message.jsx (add button)
        - src/components/chat/ChatHeader.jsx (add button)
      </files_to_modify>
      <files_to_create>
        - src/components/chat/SaveToMemoryButton.jsx
      </files_to_create>
      <test_steps>
        1. Click "Memoriser" sur message
        2. Verifier modal pre-remplie
        3. Sauvegarder et verifier badge
        4. Click "Sauvegarder conversation"
        5. Verifier POST /api/memory/conversations
        6. Verifier bi-directional link
      </test_steps>
    </feature_7>

    <feature_8>
      <title>Frontend - Memory Context in Chat</title>
      <description>
        Affichage du contexte memoire pertinent pendant une conversation.

        Fichier: src/components/memory/MemoryContextPanel.jsx

        UI:
        - Panel lateral droit (collapsible)
        - Titre "Contexte Memoire"
        - Sections:
          * "Pensees liees" (top 3)
          * "Conversations similaires" (top 3)
          * "Concepts detectes" (tags)
        - Chaque item cliquable → ouvre details
        - Auto-refresh quand nouvelle question

        Fonctionnalites:
        - Recherche semantique basee sur message user
        - Affichage temps reel (streaming)
        - Click item → insert reference dans chat
        - Toggle on/off (preference user)
        - Indicateur "Recherche en cours..."

        Technique:
        - GET /api/memory/search?q=last_user_message&limit=3
        - Declenchement sur onMessageSent
        - Debounce pour eviter spam
        - Cache par message
        - Skeleton loading

        Integration:
        - Panel dans src/components/chat/ChatContainer.jsx
        - Toggle dans settings
        - Preference sauvee dans localStorage
      </description>
      <priority>3</priority>
      <category>frontend</category>
      <files_to_create>
        - src/components/memory/MemoryContextPanel.jsx
        - src/hooks/useMemoryContext.js
      </files_to_create>
      <test_steps>
        1. Envoyer message dans chat
        2. Verifier panel se met a jour
        3. Verifier pensees/conversations pertinentes
        4. Click sur item → details
        5. Toggle on/off fonctionnel
      </test_steps>
    </feature_8>

    <feature_9>
      <title>Backend - Memory Stats Endpoint</title>
      <description>
        Endpoint pour statistiques globales de la memoire.

        Fichier: Ajouter dans server/routes/memory.js

        Route: GET /api/memory/stats

        Reponse JSON:
        {
          "total_thoughts": 142,
          "total_conversations": 38,
          "total_concepts": 256,
          "most_frequent_concepts": ["AI", "consciousness", "ethics"],
          "recent_activity": [
            {"date": "2025-12-19", "thoughts": 5, "conversations": 2}
          ],
          "mcp_status": "connected" | "disconnected",
          "last_sync": "2025-12-19T10:30:00Z"
        }

        Fonctionnalites:
        - Aggregation cote backend
        - Cache 5 minutes
        - Fallback si MCP indisponible
        - Stats incrementales (pas full scan)

        Technique:
        - Appeler check_consistency MCP pour health check
        - Compter via requetes search avec limit=0
        - Sauvegarder stats dans SQLite (table memory_stats)
        - Cron job pour update stats (toutes les 5 min)

        Integration:
        - Utilise par MemoryPanel pour afficher stats
        - Utilise par dashboard (si futur)
      </description>
      <priority>3</priority>
      <category>backend</category>
      <files_to_modify>
        - server/routes/memory.js
      </files_to_modify>
      <test_steps>
        1. GET /api/memory/stats
        2. Verifier JSON structure
        3. Verifier cache fonctionne
        4. Tester fallback si MCP down
      </test_steps>
    </feature_9>

    <feature_10>
      <title>Frontend - Memory Settings Panel</title>
      <description>
        Panel parametres pour configuration de la memoire.

        Fichier: src/components/settings/MemorySettings.jsx

        UI dans Settings modal, section "Memoire":
        - Toggle "Activer la memoire" (on/off)
        - Toggle "Contexte automatique" (afficher MemoryContextPanel)
        - Toggle "Sauvegarder conversations automatiquement"
        - Slider "Nombre de resultats" (3-10)
        - Bouton "Effacer cache memoire"
        - Indicateur "Status MCP: Connecte/Deconnecte"
        - Bouton "Tester connexion"

        Fonctionnalites:
        - Preferences sauvees dans localStorage
        - Test connexion MCP on demand
        - Affichage stats memoire (total pensees, etc.)
        - Link vers page /memory/search

        Technique:
        - Context useMemorySettings() pour state global
        - GET /api/memory/stats pour status
        - localStorage pour preferences
        - Sync preferences avec backend (optionnel)

        Integration:
        - Nouvelle section dans src/components/settings/Settings.jsx
        - Icone brain dans menu settings
      </description>
      <priority>3</priority>
      <category>frontend</category>
      <files_to_create>
        - src/components/settings/MemorySettings.jsx
      </files_to_create>
      <files_to_modify>
        - src/components/settings/Settings.jsx
      </files_to_modify>
      <test_steps>
        1. Ouvrir settings → section Memoire
        2. Toggle preferences
        3. Verifier sauvegarde localStorage
        4. Test connexion MCP
        5. Verifier status affiche correctement
      </test_steps>
    </feature_10>

    <feature_11>
      <title>Backend - Error Handling & Logging</title>
      <description>
        Gestion robuste des erreurs MCP et logging detaille.

        Fichier: server/services/errorHandler.js

        Fonctionnalites:
        - Wrapper pour appels MCP avec try/catch
        - Classification erreurs:
          * MCP_CONNECTION_ERROR (serveur down)
          * MCP_TOOL_ERROR (outil echoue)
          * MCP_TIMEOUT_ERROR (timeout)
          * VALIDATION_ERROR (params invalides)
        - Logging structure (JSON):
          {"level": "error", "type": "MCP_CONNECTION_ERROR", "message": "...", "timestamp": "..."}
        - Retry automatique pour erreurs transitoires
        - Fallback graceful (retourner donnees cached si possible)

        Technique:
        - Custom Error classes pour chaque type
        - Winston logger pour logs structures
        - Sentry integration (optionnel) pour monitoring
        - Health check endpoint: GET /api/memory/health

        Integration:
        - Utilise par tous les services memoire
        - Logs dans server/logs/memory.log
        - Dashboard health check
      </description>
      <priority>2</priority>
      <category>backend</category>
      <files_to_create>
        - server/services/errorHandler.js
        - server/middleware/mcpErrorMiddleware.js
      </files_to_create>
      <test_steps>
        1. Simuler MCP down → verifier erreur graceful
        2. Simuler timeout → verifier retry
        3. Verifier logs structures
        4. Test health check endpoint
      </test_steps>
    </feature_11>

    <feature_12>
      <title>Frontend - useMemory Hook</title>
      <description>
        Hook React centralise pour toutes interactions memoire.

        Fichier: src/hooks/useMemory.js

        API:
        const {
          thoughts,
          conversations,
          concepts,
          isLoading,
          error,
          addThought,
          searchThoughts,
          addConversation,
          searchConversations,
          globalSearch,
          traceConceptEvolution,
          checkConsistency,
          stats
        } = useMemory();

        Fonctionnalites:
        - State management pour donnees memoire
        - Cache avec SWR (stale-while-revalidate)
        - Optimistic updates
        - Error handling integre
        - Retry logic automatique
        - Invalidation cache sur mutations

        Technique:
        - React Query ou SWR pour data fetching
        - Custom hooks pour chaque operation
        - Context Provider pour state global
        - Type safety avec JSDoc ou TypeScript

        Integration:
        - Utilise par tous les composants memoire
        - Provider dans App.jsx
      </description>
      <priority>1</priority>
      <category>frontend</category>
      <files_to_create>
        - src/hooks/useMemory.js
        - src/contexts/MemoryContext.jsx
        - src/providers/MemoryProvider.jsx
      </files_to_create>
      <test_steps>
        1. Utiliser hook dans composant test
        2. Verifier addThought met a jour cache
        3. Verifier searchThoughts retourne resultats
        4. Tester error handling
        5. Verifier optimistic updates
      </test_steps>
    </feature_12>

    <feature_13>
      <title>Documentation - Memory API Guide</title>
      <description>
        Documentation complete de l'API memoire et guide d'utilisation.

        Fichier: generations/my_project/docs/MEMORY_API.md

        Contenu:
        - Introduction: Qu'est-ce que la memoire Ikario?
        - Architecture: Frontend ↔ Backend ↔ MCP Server
        - Routes API:
          * POST /api/memory/thoughts
          * GET /api/memory/thoughts
          * POST /api/memory/conversations
          * GET /api/memory/conversations
          * GET /api/memory/search
          * GET /api/memory/concepts/:concept
          * GET /api/memory/stats
          * GET /api/memory/health
        - Exemples curl pour chaque endpoint
        - Schemas JSON (request/response)
        - Codes erreur et troubleshooting
        - Guide integration frontend (composants)

        Format:
        - Markdown avec exemples code
        - Screenshots UI (optionnel)
        - Diagrammes architecture (mermaid)

        Integration:
        - Link depuis README.md principal
        - Affichage dans /docs page (si existe)
      </description>
      <priority>3</priority>
      <category>documentation</category>
      <files_to_create>
        - generations/my_project/docs/MEMORY_API.md
        - generations/my_project/docs/MEMORY_INTEGRATION.md
      </files_to_create>
      <test_steps>
        1. Lire documentation
        2. Verifier exemples curl fonctionnent
        3. Verifier schemas JSON corrects
        4. Tester troubleshooting steps
      </test_steps>
    </feature_13>

    <feature_14>
      <title>Tests - Memory Integration Tests</title>
      <description>
        Suite de tests d'integration pour l'API memoire.

        Fichier: generations/my_project/server/tests/memory.test.js

        Tests:
        - Connection MCP serveur
        - POST /api/memory/thoughts → add_thought MCP
        - GET /api/memory/thoughts?query=test → search_thoughts MCP
        - POST /api/memory/conversations → add_conversation MCP (conversation complete)
        - POST /api/memory/conversations/append → append_to_conversation MCP (incremental + thinking)
        - GET /api/memory/search?q=test → search_memories MCP
        - GET /api/memory/stats → aggregation
        - Error handling: MCP down
        - Error handling: Invalid params
        - Retry logic test
        - Cache invalidation test
        - Test append_to_conversation avec thinking optionnel
        - Test auto-creation de conversation via append

        Technique:
        - Mocha ou Jest pour framework test
        - Supertest pour HTTP requests
        - Mock MCP client pour tests isoles
        - Test data fixtures
        - Before/After hooks pour cleanup

        Integration:
        - npm run test:memory pour executer
        - CI/CD integration (optionnel)
      </description>
      <priority>2</priority>
      <category>backend</category>
      <files_to_create>
        - server/tests/memory.test.js
        - server/tests/fixtures/memoryData.js
      </files_to_create>
      <test_steps>
        1. npm run test:memory
        2. Verifier tous tests passent
        3. Verifier coverage >80%
        4. Tester avec MCP real et mock
      </test_steps>
    </feature_14>

    <feature_15>
      <title>Frontend - Memory Tour (Onboarding)</title>
      <description>
        Tour guide interactif pour introduire features memoire aux nouveaux users.

        Fichier: src/components/memory/MemoryTour.jsx

        UI:
        - Overlay semi-transparent
        - Spotlight sur element actif
        - Bulle explicative avec fleche
        - Boutons: Precedent | Suivant | Passer
        - Progress bar: 1/5, 2/5, etc.

        Etapes tour:
        1. "Bienvenue! Decouvrez la memoire Ikario"
        2. Spotlight sur MemoryPanel → "Ici vos pensees et conversations"
        3. Spotlight sur AddThought button → "Ajoutez une pensee rapidement"
        4. Spotlight sur Search → "Recherchez dans votre memoire semantique"
        5. Spotlight sur SaveToMemory button → "Memorisez conversations importantes"
        6. Fin: "C'est parti!"

        Fonctionnalites:
        - Declenchement au premier usage
        - Skip avec "Ne plus afficher"
        - Relancer depuis settings
        - Preference sauvee dans localStorage

        Technique:
        - react-joyride ou custom solution
        - State pour etape courante
        - Animations fluides
        - Responsive (adapt mobile)

        Integration:
        - Declenchement dans App.jsx apres login
        - Skip button dans tour
        - Relance depuis settings memoire
      </description>
      <priority>3</priority>
      <category>frontend</category>
      <files_to_create>
        - src/components/memory/MemoryTour.jsx
      </files_to_create>
      <test_steps>
        1. Premier usage → tour auto-start
        2. Naviguer toutes etapes
        3. Test skip button
        4. Verifier preference sauvee
        5. Test responsive mobile
      </test_steps>
    </feature_15>
  </core_features>

  <implementation_order>
    <phase_1>
      Backend Foundation (1-2 jours):
      1. Feature 1: Routes API Memory
      2. Feature 2: Memory Service Layer
      3. Feature 11: Error Handling & Logging
      4. Feature 14: Integration Tests
    </phase_1>

    <phase_2>
      Frontend Core (2-3 jours):
      5. Feature 12: useMemory Hook
      6. Feature 3: Memory Panel Component
      7. Feature 4: Add Thought Modal
      8. Feature 10: Memory Settings Panel
    </phase_2>

    <phase_3>
      Chat Integration (1 jour):
      9. Feature 7: Save to Memory Button
      10. Feature 8: Memory Context Panel
    </phase_3>

    <phase_4>
      Advanced Features (2-3 jours):
      11. Feature 6: Memory Search Interface
      12. Feature 5: Concepts Graph
      13. Feature 9: Memory Stats Endpoint
    </phase_4>

    <phase_5>
      Polish & Documentation (1 jour):
      14. Feature 13: Documentation
      15. Feature 15: Memory Tour
    </phase_5>
  </implementation_order>

  <testing_strategy>
    <backend_tests>
      - Integration tests pour routes API (supertest)
      - Unit tests pour memoryService
      - Mock MCP client pour tests isoles
      - Error scenarios (MCP down, timeout, invalid params)
      - Performance tests (response time <200ms)
    </backend_tests>

    <frontend_tests>
      - Component tests (React Testing Library)
      - Hook tests (useMemory)
      - E2E tests (Playwright): Add thought → Search → Results
      - Accessibility tests (axe-core)
      - Visual regression tests (Chromatic, optionnel)
    </frontend_tests>

    <integration_tests>
      - Full flow: Frontend → Backend → MCP → Backend → Frontend
      - Real MCP server tests (avec ikario_rag running)
      - Error recovery tests
      - Cache invalidation tests
    </integration_tests>
  </testing_strategy>

  <deployment_notes>
    <environment_setup>
      1. S'assurer que serveur MCP ikario_rag tourne:
         python C:/Users/david/SynologyDrive/ikario/ikario_rag/server.py

      2. Configurer .env dans my_project:
         MCP_IKARIO_SERVER_PATH=C:/Users/david/SynologyDrive/ikario/ikario_rag/server.py
         MCP_MEMORY_ENABLED=true

      3. Installer dependances frontend:
         cd generations/my_project
         npm install recharts react-force-graph-2d date-fns

      4. Lancer my_project:
         npm run dev (frontend)
         npm run server (backend)

      5. Tester connexion MCP:
         curl http://localhost:3000/api/memory/health
    </environment_setup>

    <rollback_plan>
      Si problemes:
      1. Desactiver memoire: MCP_MEMORY_ENABLED=false
      2. My_project fonctionne sans memoire (graceful degradation)
      3. Pas d'impact sur ikario_rag (serveur externe)
    </rollback_plan>
  </deployment_notes>

  <success_criteria>
    <functional>
      - Routes API memoire fonctionnelles (8 endpoints avec append_to_conversation)
      - Memory Panel affiche pensees/conversations
      - Add Thought modal fonctionne
      - Search retourne resultats pertinents
      - Save to Memory depuis chat fonctionne (avec thinking optionnel)
      - Append to conversation fonctionne (auto-create + thinking)
      - Error handling robuste (MCP down = graceful)
    </functional>

    <technical>
      - Tests backend >80% coverage
      - Response time API <200ms (95th percentile)
      - Zero crashes si MCP indisponible
      - Logs structures pour debugging
      - Documentation complete
    </technical>

    <user_experience>
      - Memory Panel accessible en 1 click
      - Add Thought en <10 secondes
      - Search results en <1 seconde
      - UI responsive (mobile ok)
      - Onboarding tour clair
    </user_experience>
  </success_criteria>

  <constraints>
    <critical_constraint>
      NE PAS MODIFIER LE CODE IKARIO_RAG:
      - Pas de changements dans C:/Users/david/SynologyDrive/ikario/ikario_rag/
      - Utiliser UNIQUEMENT les 8 outils MCP existants (incluant append_to_conversation)
      - Developper UNIQUEMENT dans generations/my_project/
      - Note: append_to_conversation et thinking support deja implementes dans ikario_rag (commit cba84fe)
    </critical_constraint>

    <technical_constraints>
      - Compatible avec architecture existante my_project
      - Pas de breaking changes
      - Graceful degradation si MCP indisponible
      - Backward compatible avec conversations existantes
    </technical_constraints>
  </constraints>
</project_specification>