Momento/README.md

# Memento

A smart, AI-powered note-taking app. Like Google Keep, but with notebooks, semantic search, AI agents, and a built-in MCP server.

**[Lire en francais / Read in French](README.fr.md)** | **[Full documentation](GUIDE.en.md)**

---

## Features

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

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

**Integrations**
- MCP Server with **22 tools** - connect Claude Desktop, N8N, or any MCP client
- REST API for custom integrations
- RSS feed support
- Canvas/Lab whiteboard (Excalidraw)

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

---

## Quick Start

### Docker (recommended)

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

---

## AI Providers

Memento supports three AI providers, configurable independently for tags, embeddings, and chat:

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

Example for Ollama:
```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"
```

All AI settings can also be configured from the admin panel at `/admin/settings`.

---

## MCP Server

Connect AI agents to your notes via the Model Context Protocol.

```json
// claude_desktop_config.json
{
  "mcpServers": {
    "memento": {
      "command": "docker",
      "args": ["exec", "-i", "memento-mcp", "node", "index.js"]
    }
  }
}
```

**22 tools available** - notes CRUD, notebooks, labels, reminders, search, export/import. Each API key is scoped to a user so only their notes are accessible.

For N8N or HTTP clients, use Streamable HTTP mode: `http://localhost:3001/mcp` with `x-api-key` header auth.

---

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

For the complete installation, deployment, and configuration guide, see **[GUIDE.en.md](GUIDE.en.md)**.

---

## 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 (22 tools)
│   ├── index.js              # stdio mode
│   ├── index-sse.js          # HTTP Streamable mode
│   ├── tools.js              # Tool definitions
│   ├── auth.js               # API key authentication
│   └── 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.