Momento/GUIDE.md

# Memento - Guide d'utilisation complet

## Table des matieres

1. [Presentation](#presentation)
2. [Architecture](#architecture)
3. [Installation locale](#installation-locale)
4. [Deploiement Docker](#deploiement-docker)
5. [Configuration des providers IA](#configuration-des-providers-ia)
6. [Serveur MCP (Model Context Protocol)](#serveur-mcp)
7. [Integrations N8N](#integrations-n8n)
8. [Configuration email (SMTP)](#configuration-email)
9. [Administration](#administration)
10. [Reference des variables d'environnement](#reference-des-variables-denvironnement)
11. [Commandes utiles](#commandes-utiles)
12. [Resolution des problemes](#resolution-des-problemes)

---

## Presentation

**Memento** est une application de prise de notes intelligente, inspiree de Google Keep, construite avec Next.js 16, TypeScript, Tailwind CSS 4, Prisma et PostgreSQL.

### Fonctionnalites principales

- **Notes texte et checklists** avec couleurs personnalisees (10 themes pastel)
- **Grille masonry responsive** avec drag-and-drop
- **Upload d'images** avec preservation de la taille originale
- **Notebooks et labels contextuels** pour organiser les notes
- **Recherche semantique** (embeddings IA) + recherche plein texte
- **Generation automatique de tags** via IA
- **Suggestions de titre** par IA
- **Systeme de rappels** avec notifications
- **Mode sombre/clair** avec preference systeme
- **Authentification** NextAuth.js (credentials, inscription, reset mot de passe)
- **Panneau admin** pour configurer les providers IA, SMTP, etc.
- **Serveur MCP** pour integrer avec Claude Desktop, N8N, ou tout client MCP
- **Support i18n** (FR/EN)
- **Export/import de donnees** (JSON)
- **PWA** (Progressive Web App)

### Stack technique

| Composant | Technologie |
|-----------|-------------|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS 4 |
| UI | shadcn/ui, Lucide React |
| Backend | Next.js Server Actions, API Routes |
| Base de donnees | PostgreSQL 16 via Prisma ORM 5 |
| Authentification | NextAuth.js v5 |
| IA | Vercel AI SDK (OpenAI, Ollama, custom) |
| MCP | @modelcontextprotocol/sdk |
| Email | Nodemailer (SMTP) ou Resend |
| Docker | Docker Compose (postgres + memento-note + mcp-server + ollama) |

---

## Architecture

```
Momento/
├── docker-compose.yml           # Orchestration multi-conteneurs
├── .env.docker.example          # Template config Docker
├── LICENSE                      # Apache 2.0 + Commons Clause
├── memento-note/                # Application Next.js
│   ├── app/                     # App Router (pages, actions, API)
│   ├── components/              # Composants React
│   ├── lib/                     # Logique metier
│   │   ├── ai/                  # Providers IA (factory pattern)
│   │   ├── prisma.ts            # Client DB
│   │   ├── mail.ts              # Envoi d'emails
│   │   └── config.ts            # Config depuis DB
│   ├── prisma/                  # Schema + migrations PostgreSQL
│   ├── locales/                 # Fichiers i18n (fr.json, en.json)
│   ├── Dockerfile               # Build multi-stage (node:22-bullseye)
│   ├── docker-compose.yml       # Standalone (postgres + app)
│   └── .env.example             # Template dev local
├── mcp-server/                  # Serveur MCP
│   ├── index.js                 # Mode stdio (Claude Desktop)
│   ├── index-sse.js             # Mode SSE/HTTP (N8N, remote)
│   ├── tools.js                 # Definitions des outils MCP
│   ├── Dockerfile               # Conteneur MCP (node:20-alpine)
│   └── .env.example             # Template MCP
├── scripts/                     # Scripts de migration
└── n8n-memento-workflow.json    # Workflow N8N preconfigure
```

### Flux de donnees

```
Navigateur → Next.js App Router
              ├── Server Components (lecture)
              ├── Server Actions (ecriture)
              └── API Routes (REST)
                      ↓
                  Prisma ORM
                      ↓
                  PostgreSQL 16
                      ↑
              MCP Server (stdio ou SSE)
                      ↑
              Claude Desktop / N8N / Client MCP
```

---

## Installation locale

### Prerequis

- Node.js 20+ (22 recommande)
- PostgreSQL 16
- npm

### Etapes

```bash
# 1. Cloner le depot
git clone https://github.com/votre-user/Momento.git
cd Momento/memento-note

# 2. Installer les dependances
npm install --legacy-peer-deps

# 3. Configurer l'environnement
cp .env.example .env
# Editer .env avec vos valeurs (DATABASE_URL, NEXTAUTH_SECRET, etc.)

# 4. Creer la base de donnees et appliquer les migrations
npx prisma migrate dev

# 5. Lancer en developpement
npm run dev

# 6. Acceder a l'application
# http://localhost:3000
```

### Premier lancement

1. Creez un compte via la page d'inscription
2. Le premier utilisateur inscrit devient automatiquement admin
3. Accedez au panneau admin : `http://localhost:3000/admin/settings`

---

## Deploiement Docker

### Quick Start

```bash
# 1. Cloner le depot
git clone https://github.com/votre-user/Momento.git
cd Momento

# 2. Configurer l'environnement
cp .env.docker.example .env.docker
nano .env.docker
# Modifier NEXTAUTH_URL et NEXTAUTH_SECRET (obligatoire)

# 3. Lancer les conteneurs
docker compose up -d

# 4. Verifier que tout fonctionne
docker compose ps
docker compose logs -f memento-note
```

### Avec Ollama (IA locale)

```bash
# Ajouter le profile ollama
docker compose --profile ollama up -d

# Tirer un modele
docker exec memento-ollama ollama pull granite4
docker exec memento-ollama ollama pull embeddinggemma
```

### Variables Docker obligatoires

| Variable | Description |
|----------|-------------|
| `NEXTAUTH_URL` | URL publique de l'app (ex: `http://192.168.1.190:3000`) |
| `NEXTAUTH_SECRET` | Secret JWT - generer avec `openssl rand -base64 32` |

### Ports utilises

| Service | Port | Description |
|---------|------|-------------|
| memento-note | 3000 | Application web |
| PostgreSQL | 5432 | Base de donnees |
| MCP Server | 3001 | SSE mode uniquement |
| Ollama | 11434 | IA locale (optionnel) |

### Reverse Proxy (Nginx)

```nginx
server {
    listen 80;
    server_name notes.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    client_max_body_size 10M;
}
```

---

## Configuration des providers IA

Memento supporte 3 providers IA, configurables independamment pour chaque fonctionnalite (tags, embeddings, chat).

### Provider 1 : Ollama (IA locale, gratuit)

```bash
# .env.docker
AI_PROVIDER_TAGS=ollama
AI_PROVIDER_EMBEDDING=ollama
OLLAMA_BASE_URL="http://ollama:11434"
AI_MODEL_TAGS="granite4:latest"
AI_MODEL_EMBEDDING="embeddinggemma:latest"
```

Lancer avec le profile ollama :
```bash
docker compose --profile ollama up -d
docker exec memento-ollama ollama pull granite4
docker exec memento-ollama ollama pull embeddinggemma
```

**Ressources recommandees** : 8 Go RAM, 4 CPU

### Provider 2 : OpenAI (cloud, payant)

```bash
# .env.docker
AI_PROVIDER_TAGS=openai
AI_PROVIDER_EMBEDDING=openai
OPENAI_API_KEY="sk-votre-cle-ici"
AI_MODEL_TAGS="gpt-4o-mini"
AI_MODEL_EMBEDDING="text-embedding-3-small"
```

### Provider 3 : Custom (OpenRouter, Groq, Together, Mistral...)

```bash
# .env.docker
AI_PROVIDER_TAGS=custom
AI_PROVIDER_EMBEDDING=custom
CUSTOM_OPENAI_API_KEY="votre-cle-api"
CUSTOM_OPENAI_BASE_URL="https://openrouter.ai/api/v1"
AI_MODEL_TAGS="openai/gpt-4o-mini"
AI_MODEL_EMBEDDING="openai/text-embedding-3-small"
```

| Provider | URL de base |
|----------|-------------|
| OpenRouter | `https://openrouter.ai/api/v1` |
| Groq | `https://api.groq.com/openai/v1` |
| Together AI | `https://api.together.xyz/v1` |
| Mistral | `https://api.mistral.ai/v1` |

### Configuration mixte

Vous pouvez utiliser des providers differents pour chaque fonctionnalite :

```bash
# Ollama pour les tags, OpenAI pour les embeddings
AI_PROVIDER_TAGS=ollama
AI_PROVIDER_EMBEDDING=openai
OLLAMA_BASE_URL="http://ollama:11434"
OPENAI_API_KEY="sk-..."
AI_MODEL_TAGS="granite4:latest"
AI_MODEL_EMBEDDING="text-embedding-3-small"
```

### Configuration via le panneau admin

Les providers IA peuvent aussi etre configures depuis l'interface :
1. Se connecter en admin
2. Aller sur `/admin/settings`
3. Section "AI Settings"
4. Choisir le provider, le modele, et entrer la cle API
5. Sauvegarder

**Note** : Les parametres du panneau admin (stockes en DB) sont prioritaires sur les variables d'environnement.

---

## Serveur MCP

Le serveur MCP (Model Context Protocol) permet aux agents IA d'interagir avec vos notes via un protocole standardise.

### Outils disponibles (9 outils)

| Outil | Description |
|-------|-------------|
| `create_note` | Creer une nouvelle note |
| `get_notes` | Recuperer toutes les notes |
| `get_note` | Recuperer une note specifique |
| `update_note` | Modifier une note existante |
| `delete_note` | Supprimer une note |
| `search_notes` | Rechercher des notes par contenu |
| `get_labels` | Lister les labels |
| `toggle_pin` | Epingler/Depingler une note |
| `toggle_archive` | Archiver/Desarchiver une note |

### Mode stdio (Claude Desktop, Cline)

Communication via stdin/stdout, ideal pour les clients locaux.

**Configuration Claude Desktop** (`claude_desktop_config.json`) :
```json
{
  "mcpServers": {
    "memento": {
      "command": "docker",
      "args": ["exec", "-i", "memento-mcp", "node", "index.js"]
    }
  }
}
```

### Mode SSE (N8N, HTTP)

Communication via HTTP Server-Sent Events, accessible sur le reseau.

```bash
# .env.docker
MCP_MODE="sse"
MCP_PORT="3001"
```

Le serveur sera accessible sur `http://localhost:3001`.

#### Endpoints SSE

| Endpoint | Methode | Description |
|----------|---------|-------------|
| `/` | GET | Health check |
| `/sse` | GET/POST | Endpoint MCP principal |
| `/message` | POST | Envoi de messages |
| `/sessions` | GET | Sessions actives |

#### Verification

```bash
curl http://localhost:3001/
# {"name":"Memento MCP SSE Server","version":"1.0.0","status":"running"}
```

### Configuration MCP avancee

```bash
# .env.docker
MCP_LOG_LEVEL=info          # debug, info, warn, error
MCP_REQUEST_TIMEOUT=30000   # Timeout en ms
MCP_REQUIRE_AUTH=false      # Activer l'authentification
MCP_API_KEY="votre-cle"     # Cle API si auth active
APP_BASE_URL="http://localhost:3000"  # URL de l'app pour les liens
```

---

## Integrations N8N

### Configuration du noeud MCP Client

1. Ajouter un noeud **"MCP Client"** dans N8N
2. Selectionner **"HTTP Streamable"** comme transport
3. Configurer l'endpoint : `http://memento-mcp:3001/sse` (Docker) ou `http://VOTRE_IP:3001/sse`

### Workflows preconfigures

Le fichier `n8n-memento-workflow.json` contient un workflow pret a l'emploi pour :
- Creer des notes automatiquement
- Rechercher des notes
- Archiver les notes anciennes

### Exemples d'utilisation

#### Creer une note via curl (SSE mode)

```bash
curl -X POST http://localhost:3001/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_note",
      "arguments": {
        "title": "Ma note",
        "content": "Contenu de la note"
      }
    }
  }'
```

#### Lister les outils disponibles

```bash
curl -X POST http://localhost:3001/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

---

## Configuration email

L'email est necessaire pour la reinitialisation de mot de passe et les rappels.

### Option 1 : SMTP

```bash
# .env.docker
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="votre-email@gmail.com"
SMTP_PASS="votre-mot-de-passe-app"
SMTP_FROM="noreply@votre-domaine.com"
```

| Provider | Host | Port |
|----------|------|------|
| Gmail | smtp.gmail.com | 587 |
| Outlook | smtp.office365.com | 587 |
| SendGrid | smtp.sendgrid.net | 587 |
| Mailgun | smtp.mailgun.org | 587 |

### Option 2 : Resend

```bash
# .env.docker
RESEND_API_KEY="re_votre-cle"
```

Les parametres `SMTP_SECURE` et `SMTP_IGNORE_CERT` sont configurables depuis le panneau admin.

---

## Administration

### Panneau admin

Accessibles uniquement par le premier utilisateur inscrit (ou les utilisateurs avec le role admin).

**URL** : `/admin/settings`

### Sections configurables

1. **AI Settings** - Provider, modele, cle API pour tags, embeddings et chat
2. **Email Settings** - Configuration SMTP
3. **General Settings** - Inscription publique activee/desactivee

### Gestion des utilisateurs

- Les utilisateurs sont geres via `/admin`
- Le premier utilisateur inscrit est automatiquement admin
- L'inscription peut etre desactivee avec `ALLOW_REGISTRATION=false`

---

## Reference des variables d'environnement

### Fichiers .env

| Fichier | Usage |
|---------|-------|
| `.env.docker` | Configuration Docker (lu par docker-compose via env_file) |
| `.env.docker.example` | Template pour `.env.docker` |
| `memento-note/.env` | Configuration dev local |
| `memento-note/.env.example` | Template pour dev local |
| `mcp-server/.env` | Configuration du serveur MCP |
| `mcp-server/.env.example` | Template pour MCP |

### Variables completes

#### Core (obligatoire)

| Variable | Defaut | Description |
|----------|--------|-------------|
| `DATABASE_URL` | - | Connection string PostgreSQL |
| `NEXTAUTH_SECRET` | - | Secret JWT (`openssl rand -base64 32`) |
| `NEXTAUTH_URL` | `http://localhost:3000` | URL publique de l'app |

#### PostgreSQL (Docker)

| Variable | Defaut | Description |
|----------|--------|-------------|
| `POSTGRES_USER` | `memento` | Utilisateur PostgreSQL |
| `POSTGRES_PASSWORD` | `memento` | Mot de passe PostgreSQL |
| `POSTGRES_DB` | `memento` | Nom de la base |
| `POSTGRES_PORT` | `5432` | Port expose |

#### IA - Tags

| Variable | Defaut | Description |
|----------|--------|-------------|
| `AI_PROVIDER_TAGS` | - | Provider pour tags (`ollama`, `openai`, `custom`) |
| `AI_MODEL_TAGS` | `granite4:latest` | Modele pour tags |

#### IA - Embeddings

| Variable | Defaut | Description |
|----------|--------|-------------|
| `AI_PROVIDER_EMBEDDING` | - | Provider pour embeddings |
| `AI_MODEL_EMBEDDING` | `embeddinggemma:latest` | Modele pour embeddings |

#### IA - Chat

| Variable | Defaut | Description |
|----------|--------|-------------|
| `AI_PROVIDER_CHAT` | fallback Tags | Provider pour chat |
| `AI_MODEL_CHAT` | fallback Tags | Modele pour chat |

#### IA - OpenAI

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | Cle API OpenAI (`sk-...`) |

#### IA - Ollama

| Variable | Defaut | Description |
|----------|--------|-------------|
| `OLLAMA_BASE_URL` | - | URL du service Ollama |

#### IA - Custom provider

| Variable | Description |
|----------|-------------|
| `CUSTOM_OPENAI_API_KEY` | Cle API du provider |
| `CUSTOM_OPENAI_BASE_URL` | URL de base du provider |

#### MCP Server

| Variable | Defaut | Description |
|----------|--------|-------------|
| `MCP_MODE` | `stdio` | Mode (`stdio` ou `sse`) |
| `MCP_PORT` | `3001` | Port SSE |
| `MCP_LOG_LEVEL` | `info` | Niveau de log |
| `MCP_REQUEST_TIMEOUT` | `30000` | Timeout (ms) |
| `MCP_REQUIRE_AUTH` | `false` | Activer authentification |
| `MCP_API_KEY` | - | Cle API pour auth |
| `APP_BASE_URL` | `http://localhost:3000` | URL de l'app |
| `USER_ID` | - | Filtrer par utilisateur |

#### Email

| Variable | Defaut | Description |
|----------|--------|-------------|
| `SMTP_HOST` | - | Serveur SMTP |
| `SMTP_PORT` | `587` | Port SMTP |
| `SMTP_USER` | - | Utilisateur SMTP |
| `SMTP_PASS` | - | Mot de passe SMTP |
| `SMTP_FROM` | `noreply@memento.app` | Email expediteur |
| `RESEND_API_KEY` | - | Cle API Resend |

#### Application

| Variable | Defaut | Description |
|----------|--------|-------------|
| `ALLOW_REGISTRATION` | `true` | Autoriser l'inscription publique |
| `NODE_ENV` | `development` | Environnement |
| `PORT` | `3000` | Port de l'app |
| `HOSTNAME` | `0.0.0.0` | Host d'ecoute |

---

## Commandes utiles

### Docker

```bash
# Demarrer tous les services
docker compose up -d

# Avec Ollama
docker compose --profile ollama up -d

# Voir les logs
docker compose logs -f
docker compose logs -f memento-note    # App seulement
docker compose logs -f mcp-server      # MCP seulement

# Statut des services
docker compose ps

# Reconstruire apres modification
docker compose down
docker compose build --no-cache
docker compose up -d

# Acceder a un conteneur
docker compose exec memento-note sh
docker compose exec mcp-server sh

# Arreter et supprimer les volumes (ATTENTION : perte de donnees)
docker compose down -v
```

### Base de donnees

```bash
# Lancer Prisma Studio (GUI pour la DB)
cd memento-note
npx prisma studio

# Creer une migration
npx prisma migrate dev --name nom_de_la_migration

# Appliquer les migrations en production
npx prisma migrate deploy

# Regenerer le client Prisma
npx prisma generate
```

### Developpement

```bash
cd memento-note

# Dev avec hot-reload
npm run dev

# Build production
npm run build
npm start

# Linter
npm run lint
```

### Deploy.sh (script de deploiement)

```bash
cd memento-note
chmod +x deploy.sh

./deploy.sh build     # Construire l'image
./deploy.sh start     # Demarrer les conteneurs
./deploy.sh logs      # Voir les logs
./deploy.sh backup    # Sauvegarder la DB
./deploy.sh update    # Mettre a jour l'app
```

---

## Resolution des problemes

### Erreur : `ECONNREFUSED 127.0.0.1:11434`

**Cause** : L'app essaie d'acceder a Ollama via localhost au lieu du service Docker.

**Solution** : Verifier que `.env.docker` contient :
```
OLLAMA_BASE_URL="http://ollama:11434"
```

### Le provider IA ne change pas dans l'admin

1. Sauvegarder les modifications dans l'admin
2. Rafraichir la page (F5)
3. Verifier la valeur affichee sous le dropdown

### Docker ne demarre pas

```bash
# Verifier les logs
docker compose logs memento-note

# Verifier la DB
docker compose exec postgres pg_isready -U memento

# Reconstruire
docker compose build --no-cache memento-note
```

### Mot de passe oublie sans SMTP

Si vous n'avez pas configure l'email, vous pouvez reinitialiser le mot de passe manuellement :

```bash
# Se connecter a la DB
docker compose exec postgres psql -U memento -d memento

# ou en local
cd memento-note
npx prisma studio
```

### Les embeddings ne se generent pas

1. Verifier que le provider d'embeddings est correctement configure
2. Verifier que le modele d'embedding est disponible
3. En admin, lancer la regeneration manuelle des embeddings

---

## Licence

Apache License 2.0 avec Commons Clause Restriction.
Usage personnel et educatif libre. Usage commercial interdit sans autorisation ecrite de l'auteur.
Voir le fichier [LICENSE](LICENSE) pour les details complets.