From 3b7bbdda8cde33da80f4cd45f45d0a0b8eb21f98 Mon Sep 17 00:00:00 2001 From: Sepehr Ramezani Date: Mon, 20 Apr 2026 23:07:58 +0200 Subject: [PATCH] docs: rewrite GUIDE.md with accurate code analysis, add English translation Major corrections based on thorough code verification: - MCP tools: 9 -> 37 (added notebooks, labels, AI, reminders, API keys) - MCP transport: SSE -> HTTP Streamable (SSE is legacy redirect) - MCP endpoint: /sse -> /mcp as primary - MCP version: 1.0.0 -> 3.1.0 - i18n: FR/EN -> 15 languages - Added missing features: Agents, Workflows, Chat, Canvas/Lab, Memory Echo, Note Sharing, Markdown/LaTeX, RSS, Batch Organization - Fixed Dockerfile image: node:22-bullseye -> node:22-bullseye-slim - Fixed AI fallback chain documentation - Added user settings pages table - Added auto email mode (Resend + SMTP fallback) - Added GUIDE.en.md (English translation) --- GUIDE.en.md | 833 ++++++++++++++++++++++++++++++++++++++++++++++++++++ GUIDE.md | 212 +++++++++---- 2 files changed, 993 insertions(+), 52 deletions(-) create mode 100644 GUIDE.en.md diff --git a/GUIDE.en.md b/GUIDE.en.md new file mode 100644 index 0000000..a76159d --- /dev/null +++ b/GUIDE.en.md @@ -0,0 +1,833 @@ +# Memento - Complete User Guide + +## Table of Contents + +1. [Overview](#overview) +2. [Architecture](#architecture) +3. [Local Installation](#local-installation) +4. [Docker Deployment](#docker-deployment) +5. [AI Provider Configuration](#ai-provider-configuration) +6. [MCP Server (Model Context Protocol)](#mcp-server) +7. [N8N Integrations](#n8n-integrations) +8. [Email Configuration (SMTP)](#email-configuration) +9. [Administration](#administration) +10. [Environment Variables Reference](#environment-variables-reference) +11. [Useful Commands](#useful-commands) +12. [Troubleshooting](#troubleshooting) + +--- + +## Overview + +**Memento** is a smart note-taking application, inspired by Google Keep, built with Next.js 16, React 19, TypeScript, Tailwind CSS 4, Prisma ORM 5, and PostgreSQL 16. + +### Key Features + +**Notes and organization:** +- **Text notes, checklists, and Markdown** (with LaTeX/KaTeX support) +- **Responsive masonry grid** with drag-and-drop +- **Image upload** with original size preservation +- **Notebooks and contextual labels** to organize notes +- **Note sharing** with permissions +- **Trash** and **archive** + +**AI and automation:** +- **Semantic search** (AI embeddings) + full-text search +- **Automatic tag generation** and AI-powered title suggestions +- **Configurable AI agents** with custom instructions +- **AI chat** with persistent conversations +- **Memory Echo** - discover connections between notes +- **Automatic batch organization** and smart labels +- **Visual workflows** - workflow creation automator (nodes, triggers) +- **AI-generated notebook summaries** + +**Productivity:** +- **Reminder system** with notifications and recurrence +- **Dark/light mode** with system preference support +- **Data export/import** (JSON) +- **PWA** (Progressive Web App) +- **i18n support** - 15 languages (FR, EN, AR, DE, ES, FA, HI, IT, JA, KO, NL, PL, PT, RU, ZH) + +**Advanced tools:** +- **Canvas/Lab** - whiteboard with drawing (Excalidraw/tldraw) +- **RSS feeds** - RSS feed integration +- **MCP Server** - 37 tools to integrate with Claude Desktop, N8N, or any MCP client + +**Administration:** +- **Authentication** via NextAuth.js v5 (credentials, registration, password reset) +- **Admin panel** to configure AI providers, SMTP, etc. +- **MCP API key management** +- **Settings pages**: profile, appearance, data, MCP, AI + +### Tech Stack + +| Component | Technology | +|-----------|-------------| +| 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 | +| Database | PostgreSQL 16 via Prisma ORM 5.22 | +| Authentication | NextAuth.js v5 | +| AI | Vercel AI SDK (OpenAI, Ollama, Custom OpenAI-compatible) | +| MCP | @modelcontextprotocol/sdk v3.1 | +| Email | Nodemailer (SMTP) or Resend | +| Canvas | Excalidraw / tldraw | +| Docker | Docker Compose (postgres + memento-note + mcp-server + ollama) | + +--- + +## Architecture + +``` +Momento/ +├── docker-compose.yml # Multi-container orchestration +├── .env.docker.example # Docker config template +├── GUIDE.md # This guide (FR) +├── GUIDE.en.md # English guide +├── LICENSE # Apache 2.0 + Commons Clause +├── memento-note/ # Next.js application +│ ├── 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/ # React components +│ ├── lib/ # Business logic +│ │ ├── ai/ # AI factory + providers + services +│ │ │ ├── factory.ts # Factory pattern (ollama/openai/custom) +│ │ │ ├── providers/ # Providers: ollama, openai, custom-openai +│ │ │ └── services/ # Agent executor, RSS, title, batch, etc. +│ │ ├── prisma.ts # DB client +│ │ ├── mail.ts # Email sending (SMTP + Resend) +│ │ ├── config.ts # Config from DB (SystemConfig) +│ │ └── i18n/ # Language detection + provider +│ ├── prisma/ # PostgreSQL schema + migrations +│ ├── locales/ # 15 i18n files (fr.json, en.json, etc.) +│ ├── Dockerfile # Multi-stage build (node:22-bullseye-slim) +│ ├── docker-compose.yml # Standalone (postgres + app) +│ └── .env.example # Local dev template +├── mcp-server/ # MCP Server (37 tools) +│ ├── index.js # stdio mode (Claude Desktop) +│ ├── index-sse.js # HTTP Streamable mode (N8N, remote) +│ ├── tools.js # Definitions of the 37 MCP tools +│ ├── auth.js # API key authentication +│ ├── Dockerfile # MCP container (node:20-alpine) +│ └── .env.example # MCP template +└── n8n-memento-workflow.json # Pre-configured N8N workflow +``` + +### Data Flow + +``` +Browser -> Next.js App Router + |-- Server Components (read) + |-- Server Actions (write) + `-- API Routes (REST) + | + Prisma ORM + | + PostgreSQL 16 + ^ + MCP Server (stdio or HTTP Streamable) + ^ + Claude Desktop / N8N / MCP Client +``` + +--- + +## Local Installation + +### Prerequisites + +- Node.js 20+ (22 recommended) +- PostgreSQL 16 +- npm + +### Steps + +```bash +# 1. Clone the repository +git clone https://github.com/votre-user/Momento.git +cd Momento/memento-note + +# 2. Install dependencies +npm install --legacy-peer-deps + +# 3. Configure the environment +cp .env.example .env +# Edit .env with your values (DATABASE_URL, NEXTAUTH_SECRET, etc.) + +# 4. Create the database and apply migrations +npx prisma migrate dev + +# 5. Start in development mode +npm run dev + +# 6. Access the application +# http://localhost:3000 +``` + +### First Launch + +1. Create an account via the registration page +2. The first registered user automatically becomes admin +3. Access the admin panel: `http://localhost:3000/admin/settings` + +--- + +## Docker Deployment + +### Quick Start + +```bash +# 1. Clone the repository +git clone https://github.com/votre-user/Momento.git +cd Momento + +# 2. Configure the environment +cp .env.docker.example .env.docker +nano .env.docker +# Modify NEXTAUTH_URL and NEXTAUTH_SECRET (required) + +# 3. Start the containers +docker compose up -d + +# 4. Verify everything is working +docker compose ps +docker compose logs -f memento-note +``` + +### With Ollama (Local AI) + +```bash +# Add the ollama profile +docker compose --profile ollama up -d + +# Pull a model +docker exec memento-ollama ollama pull granite4 +docker exec memento-ollama ollama pull embeddinggemma +``` + +### Required Docker Variables + +| Variable | Description | +|----------|-------------| +| `NEXTAUTH_URL` | Public URL of the app (e.g., `http://192.168.1.190:3000`) | +| `NEXTAUTH_SECRET` | JWT secret - generate with `openssl rand -base64 32` | + +### Ports Used + +| Service | Port | Description | +|---------|------|-------------| +| memento-note | 3000 | Web application | +| PostgreSQL | 5432 | Database | +| MCP Server | 3001 | HTTP Streamable mode | +| Ollama | 11434 | Local AI (optional) | + +### 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; +} +``` + +--- + +## AI Provider Configuration + +Memento supports 3 AI providers, each configurable independently for every feature (tags, embeddings, chat). + +### Provider 1: Ollama (Local AI, Free) + +```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" +``` + +Start with the ollama profile: +```bash +docker compose --profile ollama up -d +docker exec memento-ollama ollama pull granite4 +docker exec memento-ollama ollama pull embeddinggemma +``` + +**Recommended resources**: 8 GB RAM, 4 CPUs + +### Provider 2: OpenAI (Cloud, Paid) + +```bash +# .env.docker +AI_PROVIDER_TAGS=openai +AI_PROVIDER_EMBEDDING=openai +OPENAI_API_KEY="sk-your-key-here" +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="your-api-key" +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 | Base URL | +|----------|----------| +| 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` | + +### Mixed Configuration + +You can use different providers for each feature: + +```bash +# Ollama for tags, OpenAI for 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" +``` + +### AI Fallback Chain + +Each AI feature has a fallback chain: +- **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 Admin Panel + +AI providers can also be configured from the interface: +1. Log in as admin +2. Go to `/admin/settings` +3. "AI Settings" section +4. Choose the provider, model, and enter the API key +5. Save + +**Note**: Admin panel settings (stored in DB) take priority over environment variables. + +--- + +## MCP Server + +The MCP server (Model Context Protocol, v3.1) allows AI agents to interact with your notes via a standardized protocol. + +### Available Tools (37 tools) + +**Notes (12):** + +| Tool | Description | +|------|-------------| +| `create_note` | Create a new note | +| `get_notes` | Retrieve notes | +| `get_note` | Retrieve a specific note | +| `update_note` | Modify an existing note | +| `delete_note` | Delete a note | +| `delete_all_notes` | Delete all notes | +| `search_notes` | Search notes by content | +| `move_note` | Move a note to a notebook | +| `toggle_pin` | Pin/Unpin a note | +| `toggle_archive` | Archive/Unarchive a note | +| `export_notes` | Export notes as JSON | +| `import_notes` | Import notes from JSON | + +**Notebooks (6):** + +| Tool | Description | +|------|-------------| +| `create_notebook` | Create a notebook | +| `get_notebooks` | List notebooks | +| `get_notebook` | Notebook details | +| `update_notebook` | Modify a notebook | +| `delete_notebook` | Delete a notebook | +| `reorder_notebooks` | Reorder notebooks | + +**Labels (4):** + +| Tool | Description | +|------|-------------| +| `create_label` | Create a label | +| `get_labels` | List labels | +| `update_label` | Modify a label | +| `delete_label` | Delete a label | + +**AI (11):** + +| Tool | Description | +|------|-------------| +| `generate_title_suggestions` | Title suggestions for a note | +| `reformulate_text` | Reformulate text | +| `generate_tags` | Generate tags for a note | +| `suggest_notebook` | Suggest a notebook for a note | +| `get_notebook_summary` | Notebook summary | +| `get_memory_echo` | Memory echo - connections between notes | +| `get_note_connections` | Connections of a note | +| `dismiss_connection` | Dismiss a connection | +| `fuse_notes` | Merge notes | +| `batch_organize` | Automatic batch organization | +| `suggest_auto_labels` | Suggest automatic labels | + +**Reminders (1):** + +| Tool | Description | +|------|-------------| +| `get_due_reminders` | Retrieve due reminders | + +**API Key Management (3):** + +| Tool | Description | +|------|-------------| +| `generate_api_key` | Generate an API key | +| `list_api_keys` | List API keys | +| `revoke_api_key` | Revoke an API key | + +### stdio Mode (Claude Desktop, Cline) + +Communication via stdin/stdout, ideal for local clients. + +**Claude Desktop Configuration** (`claude_desktop_config.json`): +```json +{ + "mcpServers": { + "memento": { + "command": "docker", + "args": ["exec", "-i", "memento-mcp", "node", "index.js"] + } + } +} +``` + +### HTTP Streamable Mode (N8N, Remote) + +Communication via HTTP Streamable (replaces the legacy SSE), accessible over the network. + +```bash +# .env.docker +MCP_MODE="sse" +MCP_PORT="3001" +``` + +The server will be accessible at `http://localhost:3001`. + +#### HTTP Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/` | GET | Health check | +| `/mcp` | GET/POST | Main MCP endpoint (Streamable HTTP) | +| `/sse` | GET/POST | Legacy (redirects to `/mcp`) | +| `/sessions` | GET | Active sessions | + +#### Verification + +```bash +curl http://localhost:3001/ +# {"name":"Memento MCP Server","version":"3.1.0","status":"running",...} +``` + +### Advanced MCP Configuration + +```bash +# .env.docker +MCP_LOG_LEVEL=info # debug, info, warn, error +MCP_REQUEST_TIMEOUT=30000 # Timeout in ms +MCP_REQUIRE_AUTH=false # Enable authentication +MCP_API_KEY="your-key" # API key if auth is enabled +APP_BASE_URL="http://localhost:3000" # App URL for links +``` + +--- + +## N8N Integrations + +### MCP Client Node Configuration + +1. Add an **"MCP Client"** node in N8N +2. Select **"HTTP Streamable"** as transport +3. Configure the endpoint: `http://memento-mcp:3001/mcp` (Docker) or `http://YOUR_IP:3001/mcp` + +### Pre-configured Workflows + +The `n8n-memento-workflow.json` file contains a ready-to-use workflow for: +- Automatically creating notes +- Searching notes +- Archiving old notes + +### Usage Examples + +#### Create a note via curl + +```bash +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": "My note", + "content": "Note content" + } + } + }' +``` + +#### List available tools + +```bash +curl -X POST http://localhost:3001/mcp \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/list", + "params": {} + }' +``` + +--- + +## Email Configuration + +Email is required for password reset and reminders. Two providers are supported. + +### Option 1: SMTP + +```bash +# .env.docker +SMTP_HOST="smtp.gmail.com" +SMTP_PORT="587" +SMTP_USER="your-email@gmail.com" +SMTP_PASS="your-app-password" +SMTP_FROM="noreply@your-domain.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_your-key" +``` + +### Auto Mode + +In `auto` mode (default), Memento tries Resend first, then falls back to SMTP. + +The `SMTP_SECURE` and `SMTP_IGNORE_CERT` settings can be configured from the admin panel (stored in DB). + +--- + +## Administration + +### Admin Panel + +Accessible only to the first registered user (or users with the admin role). + +**URL**: `/admin/settings` + +### Configurable Sections + +1. **AI Settings** - Provider, model, API key for tags, embeddings, and chat +2. **Email Settings** - SMTP configuration +3. **General Settings** - Enable/disable public registration + +### User Settings Pages + +| Page | Route | Description | +|------|-------|-------------| +| Profile | `/settings/profile` | Name, email, password | +| Appearance | `/settings/appearance` | Theme, language | +| Data | `/settings/data` | Export/import, deletion | +| MCP | `/settings/mcp` | MCP server configuration | +| AI | `/settings/ai` | AI preferences | + +### User Management + +- Users are managed via `/admin` +- The first registered user is automatically admin +- Registration can be disabled with `ALLOW_REGISTRATION=false` + +--- + +## Environment Variables Reference + +### .env Files + +| File | Usage | +|------|-------| +| `.env.docker` | Docker configuration (read by docker-compose via env_file) | +| `.env.docker.example` | Template for `.env.docker` | +| `memento-note/.env` | Local dev configuration | +| `memento-note/.env.example` | Template for local dev | +| `mcp-server/.env` | MCP server configuration | +| `mcp-server/.env.example` | Template for MCP | + +### Complete Variables + +#### Core (Required) + +| Variable | Default | Description | +|----------|---------|-------------| +| `DATABASE_URL` | - | PostgreSQL connection string | +| `NEXTAUTH_SECRET` | - | JWT secret (`openssl rand -base64 32`) | +| `NEXTAUTH_URL` | `http://localhost:3000` | Public URL of the app | + +#### PostgreSQL (Docker) + +| Variable | Default | Description | +|----------|---------|-------------| +| `POSTGRES_USER` | `memento` | PostgreSQL user | +| `POSTGRES_PASSWORD` | `memento` | PostgreSQL password | +| `POSTGRES_DB` | `memento` | Database name | +| `POSTGRES_PORT` | `5432` | Exposed port | + +#### AI - Tags + +| Variable | Default | Description | +|----------|---------|-------------| +| `AI_PROVIDER_TAGS` | - | Provider for tags (`ollama`, `openai`, `custom`) | +| `AI_MODEL_TAGS` | `granite4:latest` | Model for tags | + +#### AI - Embeddings + +| Variable | Default | Description | +|----------|---------|-------------| +| `AI_PROVIDER_EMBEDDING` | fallback Tags | Provider for embeddings | +| `AI_MODEL_EMBEDDING` | `embeddinggemma:latest` | Model for embeddings | + +#### AI - Chat + +| Variable | Default | Description | +|----------|---------|-------------| +| `AI_PROVIDER_CHAT` | fallback Tags->Embedding | Provider for chat | +| `AI_MODEL_CHAT` | fallback Tags | Model for chat | + +#### AI - OpenAI + +| Variable | Description | +|----------|-------------| +| `OPENAI_API_KEY` | OpenAI API key (`sk-...`) | + +#### AI - Ollama + +| Variable | Default | Description | +|----------|---------|-------------| +| `OLLAMA_BASE_URL` | - | Ollama service URL | + +#### AI - Custom Provider + +| Variable | Description | +|----------|-------------| +| `CUSTOM_OPENAI_API_KEY` | Provider API key | +| `CUSTOM_OPENAI_BASE_URL` | Provider base URL | + +#### MCP Server + +| Variable | Default | Description | +|----------|---------|-------------| +| `MCP_MODE` | `stdio` | Mode (`stdio` or `sse`) | +| `MCP_PORT` | `3001` | HTTP Streamable port | +| `MCP_LOG_LEVEL` | `info` | Log level | +| `MCP_REQUEST_TIMEOUT` | `30000` | Timeout (ms) | +| `MCP_REQUIRE_AUTH` | `false` | Enable authentication | +| `MCP_API_KEY` | - | API key for auth | +| `APP_BASE_URL` | `http://localhost:3000` | App URL | +| `USER_ID` | - | Filter by user | + +#### Email + +| Variable | Default | Description | +|----------|---------|-------------| +| `SMTP_HOST` | - | SMTP server | +| `SMTP_PORT` | `587` | SMTP port | +| `SMTP_USER` | - | SMTP user | +| `SMTP_PASS` | - | SMTP password | +| `SMTP_FROM` | `noreply@memento.app` | Sender email | +| `RESEND_API_KEY` | - | Resend API key | + +#### Application + +| Variable | Default | Description | +|----------|---------|-------------| +| `ALLOW_REGISTRATION` | `true` | Allow public registration | +| `NODE_ENV` | `development` | Environment | +| `PORT` | `3000` | App port | +| `HOSTNAME` | `0.0.0.0` | Listen host | + +--- + +## Useful Commands + +### Docker + +```bash +# Start all services +docker compose up -d + +# With Ollama +docker compose --profile ollama up -d + +# View logs +docker compose logs -f +docker compose logs -f memento-note # App only +docker compose logs -f mcp-server # MCP only + +# Service status +docker compose ps + +# Rebuild after modification +docker compose down +docker compose build --no-cache +docker compose up -d + +# Access a container +docker compose exec memento-note sh +docker compose exec mcp-server sh + +# Stop and remove volumes (WARNING: data loss) +docker compose down -v +``` + +### Database + +```bash +# Launch Prisma Studio (GUI for the DB) +cd memento-note +npx prisma studio + +# Create a migration +npx prisma migrate dev --name name_of_the_migration + +# Apply migrations in production +npx prisma migrate deploy + +# Regenerate the Prisma client +npx prisma generate +``` + +### Development + +```bash +cd memento-note + +# Dev with hot-reload +npm run dev + +# Production build +npm run build +npm start + +# Linter +npm run lint +``` + +### deploy.sh (Deployment Script) + +```bash +cd memento-note +chmod +x deploy.sh + +./deploy.sh build # Build the image +./deploy.sh start # Start the containers +./deploy.sh logs # View logs +./deploy.sh backup # Backup the DB +./deploy.sh update # Update the app +``` + +--- + +## Troubleshooting + +### Error: `ECONNREFUSED 127.0.0.1:11434` + +**Cause**: The app is trying to reach Ollama via localhost instead of the Docker service. + +**Solution**: Verify that `.env.docker` contains: +``` +OLLAMA_BASE_URL="http://ollama:11434" +``` + +### AI Provider Does Not Change in Admin + +1. Save changes in the admin panel +2. Refresh the page (F5) +3. Check the value displayed below the dropdown + +### Docker Does Not Start + +```bash +# Check logs +docker compose logs memento-note + +# Check the DB +docker compose exec postgres pg_isready -U memento + +# Rebuild +docker compose build --no-cache memento-note +``` + +### Forgotten Password Without SMTP + +If you have not configured email, you can reset the password manually: + +```bash +# Connect to the DB +docker compose exec postgres psql -U memento -d memento + +# or locally +cd memento-note +npx prisma studio +``` + +### Embeddings Are Not Generating + +1. Verify that the embeddings provider is correctly configured +2. Verify that the embedding model is available +3. In the admin panel, trigger manual regeneration of embeddings + +--- + +## License + +Apache License 2.0 with Commons Clause Restriction. +Free for personal and educational use. Commercial use is prohibited without written permission from the author. +See the [LICENSE](LICENSE) file for full details. diff --git a/GUIDE.md b/GUIDE.md index 9456e5d..cd96a8a 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -19,38 +19,59 @@ ## 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. +**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 texte et checklists** avec couleurs personnalisees (10 themes pastel) +**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** via IA -- **Suggestions de titre** par IA -- **Systeme de rappels** avec notifications +- **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 -- **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) +- **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/tldraw) +- **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, React 19, TypeScript, Tailwind CSS 4 | -| UI | shadcn/ui, Lucide React | +| 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 | +| Base de donnees | PostgreSQL 16 via Prisma ORM 5.22 | | Authentification | NextAuth.js v5 | -| IA | Vercel AI SDK (OpenAI, Ollama, custom) | -| MCP | @modelcontextprotocol/sdk | +| IA | Vercel AI SDK (OpenAI, Ollama, Custom OpenAI-compatible) | +| MCP | @modelcontextprotocol/sdk v3.1 | | Email | Nodemailer (SMTP) ou Resend | +| Canvas | Excalidraw / tldraw | | Docker | Docker Compose (postgres + memento-note + mcp-server + ollama) | --- @@ -61,44 +82,55 @@ 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/ # Providers IA (factory pattern) +│ │ ├── 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 -│ │ └── config.ts # Config depuis DB +│ │ ├── mail.ts # Envoi d'emails (SMTP + Resend) +│ │ ├── config.ts # Config depuis DB (SystemConfig) +│ │ └── i18n/ # Detection langue + provider │ ├── prisma/ # Schema + migrations PostgreSQL -│ ├── locales/ # Fichiers i18n (fr.json, en.json) -│ ├── Dockerfile # Build multi-stage (node:22-bullseye) +│ ├── 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 +├── mcp-server/ # Serveur MCP (37 outils) │ ├── index.js # Mode stdio (Claude Desktop) -│ ├── index-sse.js # Mode SSE/HTTP (N8N, remote) -│ ├── tools.js # Definitions des outils MCP +│ ├── 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 -├── 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) - ↓ +Navigateur -> Next.js App Router + |-- Server Components (lecture) + |-- Server Actions (ecriture) + `-- API Routes (REST) + | Prisma ORM - ↓ + | PostgreSQL 16 - ↑ - MCP Server (stdio ou SSE) - ↑ + ^ + MCP Server (stdio ou HTTP Streamable) + ^ Claude Desktop / N8N / Client MCP ``` @@ -190,7 +222,7 @@ docker exec memento-ollama ollama pull embeddinggemma |---------|------|-------------| | memento-note | 3000 | Application web | | PostgreSQL | 5432 | Base de donnees | -| MCP Server | 3001 | SSE mode uniquement | +| MCP Server | 3001 | Mode HTTP Streamable | | Ollama | 11434 | IA locale (optionnel) | ### Reverse Proxy (Nginx) @@ -286,6 +318,13 @@ 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 : @@ -301,21 +340,76 @@ Les providers IA peuvent aussi etre configures depuis l'interface : ## Serveur MCP -Le serveur MCP (Model Context Protocol) permet aux agents IA d'interagir avec vos notes via un protocole standardise. +Le serveur MCP (Model Context Protocol, v3.1) permet aux agents IA d'interagir avec vos notes via un protocole standardise. -### Outils disponibles (9 outils) +### Outils disponibles (37 outils) + +**Notes (12) :** | Outil | Description | |-------|-------------| | `create_note` | Creer une nouvelle note | -| `get_notes` | Recuperer toutes les notes | +| `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 | -| `get_labels` | Lister les labels | +| `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) @@ -333,9 +427,9 @@ Communication via stdin/stdout, ideal pour les clients locaux. } ``` -### Mode SSE (N8N, HTTP) +### Mode HTTP Streamable (N8N, remote) -Communication via HTTP Server-Sent Events, accessible sur le reseau. +Communication via HTTP Streamable (remplace l'ancien SSE), accessible sur le reseau. ```bash # .env.docker @@ -345,20 +439,20 @@ MCP_PORT="3001" Le serveur sera accessible sur `http://localhost:3001`. -#### Endpoints SSE +#### Endpoints HTTP | Endpoint | Methode | Description | |----------|---------|-------------| | `/` | GET | Health check | -| `/sse` | GET/POST | Endpoint MCP principal | -| `/message` | POST | Envoi de messages | +| `/mcp` | GET/POST | Endpoint MCP principal (Streamable HTTP) | +| `/sse` | GET/POST | Legacy (redirige vers `/mcp`) | | `/sessions` | GET | Sessions actives | #### Verification ```bash curl http://localhost:3001/ -# {"name":"Memento MCP SSE Server","version":"1.0.0","status":"running"} +# {"name":"Memento MCP Server","version":"3.1.0","status":"running",...} ``` ### Configuration MCP avancee @@ -380,7 +474,7 @@ APP_BASE_URL="http://localhost:3000" # URL de l'app pour les liens 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` +3. Configurer l'endpoint : `http://memento-mcp:3001/mcp` (Docker) ou `http://VOTRE_IP:3001/mcp` ### Workflows preconfigures @@ -391,10 +485,10 @@ Le fichier `n8n-memento-workflow.json` contient un workflow pret a l'emploi pour ### Exemples d'utilisation -#### Creer une note via curl (SSE mode) +#### Creer une note via curl ```bash -curl -X POST http://localhost:3001/sse \ +curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", @@ -413,7 +507,7 @@ curl -X POST http://localhost:3001/sse \ #### Lister les outils disponibles ```bash -curl -X POST http://localhost:3001/sse \ +curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", @@ -427,7 +521,7 @@ curl -X POST http://localhost:3001/sse \ ## Configuration email -L'email est necessaire pour la reinitialisation de mot de passe et les rappels. +L'email est necessaire pour la reinitialisation de mot de passe et les rappels. Deux providers sont supportes. ### Option 1 : SMTP @@ -454,7 +548,11 @@ SMTP_FROM="noreply@votre-domaine.com" RESEND_API_KEY="re_votre-cle" ``` -Les parametres `SMTP_SECURE` et `SMTP_IGNORE_CERT` sont configurables depuis le panneau admin. +### 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). --- @@ -472,6 +570,16 @@ Accessibles uniquement par le premier utilisateur inscrit (ou les utilisateurs a 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` @@ -523,14 +631,14 @@ Accessibles uniquement par le premier utilisateur inscrit (ou les utilisateurs a | Variable | Defaut | Description | |----------|--------|-------------| -| `AI_PROVIDER_EMBEDDING` | - | Provider pour embeddings | +| `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 | Provider pour chat | +| `AI_PROVIDER_CHAT` | fallback Tags->Embedding | Provider pour chat | | `AI_MODEL_CHAT` | fallback Tags | Modele pour chat | #### IA - OpenAI @@ -557,7 +665,7 @@ Accessibles uniquement par le premier utilisateur inscrit (ou les utilisateurs a | Variable | Defaut | Description | |----------|--------|-------------| | `MCP_MODE` | `stdio` | Mode (`stdio` ou `sse`) | -| `MCP_PORT` | `3001` | Port 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 |