Momento/GUIDE.en.md

Memento - Complete User Guide

Table of Contents

1. Overview
2. Architecture
3. Local Installation
4. Docker Deployment
5. AI Provider Configuration
6. MCP Server (Model Context Protocol)
7. N8N Integrations
8. Email Configuration (SMTP)
9. Administration
10. Environment Variables Reference
11. Useful Commands
12. 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

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

Steps

# 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

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

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

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)

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

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)

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

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

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

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

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

# 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

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

Advanced MCP Configuration

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

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

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

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

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

# 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

# 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

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)

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

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

# 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 file for full details.