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)
- **RSS feeds** - RSS feed integration
- **MCP Server** - 22 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 |
| Docker | Docker Compose (postgres + memento-note + mcp-server + ollama) |

---

## Architecture

```
Memento/
├── 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 (22 tools)
│   ├── index.js                 # stdio mode (Claude Desktop)
│   ├── index-sse.js             # HTTP Streamable mode (N8N, remote)
│   ├── tools.js                 # Definitions of the 22 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

### Quick Setup (interactive script)

```bash
git clone https://github.com/votre-user/Memento.git
cd Memento

# macOS / Linux
./scripts/deploy-local.sh

# Windows PowerShell
.\scripts\deploy-local.ps1
```

The script will:
1. Check that Node.js, npm, and PostgreSQL are installed
2. Ask for configuration (database, admin email, AI provider, etc.)
3. Generate `.env` with auto-generated secrets
4. Install dependencies and run database migrations

### Manual Steps

```bash
# 1. Clone the repository
git clone https://github.com/votre-user/Memento.git
cd Memento/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, ADMIN_EMAIL, 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. Register an account using the email you set in `ADMIN_EMAIL`
2. That account automatically gets the **ADMIN** role
3. Access the admin panel: `http://localhost:3000/admin/settings`

---

## Docker Deployment

### Quick Setup (interactive script)

```bash
git clone https://github.com/votre-user/Memento.git
cd Memento

# macOS / Linux
./scripts/deploy-docker.sh

# Windows PowerShell
.\scripts\deploy-docker.ps1
```

The script will:
1. Check Docker and Docker Compose are installed
2. Ask for configuration (URL, admin email, PostgreSQL, AI provider, MCP, email, Ollama, web search)
3. Auto-generate `NEXTAUTH_SECRET` and `POSTGRES_PASSWORD`
4. Build and start all containers
5. Run database migrations

**Deploy script options:**

| Command | Description |
|---------|-------------|
| `./scripts/deploy-docker.sh` | Full setup (env + build + deploy) |
| `./scripts/deploy-docker.sh --env-only` | Generate `.env.docker` only |
| `./scripts/deploy-docker.sh --build` | Build + deploy (requires existing `.env.docker`) |
| `./scripts/deploy-docker.sh --stop` | Stop all containers |
| `./scripts/deploy-docker.sh --logs` | Show container logs |

### Manual Setup

```bash
# 1. Clone the repository
git clone https://github.com/votre-user/Memento.git
cd Memento

# 2. Configure the environment
cp .env.docker.example .env.docker
nano .env.docker
# Modify NEXTAUTH_URL, NEXTAUTH_SECRET, and ADMIN_EMAIL (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` |
| `ADMIN_EMAIL` | Email that automatically gets ADMIN role on registration |

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

---

## AI Agents and External Tools

Memento includes a configurable AI agent system that can perform automated actions using external tools.

### Agent Types

| Type | Description | Default Tools |
|------|-------------|---------------|
| **Scraper** | Scrapes web pages and creates notes | `web_scrape`, `note_create` |
| **Researcher** | In-depth web research + synthesis | `web_search`, `web_scrape`, `note_search`, `note_create` |
| **Monitor** | Watches a notebook and analyzes notes | `note_search`, `note_read`, `note_create` |
| **Custom** | Free-form agent with custom instructions | configurable |

### Available Tools

| Tool | External | Description | Required Config |
|------|----------|-------------|-----------------|
| `web_search` | Yes | Web search (SearXNG or Brave) | SearXNG URL or Brave API key |
| `web_scrape` | Yes | Scrape a web page to Markdown (Jina Reader) | Jina key (optional) |
| `url_fetch` | No | Fetch JSON/CSV/text content from a URL | None |
| `note_search` | No | Keyword search in user's notes | None |
| `note_read` | No | Read a specific note by ID | None |
| `note_create` | No | Create a new note | None |
| `memory_search` | No | Search past agent execution history | None |

### Web Search - SearXNG (recommended)

SearXNG is an open-source, self-hosted metasearch engine. It is the default web search provider.

**Install SearXNG:**

```bash
# Via Docker
docker run -d --name searxng \
  -p 8080:8080 \
  -e SEARXNG_BASE_URL=http://localhost:8080 \
  --restart unless-stopped \
  searxng/searxng:latest
```

**Configure in Memento:**

1. Go to `/admin/settings`
2. Section "Tools"
3. Web Search Provider: select `SearXNG (Self-hosted)`
4. SearXNG URL: `http://localhost:8080` (or your instance URL)
5. Save

**In Docker (shared network):**

If SearXNG and Memento are on the same Docker network, use the service name:
```
http://searxng:8080
```

### Web Search - Brave Search (alternative)

Brave Search is a paid API alternative to SearXNG.

1. Create an account at [brave.com/search/api](https://brave.com/search/api/)
2. Get an API key
3. In `/admin/settings` > Tools: select `Brave Search API` and enter the key

Both providers can be used simultaneously by selecting `Both`.

### Web Scraping - Jina Reader (optional)

The `web_scrape` tool uses [Jina Reader](https://jina.ai/reader/) to convert web pages to Markdown. It works without an API key (rate-limited), or with a key for higher limits.

1. Create an account at [jina.ai](https://jina.ai/)
2. Get an API key
3. In `/admin/settings` > Tools: enter the Jina key

### Using Agents

1. Go to `/agents`
2. Click "New agent" or choose a template
3. Configure:
   - **Name and description**
   - **Type** (Scraper, Researcher, Monitor, Custom)
   - **Instructions** (system prompt)
   - **Tools** (select active tools)
   - **Frequency** (manual, hourly, daily, weekly, monthly)
   - **Target notebook** (where to save results)
   - **Source URLs** (for scrapers)
4. Save and run

Agents are also available in **AI Chat**: when web search is enabled, the chat automatically uses `web_search` and `web_scrape` tools.

---

## MCP Server

The MCP server (Model Context Protocol, v3.1) allows AI agents to interact with your notes via a standardized protocol.

### Available Tools (22 tools)

**Notes (11):**

| 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 |
| `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 |

**Reminders (1):**

| Tool | Description |
|------|-------------|
| `get_due_reminders` | Retrieve due reminders |

### 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, accessible over the network. API key authentication is enabled by default in Docker.

API keys are generated from **Settings > MCP** in the Memento web UI.

```bash
# docker-compose.yml (pre-configured)
MCP_MODE=sse
MCP_REQUIRE_AUTH=true
```

The server will be accessible at `http://localhost:3001/mcp`.

#### 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=true       # API key authentication
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`
4. Add **Header Auth**: `x-api-key` = your API key (generated from Settings > 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 users with the admin role.

The **first user who registers with the email set in `ADMIN_EMAIL`** automatically gets the ADMIN role. Make sure to set this variable in your `.env` or `.env.docker` before deploying.

**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 |
| `ADMIN_EMAIL` | - | Email that automatically gets ADMIN role on registration |

#### Registration & Admin

| Variable | Default | Description |
|----------|---------|-------------|
| `ALLOW_REGISTRATION` | `true` | Allow public registration |
| `ADMIN_EMAIL` | - | Email that gets ADMIN role on registration |

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

### Deploy Scripts

```bash
# Docker deployment (macOS / Linux)
./scripts/deploy-docker.sh              # Full setup (env + build + deploy)
./scripts/deploy-docker.sh --env-only   # Generate .env.docker interactively
./scripts/deploy-docker.sh --build      # Build + deploy (needs existing .env.docker)
./scripts/deploy-docker.sh --stop       # Stop all containers
./scripts/deploy-docker.sh --logs       # Show container logs

# Local deployment (macOS / Linux)
./scripts/deploy-local.sh               # Full setup (env + install + migrate)
./scripts/deploy-local.sh --env-only    # Generate .env interactively
./scripts/deploy-local.sh --start       # Start app (dev or prod mode)
./scripts/deploy-local.sh --migrate     # Run database migrations
./scripts/deploy-local.sh --install     # Install npm dependencies

# Windows PowerShell
.\scripts\deploy-docker.ps1             # Full Docker setup
.\scripts\deploy-docker.ps1 -EnvOnly    # Generate .env.docker only
.\scripts\deploy-docker.ps1 -Build      # Build + deploy
.\scripts\deploy-docker.ps1 -Stop       # Stop containers
.\scripts\deploy-docker.ps1 -Logs       # Show logs

.\scripts\deploy-local.ps1              # Full local setup
.\scripts\deploy-local.ps1 -EnvOnly     # Generate .env only
.\scripts\deploy-local.ps1 -Start       # Start app
.\scripts\deploy-local.ps1 -Migrate     # Run migrations
.\scripts\deploy-local.ps1 -Install     # Install dependencies
```

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

The older `memento-note/deploy.sh` script is still available for the standalone Docker Compose setup:

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