sepehr/Momento
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c743ee679da4d26dc541fe48ff355a84c0f7c26
Momento/GUIDE.md
Sepehr Ramezani 48c490cd79 docs: remove tldraw references (removed from project)
2026-04-20 23:11:31 +02:00

23 KiB
Raw Blame History

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, React 19, TypeScript, Tailwind CSS 4, Prisma ORM 5 et PostgreSQL 16.

Fonctionnalites principales

Notes et organisation :

  • Notes texte, checklists et Markdown (avec support LaTeX/KaTeX)
  • Grille masonry responsive avec drag-and-drop
  • Upload d'images avec preservation de la taille originale
  • Notebooks et labels contextuels pour organiser les notes
  • Partage de notes avec permissions
  • Corbeille et archive

IA et automatisation :

  • Recherche semantique (embeddings IA) + recherche plein texte
  • Generation automatique de tags et suggestions de titre via IA
  • Agents IA configurables avec instructions personnalisees
  • Chat IA avec conversations persistees
  • Memory Echo - decouverte de connexions entre notes
  • Organisation automatique par batch et labels intelligents
  • Workflows visuels - automate de creation de workflows (noeuds, triggers)
  • Resume de notebooks genere par IA

Productivite :

  • Systeme de rappels avec notifications et recurrence
  • Mode sombre/clair avec preference systeme
  • Export/import de donnees (JSON)
  • PWA (Progressive Web App)
  • Support i18n - 15 langues (FR, EN, AR, DE, ES, FA, HI, IT, JA, KO, NL, PL, PT, RU, ZH)

Outils avances :

  • Canvas/Lab - tableau blanc avec dessin (Excalidraw)
  • Flux RSS - integration de feeds RSS
  • Serveur MCP - 37 outils pour integrer avec Claude Desktop, N8N, ou tout client MCP

Administration :

  • Authentification NextAuth.js v5 (credentials, inscription, reset mot de passe)
  • Panneau admin pour configurer les providers IA, SMTP, etc.
  • Gestion des cles API MCP
  • Pages settings : profil, apparence, donnees, MCP, IA

Stack technique

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

Architecture

Momento/
├── docker-compose.yml           # Orchestration multi-conteneurs
├── .env.docker.example          # Template config Docker
├── GUIDE.md                     # Ce guide (FR)
├── GUIDE.en.md                  # English guide
├── LICENSE                      # Apache 2.0 + Commons Clause
├── memento-note/                # Application Next.js
│   ├── app/                     # App Router (pages, actions, API)
│   │   ├── (auth)/              # Login, register, reset password
│   │   ├── (main)/              # Dashboard, admin, archive, trash, chat,
│   │   │                        # agents, reminders, lab, settings, support
│   │   ├── actions/             # Server actions (auth, notes, AI, admin)
│   │   └── api/                 # REST API routes
│   ├── components/              # Composants React
│   ├── lib/                     # Logique metier
│   │   ├── ai/                  # Factory IA + providers + services
│   │   │   ├── factory.ts       # Factory pattern (ollama/openai/custom)
│   │   │   ├── providers/       # Providers: ollama, openai, custom-openai
│   │   │   └── services/        # Agent executor, RSS, title, batch, etc.
│   │   ├── prisma.ts            # Client DB
│   │   ├── mail.ts              # Envoi d'emails (SMTP + Resend)
│   │   ├── config.ts            # Config depuis DB (SystemConfig)
│   │   └── i18n/                # Detection langue + provider
│   ├── prisma/                  # Schema + migrations PostgreSQL
│   ├── locales/                 # 15 fichiers i18n (fr.json, en.json, etc.)
│   ├── Dockerfile               # Build multi-stage (node:22-bullseye-slim)
│   ├── docker-compose.yml       # Standalone (postgres + app)
│   └── .env.example             # Template dev local
├── mcp-server/                  # Serveur MCP (37 outils)
│   ├── index.js                 # Mode stdio (Claude Desktop)
│   ├── index-sse.js             # Mode HTTP Streamable (N8N, remote)
│   ├── tools.js                 # Definitions des 37 outils MCP
│   ├── auth.js                  # Authentification API keys
│   ├── Dockerfile               # Conteneur MCP (node:20-alpine)
│   └── .env.example             # Template MCP
└── 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 HTTP Streamable)
                      ^
              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 Mode HTTP Streamable
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"

Chaine de fallback IA

Chaque fonctionnalite IA a une chaine de fallback :

  • Tags : AI_PROVIDER_TAGS -> AI_PROVIDER
  • Embeddings : AI_PROVIDER_EMBEDDING -> AI_PROVIDER_TAGS -> AI_PROVIDER
  • Chat : AI_PROVIDER_CHAT -> AI_PROVIDER_TAGS -> AI_PROVIDER_EMBEDDING -> AI_PROVIDER

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, v3.1) permet aux agents IA d'interagir avec vos notes via un protocole standardise.

Outils disponibles (37 outils)

Notes (12) :

Outil Description
create_note Creer une nouvelle note
get_notes Recuperer les notes
get_note Recuperer une note specifique
update_note Modifier une note existante
delete_note Supprimer une note
delete_all_notes Supprimer toutes les notes
search_notes Rechercher des notes par contenu
move_note Deplacer une note vers un notebook
toggle_pin Epingler/Depingler une note
toggle_archive Archiver/Desarchiver une note
export_notes Exporter les notes en JSON
import_notes Importer des notes depuis JSON

Notebooks (6) :

Outil Description
create_notebook Creer un notebook
get_notebooks Lister les notebooks
get_notebook Details d'un notebook
update_notebook Modifier un notebook
delete_notebook Supprimer un notebook
reorder_notebooks Reordonner les notebooks

Labels (4) :

Outil Description
create_label Creer un label
get_labels Lister les labels
update_label Modifier un label
delete_label Supprimer un label

IA (11) :

Outil Description
generate_title_suggestions Suggestions de titre pour une note
reformulate_text Reformuler un texte
generate_tags Generer des tags pour une note
suggest_notebook Suggerer un notebook pour une note
get_notebook_summary Resume d'un notebook
get_memory_echo Echo memoire - connexions entre notes
get_note_connections Connexions d'une note
dismiss_connection Ignorer une connexion
fuse_notes Fusionner des notes
batch_organize Organisation automatique par batch
suggest_auto_labels Suggerer des labels automatiques

Rappels (1) :

Outil Description
get_due_reminders Recuperer les rappels dus

Gestion des cles API (3) :

Outil Description
generate_api_key Generer une cle API
list_api_keys Lister les cles API
revoke_api_key Revoquer une cle API

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 HTTP Streamable (N8N, remote)

Communication via HTTP Streamable (remplace l'ancien SSE), accessible sur le reseau.

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

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

Endpoints HTTP

Endpoint Methode Description
/ GET Health check
/mcp GET/POST Endpoint MCP principal (Streamable HTTP)
/sse GET/POST Legacy (redirige vers /mcp)
/sessions GET Sessions actives

Verification

curl http://localhost:3001/
# {"name":"Memento MCP Server","version":"3.1.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/mcp (Docker) ou http://VOTRE_IP:3001/mcp

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

curl -X POST http://localhost:3001/mcp \
  -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/mcp \
  -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. Deux providers sont supportes.

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"

Mode auto

En mode auto (defaut), Memento essaie Resend en premier, puis SMTP en fallback.

Les parametres SMTP_SECURE et SMTP_IGNORE_CERT sont configurables depuis le panneau admin (stockes en DB).

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

Pages settings utilisateur

Page Route Description
Profil /settings/profile Nom, email, mot de passe
Apparence /settings/appearance Theme, langue
Donnees /settings/data Export/import, suppression
MCP /settings/mcp Configuration serveur MCP
IA /settings/ai Preferences IA

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 fallback Tags Provider pour embeddings
AI_MODEL_EMBEDDING embeddinggemma:latest Modele pour embeddings

IA - Chat

Variable Defaut Description
AI_PROVIDER_CHAT fallback Tags->Embedding 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 HTTP Streamable
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.

Reference in New Issue View Git Blame Copy Permalink