Mémoire persistante des agents IA : le serveur REST officiel de Mem0 extrait les faits des conversations avec le LLM, les stocke avec leur plongement dans PostgreSQL (pgvector) par utilisateur, agent ou exécution, et répond aux recherches sémantiques, mises à jour, historiques et suppressions. Les appels au LLM et aux plongements passent par la passerelle LiteLLM de la plateforme (compatible OpenAI) ; chaque appel est authentifié (clé d'administration, clés d'API des utilisateurs ou JWT) et aucune télémétrie ne quitte l'hôte.
Généré depuis catalog/services/mem0.yaml : ne pas modifier à la main.
Résumé
| |
|---|
| Version | 2.2.1 |
| Usage | installer et configurer, configurer et connecter |
| Couche | fonctionnelle (catalogue IA) |
| Catégorie | Mémoire IA |
| Sous-catégorie | Mémoire persistante des agents |
| Méthodes d'installation | python |
| Connexion externe | non |
| Réservé au bac à sable | non |
Licence
| |
|---|
| Identifiant SPDX | Apache-2.0 |
| Politique de licence | licence socle (MIT ou Apache-2.0) |
| Exception de licence | - |
| Remarque de licence | Les sources du serveur (server/ de l'archive v2.2.1, sha256 2d203947596fbbfeaf06e5311c087a6b837566528016013aff15ad2a8a4103c5) et sa LICENSE sont rendues depuis templates/mem0/server, identiques à l'archive sauf deux retouches de texte sans effet sur le comportement (un message de journal de main.py et les tirets de docstrings et d'un commentaire de telemetry.py : le catalogue refuse les marqueurs Jinja et les tirets dans les fichiers rendus) ; les dépendances Python sont sous licences OSI (MIT, BSD, Apache-2.0, ISC, MPL-2.0, LGPL-3.0-only pour psycopg, Unlicense, PSF-2.0). Le tableau de bord web de la version (Next.js) n'est pas livré : aucune image officielle versionnée n'existe et la méthode python ne peut pas le construire. Pas de méthode podman non plus : l'image Docker Hub mem0/mem0-api-server n'a aucune étiquette versionnée (une étiquette flottante du 2025-09-10, antérieure à la v2) et la documentation officielle ne cite aucune autre image. La mémoire en graphe (Neo4j) et spaCy ne sont pas installés : la liaison des entités et le score lexical lemmatisé restent inactifs. |
| Composant de la plateforme | mem0 |
Paquets et artefacts
Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.
| Type | Paquet | Version | Licence | Détails |
|---|
| paquet Python | mem0ai | 2.2.1 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | fastapi | 0.115.8 | MIT | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | uvicorn | 0.34.0 | BSD-3-Clause | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | pydantic[email] | 2.10.4 | MIT | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | python-dotenv | 1.2.2 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | psycopg[binary] | 3.3.7 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | psycopg-pool | 3.3.3 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | sqlalchemy | 2.1.6 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | alembic | 1.20.1 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | passlib[bcrypt] | 1.7.4 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | bcrypt | 4.0.1 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | python-jose[cryptography] | 3.5.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | cryptography | 50.0.2 | Apache-2.0 OR BSD-3-Clause | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | posthog | 7.82.2 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | slowapi | 0.1.10 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | openai | 3.42.1 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
| paquet Python | pixeltable-pgserver | 0.7.1 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12 |
Systèmes et architectures pris en charge
| Méthode | Systèmes d'exploitation | Architectures |
|---|
python | famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman) | x86_64, aarch64 (non restreintes par le descripteur) |
Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.
Prérequis
Hôte
- au moins 1024 Mo de mémoire (bloquant,
memory).
- au moins 1 CPU (bloquant,
cpu).
- au moins 2048 Mo libres pour
/var/lib/navin (bloquant, disk).
Réseau et ports
| Composant | Nom du port | Port | Ouvert dans le pare-feu de l'hôte |
|---|
mem0-server | api | 8720/tcp | oui |
mem0-server | api_local | 8720/tcp | non |
Services et connexions nécessaires
Détail et résolution : voir Dépendances.
Méthodes et modes d'installation
| Méthode | Défaut | Ce que la méthode utilise |
|---|
python | oui | un environnement virtuel Python qui contient les paquets Python du descripteur |
Composants
| Composant | Type | Méthodes d'installation | Ports |
|---|
Serveur REST Mem0 (mem0-server) | maître | python | 8720/tcp, 8720/tcp |
Purge du journal des requêtes (request-log-pruner) | travailleur | python | - |
request-log-pruner ne tourne que sur un hôte qui porte aussi mem0-server.
Serveur unique (single) (par défaut)
Un serveur Mem0 et sa purge du journal des requêtes.
Ce que le mode déploie :
| Composant | Placement |
|---|
mem0-server | min 1, max 1 |
request-log-pruner | min 1, max 1 |
Installer ce service
L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.
-
Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.
-
Choisissez le service. À l'étape Service, sélectionnez Mem0. La carte affiche la licence Apache-2.0 et les dépendances dont l'installation a besoin.
-
Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : single (par défaut). Chaque mode déploie les composants listés dans Méthodes et modes d'installation. Avec plusieurs composants, placez chacun sur ses hôtes dans Répartition des composants (Proposer un placement propose un placement qui respecte les cardinalités).
-
Liez les dépendances. À l'étape Liaisons, choisissez pour chaque dépendance (database, app, llm) Installer avec la plateforme ou Utiliser une connexion existante ; une dépendance facultative peut rester sur Aucune liaison.
-
Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.
-
Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.
-
Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services. Ouvrez le service et choisissez Lancer le test fonctionnel dans la carte Contrôles : Dans un espace dédié (user_id navin-smoke-<nonce>) : vérifie qu'un appel sans clé est refusé, stocke une mémoire (appel de plongement), interroge le LLM à travers le serveur, retrouve la mémoire par recherche sémantique, la met à jour, la relit, la supprime, vérifie que l'espace est vide, puis supprime l'espace quoi qu'il arrive.
Connecter un service existant
| |
|---|
| Schémas | https, http |
| Port par défaut | 8000 |
| Authentification | obligatoire |
| Contrôle de santé | /openapi.json |
| Méthode d'authentification | Champs | Description |
|---|
api_key | api_key | ADMIN_API_KEY du serveur ou clé d'API d'un utilisateur (m0sk_...), envoyée en X-API-Key. |
Documentation officielle : https://docs.mem0.ai/open-source/features/rest-api
Haute disponibilité
Topologie par mode
| Modes | Niveau le plus haut du catalogue | Répartition | Composant du quorum | Domaines de panne | Description |
|---|
single | autonome (standalone) | unique (single) | - | 1 | Un serveur : sa perte arrête l'API de mémoire jusqu'à son redémarrage ou sa restauration ; les mémoires restent dans PostgreSQL. |
Remarques
- Pas de mode répliqué : l'historique des mémoires et les messages récents servant de contexte d'extraction sont dans un fichier SQLite local (HISTORY_DB_PATH, mem0/memory/storage.py), les limites de débit des routes d'authentification sont comptées en mémoire par processus (slowapi) et les migrations s'appliquent à chaque démarrage. Deux serveurs derrière un répartiteur garderaient chacun un historique partiel.
- Les mémoires, leurs vecteurs, les utilisateurs et les clés sont dans PostgreSQL : avec le service PostgreSQL hautement disponible un hôte perdu est remplacé par une réinstallation et la restauration du fichier d'historique.
- Le serveur n'expose aucun point de métriques : l'observabilité utilise des sondes blackbox de /openapi.json et de /auth/setup-status.
Paramètres de configuration
Réseau
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Port de l'API (port) | port | 8720 | - | non | non | oui | Port de l'API REST (8000 en amont, déplacé hors du port de vLLM et d'Opik). |
Exposition de l'API (listen_scope) | enum | network | network, local | non | non | oui | network : l'API écoute sur la seule adresse privée de l'hôte (jamais sur toutes les adresses) et le pare-feu de l'hôte l'ouvre aux consommateurs ; local : boucle locale uniquement, pour des consommateurs du même hôte. Elle n'est jamais publiée par une passerelle. |
TLS (tls_enabled) | bool | false | - | non | non | oui | Servir l'API en TLS (uvicorn --ssl-certfile et --ssl-keyfile) avec le certificat que le Manager émet pour l'hôte ; la liaison des consommateurs passe alors en https. |
Requêtes simultanées (limit_concurrency) | int | 64 | min 4, max 1024 | non | non | oui | Requêtes servies en même temps (uvicorn --limit-concurrency) ; au-delà, le serveur répond 503. |
Modèles
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
LLM (llm_model) | string | qwen-local | ^[A-Za-z0-9._:/@-]{1,128}$ | non | non | oui | Nom du modèle de la passerelle utilisé pour l'extraction des faits (mode JSON) ; par défaut qwen-local, le nom servi par défaut d'un moteur vLLM lié à LiteLLM (la passerelle n'a pas d'entrée par défaut, audit P5B-010). |
Température du LLM (llm_temperature) | float | 0.2 | min 0, max 2 | non | non | oui | Température des appels d'extraction (0,2 en amont). |
Modèle de plongement (embedder_model) | string | bge-m3 | ^[A-Za-z0-9._:/@-]{1,128}$ | non | non | oui | Nom du modèle de plongement de la passerelle ; par défaut bge-m3, servi par un moteur vLLM en mode plongement lié à LiteLLM. |
Taille des vecteurs (embedding_dims) | int | 1024 | min 64, max 16000 | non | non | oui | Taille des vecteurs que renvoie le modèle de plongement (1024 pour bge-m3) : la colonne vector de la collection est créée avec elle. La changer sur une collection qui contient des mémoires demande un nouveau nom de collection. |
Envoyer la taille des vecteurs (embedding_send_dimensions) | bool | false | - | non | non | oui | Envoyer le paramètre dimensions dans les appels de plongement (modèles à plongements Matryoshka uniquement : vLLM le refuse pour les autres modèles). (avancé) |
Clé de la passerelle (llm_api_key) | password | (vide) | - | non | oui | non | Clé virtuelle LiteLLM de Mem0 (sk-...) ; vide, la clé maîtresse de la passerelle liée est utilisée. |
Stockage et rétention
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Collection (collection_name) | string | memories | ^[a-z_][a-z0-9_]{0,62}$ | non | non | oui | Table des mémoires dans la base des mémoires (POSTGRES_COLLECTION_ NAME) ; les entités utilisent la table de même nom suffixée par _entities. |
Rétention du journal des requêtes (request_log_retention_days) | int | 30 | min 1, max 3650, days | non | non | oui | Les lignes du journal des requêtes plus anciennes sont supprimées par le composant request-log-pruner (prune_request_logs.py officiel). |
Intervalle de purge (prune_interval_hours) | int | 24 | min 1, max 168, hours | non | non | oui | Heures entre deux purges du journal des requêtes. |
Sécurité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Clé d'API d'administration (admin_api_key) | password | généré | - | non | oui | non | ADMIN_API_KEY du serveur (en-tête X-API-Key, rôle admin), donnée aux consommateurs comme secret api_key du point d'accès api ; renouvelée par une nouvelle valeur et un redémarrage. |
Secret JWT (jwt_secret) | password | généré | - | non | oui | non | JWT_SECRET qui signe les jetons d'accès et de rafraîchissement des utilisateurs ; le changer ferme toutes les sessions. |
Courriel de l'administrateur (admin_email) | string | mem0-admin@navin.internal | ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$ | non | non | non | Identifiant du premier administrateur, créé par le lanceur avant que l'API écoute (la route publique d'inscription est alors fermée). |
Mot de passe administrateur (admin_password) | password | généré | - | non | oui | non | Mot de passe initial du premier administrateur (empreinte bcrypt dans la base applicative) ; une fois le compte créé il ne se change que dans le serveur (POST /auth/change-password). |
Observabilité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Niveau de journalisation (log_level) | enum | info | critical, error, warning, info, debug | non | non | non | Verbosité d'uvicorn. |
Dépendances
Pour chaque dépendance active, le Manager prend la première solution parmi : la liaison choisie dans l'assistant ; un service de la même installation qui la fournit ; un service déjà installé dans le cluster ; la seule connexion du type attendu. Sinon, une dépendance facultative reste non liée, et une dépendance obligatoire est ajoutée à l'installation dans son mode par défaut (la colonne ci-dessous nomme le service du catalogue ajouté).
| Liaison | Fournie par | Type de connexion | Point d'accès | Facultative | Quand rien n'est lié | Description |
|---|
database | postgresql (versions >= 13) | postgresql | sql | non | postgresql est ajouté à l'installation | Base des mémoires (base mem0) : la collection pgvector des mémoires et des entités. Le provisionnement crée le rôle mem0, propriétaire de ses seules bases, et l'extension vector. |
app | postgresql (versions >= 13) | postgresql | sql | non | postgresql est ajouté à l'installation | Base applicative (base mem0_app) du serveur : utilisateurs, clés d'API, jetons de rafraîchissement, réglages et journal des requêtes (migrations Alembic). Elle doit être sur le même serveur PostgreSQL que la base des mémoires. |
llm | litellm | - | api | non | litellm est ajouté à l'installation | Passerelle compatible OpenAI du LLM (extraction des faits) et du modèle de plongement ; les moteurs vLLM et Ollama du Manager sont joints à travers elle. |
Vérifications des points d'accès liés
- le point d'accès
/v1/models de la liaison llm répond avec le statut 200 et liste les valeurs de llm_model, embedder_model, vérifié par le Manager avant l'installation (bloquant, llm_models).
Points d'accès
| Point d'accès | Schéma | Composant | Port | Chemin | Paramètre TLS | Paramètres de liaison | Secrets de liaison | Commande de provisionnement |
|---|
api | http | mem0-server | 8720 (port) | - | tls_enabled | collection, embedding_dims | api_key | - |
Fichiers de configuration client
Fichiers rendus pour le téléchargement de la configuration client :
Commandes
| Commande | Composant | Cible | Description |
|---|
Configuration effective (configuration) | mem0-server | premier hôte | Configuration avec laquelle le serveur tourne (GET /configure, secrets masqués par le serveur). |
Purger le journal des requêtes (prune_request_logs) | request-log-pruner | premier hôte | Supprime maintenant les lignes du journal des requêtes plus anciennes que la rétention. |
Appliquer les migrations (migrate) | mem0-server | premier hôte | Applique les migrations Alembic de la version à la base applicative (fait aussi à chaque démarrage du serveur). |
Journaux récents (logs) | mem0-server | hôte choisi | Dernières lignes du journal du serveur. |
Contrôles de santé
Vivacité (par instance)
| Composant | Contrôle | Détails |
|---|
mem0-server | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled and config.listen_scope == 'network' else ((host.ip or '127.0.0.1') if config.listen_scope == 'network' else '127.0.0.1') }}:{{ config.port }}/openapi.json | Attendu 200 ; Attendu Mem0 REST APIs ; 60 tentatives ; intervalle 2 s ; délai 5 s |
request-log-pruner | {{ paths.opt }}/venv/bin/python {{ paths.opt }}/server/navin_prune.py --check {{ paths.data }}/home/prune.status {{ config.prune_interval_hours * 7200 + 600 }} | 20 tentatives ; intervalle 3 s ; délai 30 s |
Disponibilité (contrôle du service)
| Contrôle | Détails |
|---|
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled and config.listen_scope == 'network' else ((host.ip or '127.0.0.1') if config.listen_scope == 'network' else '127.0.0.1') }}:{{ config.port }}/auth/setup-status | Attendu 200 ; Attendu "needsSetup":false ; 10 tentatives ; intervalle 3 s ; délai 10 s |
Test fonctionnel
Dans un espace dédié (user_id navin-smoke-<nonce>) : vérifie qu'un appel sans clé est refusé, stocke une mémoire (appel de plongement), interroge le LLM à travers le serveur, retrouve la mémoire par recherche sémantique, la met à jour, la relit, la supprime, vérifie que l'espace est vide, puis supprime l'espace quoi qu'il arrive. (mem0-server: refused_without_key, create, llm, search, update, read_back, delete, gone, cleanup)
Contrôles préalables
| Contrôle | Type | Signification | Sévérité | Composants |
|---|
memory | memory_mb {"min": 1024} | au moins 1024 Mo de mémoire | bloquant | mem0-server |
cpu | cpu_count {"min": 1} | au moins 1 CPU | bloquant | mem0-server |
disk | disk_free_mb {"min": 2048} | au moins 2048 Mo libres pour /var/lib/navin | bloquant | mem0-server |
api_port_free | port_free {"param": "port"} | port 8720 libre sur l'hôte | bloquant | mem0-server |
llm_models | http_reachable {"binding": "llm", "path": "/v1/models", "bearer_secret": "token", "contains_params": ["llm_model", "embedder_model"], "timeout_s": 10} | le point d'accès /v1/models de la liaison llm répond avec le statut 200 et liste les valeurs de llm_model, embedder_model, vérifié par le Manager avant l'installation | bloquant | mem0-server |
Sauvegarde et restauration
pg_dump (format custom, sans propriétaire ni privilège) des bases des mémoires et applicative et sauvegarde SQLite en ligne du fichier d'historique ; la vérification lit la table des matières de chaque sauvegarde et contrôle l'intégrité d'une copie de l'historique. Restauration : le serveur est arrêté, pg_restore --clean --if-exists remplace les objets de chaque base en une transaction (l'extension vector reste celle du provisionnement) et le fichier d'historique est remplacé.
| |
|---|
| Format | mem0-pgdump |
| Composant | mem0-server |
| Fichiers | {{ backup.dir }}/memories.dump, {{ backup.dir }}/app.dump, {{ backup.dir }}/history.db |
| Test de restauration | oui |
| Instances arrêtées pendant la restauration | oui |
Mise à niveau
| |
|---|
| Prise en charge depuis | |
| Avec état | oui |
| Sauvegarde avant la mise à niveau | oui |
| Retour arrière | non (Les migrations Alembic du serveur ne vont qu'en avant (elles s'appliquent à chaque démarrage d'une nouvelle version et le Manager ne les annule jamais) : le retour arrière est la restauration de la sauvegarde prise avant la mise à jour.) |
| Migrations | alembic_head |
Désinstallation
Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.
Liens rapides
- Référence de l'API :
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/docs
Documentation amont