Momento/GUIDE.md

Memento - Guide d'utilisation complet

Table des matieres

1. Presentation
2. Architecture
3. Installation locale
4. Deploiement Docker
5. Configuration des providers IA
6. Serveur MCP (Model Context Protocol)
7. Integrations N8N
8. Configuration email (SMTP)
9. Administration
10. Reference des variables d'environnement
11. Commandes utiles
12. 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

# 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

# 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)

# 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)

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)

# .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 :

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)

# .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...)

# .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 :

# 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) :

{
  "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.

# .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

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

Configuration MCP avancee

# .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)

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

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

# .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

# .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

# 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

# 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

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)

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

# 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 :

# 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 pour les details complets.