diff --git a/GUIDE.en.md b/GUIDE.en.md index 3eb4300..9c30f2e 100644 --- a/GUIDE.en.md +++ b/GUIDE.en.md @@ -338,6 +338,97 @@ AI providers can also be configured from the interface: --- +## 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. diff --git a/GUIDE.md b/GUIDE.md index 406ce1b..07d2de4 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -7,13 +7,14 @@ 3. [Installation locale](#installation-locale) 4. [Deploiement Docker](#deploiement-docker) 5. [Configuration des providers IA](#configuration-des-providers-ia) -6. [Serveur MCP (Model Context Protocol)](#serveur-mcp) -7. [Integrations N8N](#integrations-n8n) -8. [Configuration email (SMTP)](#configuration-email) -9. [Administration](#administration) -10. [Reference des variables d'environnement](#reference-des-variables-denvironnement) -11. [Commandes utiles](#commandes-utiles) -12. [Resolution des problemes](#resolution-des-problemes) +6. [Agents IA et Outils externes](#agents-ia-et-outils-externes) +7. [Serveur MCP (Model Context Protocol)](#serveur-mcp) +8. [Integrations N8N](#integrations-n8n) +9. [Configuration email (SMTP)](#configuration-email) +10. [Administration](#administration) +11. [Reference des variables d'environnement](#reference-des-variables-denvironnement) +12. [Commandes utiles](#commandes-utiles) +13. [Resolution des problemes](#resolution-des-problemes) --- @@ -338,6 +339,97 @@ Les providers IA peuvent aussi etre configures depuis l'interface : --- +## Agents IA et Outils externes + +Memento inclut un systeme d'agents IA configurables qui peuvent executer des actions automatisees en utilisant des outils externes. + +### Types d'agents + +| Type | Description | Outils par defaut | +|------|-------------|-------------------| +| **Scraper** | Scrape des pages web et cree des notes | `web_scrape`, `note_create` | +| **Researcher** | Recherche web approfondie + synthese | `web_search`, `web_scrape`, `note_search`, `note_create` | +| **Monitor** | Surveille un notebook et analyse les notes | `note_search`, `note_read`, `note_create` | +| **Custom** | Agent libre avec instructions personnalisees | configurable | + +### Outils disponibles + +| Outil | Externe | Description | Configuration requise | +|-------|---------|-------------|----------------------| +| `web_search` | Oui | Recherche web (SearXNG ou Brave) | URL SearXNG ou cle Brave | +| `web_scrape` | Oui | Scrape une page web en Markdown (Jina Reader) | Cle Jina (optionnel) | +| `url_fetch` | Non | Recupere du contenu JSON/CSV/texte | Aucune | +| `note_search` | Non | Recherche par mots-cles dans les notes | Aucune | +| `note_read` | Non | Lire une note par ID | Aucune | +| `note_create` | Non | Creer une nouvelle note | Aucune | +| `memory_search` | Non | Rechercher dans l'historique des executions | Aucune | + +### Recherche web - SearXNG (recommande) + +SearXNG est un moteur de metarecherche open-source et auto-hberge. C'est le provider par defaut pour la recherche web. + +**Installation de 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 +``` + +**Configuration dans Memento :** + +1. Aller dans `/admin/settings` +2. Section "Tools" +3. Web Search Provider : selectionner `SearXNG (Self-hosted)` +4. SearXNG URL : `http://localhost:8080` (ou l'URL de votre instance) +5. Sauvegarder + +**En Docker (reseau partage) :** + +Si SearXNG et Memento sont dans le meme reseau Docker, utiliser le nom du service : +``` +http://searxng:8080 +``` + +### Recherche web - Brave Search (alternative) + +Brave Search est une API payante comme alternative a SearXNG. + +1. Creer un compte sur [brave.com/search/api](https://brave.com/search/api/) +2. Obtenir une cle API +3. Dans `/admin/settings` > Tools : selectionner `Brave Search API` et entrer la cle + +Les deux providers peuvent etre utilises en meme temps en selectionnant `Both`. + +### Scraping web - Jina Reader (optionnel) + +L'outil `web_scrape` utilise [Jina Reader](https://jina.ai/reader/) pour convertir des pages web en Markdown. Fonctionne sans cle API (avec limites de debit), ou avec une cle pour des limites plus elevees. + +1. Creer un compte sur [jina.ai](https://jina.ai/) +2. Obtenir une cle API +3. Dans `/admin/settings` > Tools : entrer la cle Jina + +### Utilisation des agents + +1. Aller sur `/agents` +2. Cliquer sur "Nouvel agent" ou choisir un template +3. Configurer : + - **Nom et description** + - **Type** (Scraper, Researcher, Monitor, Custom) + - **Instructions** (prompt systeme) + - **Outils** (selectionner les outils actifs) + - **Frequence** (manuel, hourly, daily, weekly, monthly) + - **Notebook cible** (ou sauvegarder les resultats) + - **URLs sources** (pour les scrapers) +4. Sauvegarder et executer + +Les agents sont aussi disponibles dans le **Chat IA** : si la recherche web est activee, le chat utilise automatiquement les outils `web_search` et `web_scrape`. + +--- + ## Serveur MCP Le serveur MCP (Model Context Protocol, v3.1) permet aux agents IA d'interagir avec vos notes via un protocole standardise.