docs: rewrite README.md

- Accurate feature list matching actual codebase (37 MCP tools, 15 languages, AI agents, workflows, canvas, etc.) - Correct tech stack (PostgreSQL, not SQLite) - Correct license (Apache 2.0 + Commons Clause, not MIT) - Clean structure: Features, Quick Start, AI Providers, MCP, Tech Stack, Docs, Contributing, Support, License - Link to French documentation (GUIDE.md)
2026-04-20 23:21:33 +02:00
parent 48c490cd79
commit 8e65210e63
1 changed files with 178 additions and 402 deletions
--- a/README.md
+++ b/README.md
@@ -1,432 +1,208 @@
-# Memento - Your Digital Notepad ☕
+# Memento

-A beautiful and functional note-taking app inspired by Google Keep, built with Next.js 16, TypeScript, Tailwind CSS 4, and Prisma.
+A smart, AI-powered note-taking app. Like Google Keep, but with notebooks, semantic search, AI agents, and a built-in MCP server.

-## 🌟 Support Memento
-
-**Memento is 100% free and open-source!** If you find it useful, please consider supporting its development:
-
- **[☕ Buy me a coffee on Ko-fi](https://ko-fi.com/yourusername)** - One-time or monthly support
- **[💚 Sponsor on GitHub](https://github.com/sponsors/yourusername)** - Recurring support
- **[⭐ Star on GitHub](https://github.com/yourusername/memento)** - Free way to show support
-
-Your support helps:
- ☕ Keep the developer fueled with coffee
- 🐛 Cover hosting and server costs (~$50/month)
- ✨ Fund development of new features
- 📚 Improve documentation
- 🌍 Keep Memento 100% open-source
+**[Documentation en francais](GUIDE.md)**

 ---

-## 🚀 Project Location
+## Features

-The complete application is in the `memento-note/` directory.
+**Notes & Organization**
+- Text, checklist, and Markdown notes (with LaTeX/KaTeX)
+- Notebooks with contextual labels
+- Responsive masonry grid with drag-and-drop
+- Image upload, note sharing, archive, and trash
+- 10 pastel color themes + dark mode

-## ✅ Completed Features
+**AI & Automation**
+- Semantic search powered by embeddings
+- Auto-generated tags and title suggestions
+- Configurable AI agents with custom instructions
+- Persistent AI chat conversations
+- Memory Echo - discover hidden connections between notes
+- Batch auto-organization and smart labels
+- AI-generated notebook summaries
+- Visual workflow builder

-### Core Functionality
- ✅ Create, read, update, delete notes
- ✅ Text notes and checklist notes
- ✅ Pin/unpin notes
- ✅ Archive/unarchive notes
- ✅ Real-time search across all notes
- ✅ Color customization (10 soft pastel themes)
- ✅ Label management
- ✅ Responsive masonry grid layout
- ✅ Drag-and-drop note reordering
- ✅ **Image upload with original size preservation**
+**Integrations**
+- MCP Server with **37 tools** - connect Claude Desktop, N8N, or any MCP client
+- REST API for custom integrations
+- RSS feed support
+- Canvas/Lab whiteboard (Excalidraw)

-### UI/UX Features
- ✅ Expandable note input (Google Keep style)
- ✅ Modal note editor with full editing (`!max-w-[min(95vw,1600px)]`)
- ✅ **Images display at original dimensions** (no cropping, `h-auto` without `w-full`)
- ✅ Hover effects and smooth animations
- ✅ **Masonry layout with CSS columns** (responsive: 1-5 columns)
- ✅ **Soft pastel color themes** (bg-red-50, bg-blue-50, etc.)
- ✅ Dark mode with system preference
- ✅ Mobile responsive design
- ✅ Icon-based navigation with 9 toolbar icons
- ✅ Toast notifications (via shadcn)
+**Platform**
+- 15 languages (EN, FR, AR, DE, ES, FA, HI, IT, JA, KO, NL, PL, PT, RU, ZH)
+- Progressive Web App (PWA)
+- Reminder system with recurrence
+- Data export/import (JSON)
+- Admin panel for AI providers, SMTP, and settings

-### Integration Features
- ✅ **REST API** (4 endpoints: GET, POST, PUT, DELETE)
-  - `/api/notes` - List all notes
-  - `/api/notes` - Create new note
-  - `/api/notes/[id]` - Update note
-  - `/api/notes/[id]` - Delete note
- ✅ **MCP Server** (Model Context Protocol) with 9 tools:
-  - `getNotes` - Fetch all notes
-  - `createNote` - Create new note
-  - `updateNote` - Update existing note
-  - `deleteNote` - Delete note
-  - `searchNotes` - Search notes by query
-  - `getNoteById` - Get specific note
-  - `archiveNote` - Archive/unarchive note
-  - `pinNote` - Pin/unpin note
-  - `addLabel` - Add label to note
+---

-### Technical Features
- ✅ Next.js 16 with App Router & Turbopack
- ✅ Server Actions for mutations
- ✅ TypeScript throughout
- ✅ Tailwind CSS 4
- ✅ shadcn/ui components (11 components)
- ✅ Prisma ORM 5.22.0 with SQLite
- ✅ Type-safe database operations
- ✅ **Base64 image encoding** (FileReader.readAsDataURL)
- ✅ **@modelcontextprotocol/sdk** v1.0.4
+## Quick Start

-## 🏃 Quick Start
+### Docker (recommended)

 ```bash
-cd memento-note
-npm install
-npx prisma generate
+git clone https://github.com/yourusername/Momento.git
+cd Momento
+
+cp .env.docker.example .env.docker
+
+# Edit these two required values:
+# NEXTAUTH_URL="http://YOUR_SERVER_IP:3000"
+# NEXTAUTH_SECRET="generate-with: openssl rand -base64 32"
+
+docker compose up -d
+```
+
+Open `http://localhost:3000` - the first registered user becomes admin.
+
+### Local Development
+
+```bash
+git clone https://github.com/yourusername/Momento.git
+cd Momento/memento-note
+
+cp .env.example .env
+# Edit .env with your DATABASE_URL, NEXTAUTH_SECRET, etc.
+
+npm install --legacy-peer-deps
 npx prisma migrate dev
 npm run dev
 ```

-Then open http://localhost:3000
+---

-## 📱 Application Features
+## AI Providers

-### 1. Note Creation
- Click the input field to expand
- Add title and content
- **Upload images** (displayed at original size)
- Switch to checklist mode with one click
- Add labels and choose from 10 soft pastel colors
+Memento supports three AI providers, configurable independently for tags, embeddings, and chat:

-### 2. Note Management
- **Edit**: Click any note to open the editor (max-width: 95vw or 1600px)
- **Pin**: Click pin icon to keep notes at top
- **Archive**: Move notes to archive
- **Delete**: Remove notes permanently
- **Color**: Choose from 10 beautiful pastel colors
- **Labels**: Add multiple labels
- **Images**: Upload images that preserve original dimensions
+| Provider | Type | Setup |
+|----------|------|-------|
+| **Ollama** | Local, free | `docker compose --profile ollama up -d` |
+| **OpenAI** | Cloud, paid | Set `OPENAI_API_KEY` |
+| **Custom** | OpenRouter, Groq, Together, Mistral... | Set `CUSTOM_OPENAI_API_KEY` + `CUSTOM_OPENAI_BASE_URL` |

-### 3. Checklist Notes
- Create todo lists
- Check/uncheck items
- Add/remove items dynamically
- Strike-through completed items
-
-### 4. Search & Navigation
- Real-time search in header
- Search by title or content
- Navigate to Archive page
- Dark/light mode toggle
-
-### 5. API Integration
-Use the REST API to integrate with other services:
+Example for Ollama:
 ```bash
-# Get all notes
-curl http://localhost:3000/api/notes
-
-# Create a note
-curl -X POST http://localhost:3000/api/notes \
-  -H "Content-Type: application/json" \
-  -d '{"title":"API Note","content":"Created via API"}'
-
-# Update a note
-curl -X PUT http://localhost:3000/api/notes/1 \
-  -H "Content-Type: application/json" \
-  -d '{"title":"Updated","content":"Modified via API"}'
-
-# Delete a note
-curl -X DELETE http://localhost:3000/api/notes/1
+# .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"
 ```

-### 6. MCP Server for AI Agents
-Start the MCP server for integration with Claude, N8N, or other MCP clients:
-```bash
-cd memento-note
-npm run mcp
-```
-
-The MCP server exposes 9 tools for AI agents to interact with your notes:
- Create, read, update, and delete notes
- Search notes by content
- Manage pins, archives, and labels
- Perfect for N8N workflows, Claude Desktop, or custom integrations
-
-Example N8N workflow available in: `n8n-memento-workflow.json`
-
-## 🛠️ Tech Stack
-
- **Frontend**: Next.js 16, React, TypeScript, Tailwind CSS 4
- **UI Components**: shadcn/ui (11 components: Dialog, Tooltip, Badge, etc.)
- **Icons**: Lucide React (Bell, Image, UserPlus, Palette, Archive, etc.)
- **Backend**: Next.js Server Actions
- **Database**: Prisma ORM 5.22.0 + SQLite (upgradeable to PostgreSQL)
- **Styling**: Tailwind CSS 4 with soft pastel themes (bg-*-50)
- **Layout**: CSS columns for masonry grid (responsive 1-5 columns)
- **Images**: Base64 encoding, original size preservation
- **Integration**: REST API + MCP Server (@modelcontextprotocol/sdk v1.0.4)
-
-## 📂 Project Structure
-
-```
-memento-note/
-├── app/
-│   ├── actions/notes.ts       # Server actions (CRUD + images)
-│   ├── api/notes/             # REST API endpoints
-│   ├── archive/page.tsx       # Archive page
-│   ├── layout.tsx             # Root layout
-│   └── page.tsx               # Home page
-├── components/
-│   ├── ui/                    # shadcn components
-│   ├── header.tsx             # Navigation
-│   ├── note-card.tsx          # Note display (masonry, images)
-│   ├── note-editor.tsx        # Note editing (!max-w-[95vw])
-│   ├── note-input.tsx         # Note creation (image upload)
-│   └── note-grid.tsx          # Masonry layout
-├── lib/
-│   ├── types.ts               # TypeScript types (Note with images)
-│   └── utils.ts               # Utilities
-├── prisma/
-│   ├── schema.prisma          # Database schema (images String?)
-│   └── dev.db                 # SQLite database
-├── mcp/
-│   └── server.ts              # MCP server (9 tools)
-└── package.json               # Scripts: dev, build, start, mcp
-```
-│   ├── note-editor.tsx        # Edit modal
-│   ├── note-grid.tsx          # Grid layout
-│   └── note-input.tsx         # Note creation
-├── lib/
-│   ├── prisma.ts              # DB client
-│   ├── types.ts               # TypeScript types
-│   └── utils.ts               # Utilities
-└── prisma/
-    ├── schema.prisma          # Database schema
-    └── migrations/            # DB migrations
-```
-
-## 🎨 Color Themes
-
-The app includes 10 color themes:
- Default (White)
- Red
- Orange  
- Yellow
- Green
- Teal
- Blue
- Purple
- Pink
- Gray
-
-All themes support dark mode!
-
-## 🔧 Configuration
-
-### Database
-Currently uses SQLite. To switch to PostgreSQL:
-
-1. Edit `prisma/schema.prisma`:
-```prisma
-datasource db {
-  provider = "postgresql"
-}
-```
-
-2. Update `prisma.config.ts` with PostgreSQL URL
-3. Run: `npx prisma migrate dev`
-
-### Environment Variables
-Located in `.env`:
-```
-DATABASE_URL="file:./dev.db"
-```
-
-## 🚀 Deployment
-
-### 🐳 Docker Deployment (Recommended for Proxmox)
-
-Keep Notes includes complete Docker configuration for easy deployment on Proxmox or any Docker host.
-
-#### Quick Start
-
-```bash
-cd memento-note
-
-# Create environment file
-cat > .env << EOF
-NEXTAUTH_URL=http://localhost:3000
-NEXTAUTH_SECRET=$(openssl rand -base64 32)
-EOF
-
-# Build and start
-docker-compose build
-docker-compose up -d
-
-# Access at http://localhost:3000
-```
-
-#### Deployment Script
-
-We provide an automation script for common tasks:
-
-```bash
-chmod +x deploy.sh
-
-# Build image
-./deploy.sh build
-
-# Start containers
-./deploy.sh start
-
-# View logs
-./deploy.sh logs
-
-# Backup database
-./deploy.sh backup
-
-# Update application
-./deploy.sh update
-```
-
-#### Features
-
- ✅ **Multi-stage Docker build** for optimized image size
- ✅ **Persistent volumes** for database and uploads
- ✅ **Health checks** for automatic restart
- ✅ **Resource limits** for stable performance
- ✅ **Ollama support** for local AI models (optional)
- ✅ **Nginx reverse proxy** configuration included
- ✅ **Automated backups** with cron scripts
-
-#### Architecture
-
-```
-memento-note/
-├── Dockerfile                 # Multi-stage build
-├── docker-compose.yml         # Container orchestration
-├── .dockerignore              # Build optimization
-├── deploy.sh                  # Deployment automation
-└── DOCKER_DEPLOYMENT.md      # Complete guide
-```
-
-#### Supported Platforms
-
- **Proxmox VE** (LXC containers or VMs)
- **Docker hosts** (Linux, Windows, macOS)
- **Cloud providers** (AWS, GCP, Azure)
- **Kubernetes** (via Docker Compose)
-
-#### AI Features Setup
-
-**Option 1: OpenAI (Cloud)**
-```yaml
-# In .env or docker-compose.yml
-OPENAI_API_KEY=sk-your-key-here
-```
-
-**Option 2: Ollama (Local AI)**
-```bash
-# Uncomment ollama service in docker-compose.yml
-./deploy.sh start
-./deploy.sh ollama-pull granite4
-```
-
-#### Documentation
-
-See [DOCKER_DEPLOYMENT.md](memento-note/DOCKER_DEPLOYMENT.md) for:
- Complete Proxmox deployment guide
- SSL/HTTPS configuration with Let's Encrypt
- Database backup and restore procedures
- Performance tuning and resource recommendations
- Troubleshooting common issues
- Security best practices
-
-### ☁️ Vercel (Alternative)
-
-For serverless deployment:
-
-```bash
-cd memento-note
-npm run build
-vercel deploy
-```
-
-### 📦 Traditional Deployment
-
-For traditional VPS or bare metal:
-
-```bash
-cd memento-note
-npm install
-npx prisma generate
-npx prisma migrate deploy
-npm run build
-npm start
-```
-
-## 📝 Development Notes
-
-### Server Actions
-All CRUD operations use Next.js Server Actions:
- `createNote()` - Create new note
- `updateNote()` - Update existing note  
- `deleteNote()` - Delete note
- `getNotes()` - Fetch all notes
- `searchNotes()` - Search notes
- `togglePin()` - Pin/unpin
- `toggleArchive()` - Archive/unarchive
-
-### Type Safety
-Full TypeScript coverage with interfaces:
- `Note` - Main note type
- `CheckItem` - Checklist item
- `NoteColor` - Color themes
-
-### Responsive Design
- Mobile: Single column
- Tablet: 2 columns
- Desktop: 3-4 columns
- Auto-adjusts with window size
-
-## 🎯 Future Enhancements
-
-Possible additions:
- [x] User authentication (NextAuth.js) ✅ Already implemented!
- [ ] Real-time collaboration
- [x] Image uploads ✅ Already implemented!
- [ ] Rich text editor
- [ ] Note sharing
- [x] Reminders ✅ Already implemented!
- [ ] Export to PDF/Markdown
- [ ] Voice notes
- [ ] Drawing support
-
-## 🤝 Contributing
-
-We welcome contributions! Please feel free to:
-
- **Report bugs**: [Open an issue](https://github.com/yourusername/memento/issues)
- **Suggest features**: [Start a discussion](https://github.com/yourusername/memento/discussions)
- **Submit pull requests**: Fork and create a PR
- **Share feedback**: [Support page](/support)
-
-## ☕ Support Development
-
-Enjoying Memento? Consider supporting its development:
-
- **[Donate on Ko-fi](https://ko-fi.com/yourusername)** - Buy me a coffee ☕
- **[GitHub Sponsors](https://github.com/sponsors/yourusername)** - Monthly sponsorship 💚
- **[Star the repo](https://github.com/yourusername/memento)** - It's free! ⭐
-
-## 📄 License
-
-MIT License - feel free to use for personal or commercial projects!
+All AI settings can also be configured from the admin panel at `/admin/settings`.

 ---

-**Built with ❤️ and ☕ using Next.js 16, TypeScript, and Tailwind CSS 4**
+## MCP Server

-Server running at: http://localhost:3000
+Connect AI agents to your notes via the Model Context Protocol.

-**⭐ If you like Memento, please consider giving it a star on GitHub!**
+```json
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "memento": {
+      "command": "docker",
+      "args": ["exec", "-i", "memento-mcp", "node", "index.js"]
+    }
+  }
+}
+```
+
+**37 tools available** - notes CRUD, notebooks, labels, AI operations (tag generation, title suggestions, memory echo, batch organize), reminders, and API key management.
+
+For N8N or HTTP clients, use Streamable HTTP mode: `http://localhost:3001/mcp`
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js 16, React 19, TypeScript 5 |
+| Styling | Tailwind CSS 4, shadcn/ui |
+| Database | PostgreSQL 16, Prisma ORM 5 |
+| Auth | NextAuth.js v5 |
+| AI | Vercel AI SDK (OpenAI, Ollama, Custom) |
+| MCP | @modelcontextprotocol/sdk |
+| Email | Nodemailer (SMTP) / Resend |
+
+---
+
+## Documentation
+
+| File | Language | Content |
+|------|----------|---------|
+| [GUIDE.en.md](GUIDE.en.md) | English | Full installation, deployment, and configuration guide |
+| [GUIDE.md](GUIDE.md) | French | Guide complet d'installation, deploiement et configuration |
+
+---
+
+## Project Structure
+
+```
+Momento/
+├── docker-compose.yml        # Multi-container orchestration
+├── .env.docker.example       # Docker environment template
+├── memento-note/             # Next.js application
+│   ├── app/                  # App Router (pages, actions, API)
+│   ├── components/           # React UI components
+│   ├── lib/                  # Business logic (AI, DB, mail, i18n)
+│   ├── prisma/               # Schema + migrations
+│   ├── locales/              # 15 i18n JSON files
+│   └── Dockerfile            # Multi-stage build
+├── mcp-server/               # MCP server (37 tools)
+│   ├── index.js              # stdio mode
+│   ├── index-sse.js          # HTTP Streamable mode
+│   ├── tools.js              # Tool definitions
+│   └── Dockerfile            # Container build
+└── n8n-memento-workflow.json # Pre-configured N8N workflow
+```
+
+---
+
+## Environment Variables
+
+See [.env.docker.example](.env.docker.example) for the complete list. Key variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NEXTAUTH_URL` | Yes | Public URL of the app |
+| `NEXTAUTH_SECRET` | Yes | JWT secret (`openssl rand -base64 32`) |
+| `POSTGRES_PASSWORD` | Rec. | PostgreSQL password (default: `memento`) |
+| `AI_PROVIDER_TAGS` | No | AI provider for tags: `ollama`, `openai`, `custom` |
+| `OPENAI_API_KEY` | If OpenAI | Your OpenAI API key |
+
+---
+
+## Contributing
+
+Contributions are welcome!
+
+- **Bug reports**: [Open an issue](https://github.com/yourusername/Momento/issues)
+- **Feature ideas**: [Start a discussion](https://github.com/yourusername/Momento/discussions)
+- **Pull requests**: Fork, create a branch, and submit a PR
+
+---
+
+## Support
+
+If you find Memento useful, consider supporting its development:
+
+- **[Ko-fi](https://ko-fi.com/yourusername)** - One-time or monthly support
+- **[GitHub Sponsors](https://github.com/sponsors/yourusername)** - Recurring sponsorship
+- **Star the repo** - It's free and helps visibility
+
+---
+
+## License
+
+Apache License 2.0 with Commons Clause Restriction.
+
+Free for personal, educational, and non-commercial use. Commercial use requires written permission from the author. See [LICENSE](LICENSE) for details.