Momento/GUIDE.en.md

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