Skip to content

README.fr.md

Latest commit

 

History

History
550 lines (394 loc) · 25.6 KB

README.fr.md

File metadata and controls

550 lines (394 loc) · 25.6 KB
Raw
Logo SimpleMem

Mémoire à long terme efficace pour les agents LLM — Texte & Multimodal

Stockez, compressez et récupérez des souvenirs à long terme grâce à une compression sémantique sans perte. Désormais avec prise en charge multimodale pour le texte, les images, l'audio et la vidéo.

Fonctionne avec toute plateforme IA supportant MCP (mémoire texte) ou l'intégration Python (multimodal complet)

Claude Desktop
Claude Desktop 		Cursor
Cursor 		LM Studio
LM Studio 		Cherry Studio
Cherry Studio 		PyPI
Package PyPI 		+ Tout client
MCP

🔥 Actualités

  • [05/21/2026] 📦 Package unifié simplemem — une seule importation, routage automatique ! SimpleMem, Omni-SimpleMem et EvolveMem coexistent désormais dans un seul package. from simplemem import SimpleMem sélectionne automatiquement le backend texte ou multimodal selon le premier appel de méthode, et simplemem.optimize(...) exploite la boucle d'auto-évolution d'EvolveMem. Installation en une seule étape avec pip install -e ..
  • [05/14/2026] 🧬 EvolveMem (v3.0) — Mémoire auto-évolutive via AutoResearch ! L'infrastructure de récupération elle-même s'auto-évolue désormais grâce à un diagnostic en boucle fermée piloté par LLM. Sur LoCoMo, EvolveMem surpasse la meilleure baseline de +25,7 % en relatif ; sur MemBench, de +18,9 % en relatif. Le système découvre des dimensions de récupération entièrement nouvelles, absentes de la conception originale. Voir EvolveMem →
  • [04/02/2026] 🧠 Omni-SimpleMem (v2.0) — La mémoire multimodale est arrivée ! SimpleMem prend désormais en charge la mémoire texte, image, audio et vidéo. Atteignant un nouveau SOTA sur LoCoMo (F1=0,613, +47%) et Mem-Gallery (F1=0,810, +51%) par rapport au meilleur précédent. Voir Omni-SimpleMem →
  • [02/09/2026] 🚀 Mémoire inter-sessions — Surpasse Claude-Mem de 64% ! Voir la documentation inter-sessions →
  • [01/20/2026] 📦 SimpleMem est maintenant disponible sur PyPI ! Installez via pip install simplemem. Voir le guide d'utilisation du package →
  • [01/14/2026] 🎉 Le serveur MCP SimpleMem est EN LIGNE ! Hébergé dans le cloud sur mcp.simplemem.cloud. Voir la documentation MCP →
  • [01/05/2026] L'article SimpleMem a été publié sur arXiv !

📑 Table des matières

🚀 Démarrage rapide

🧠 Comprendre le flux de travail de base

En résumé, SimpleMem fonctionne comme un système de mémoire à long terme pour les agents basés sur des LLM. Le flux de travail se compose de trois étapes simples :

  1. Stocker les informations – Les dialogues ou faits sont traités et convertis en souvenirs structurés et atomiques.
  2. Indexer la mémoire – Les souvenirs stockés sont organisés à l'aide d'embeddings sémantiques et de métadonnées structurées.
  3. Récupérer la mémoire pertinente – Lors d'une requête, SimpleMem récupère les informations stockées les plus pertinentes en fonction du sens plutôt que des mots-clés.

Cette conception permet aux agents LLM de maintenir le contexte, de rappeler efficacement les informations passées et d'éviter de retraiter un historique redondant.

🎓 Utilisation de base

SimpleMem est fourni sous la forme d'un unique package simplemem. Le mode par défaut mode="auto" détecte automatiquement le backend à utiliser en fonction de ce que vous appelez — aucune configuration manuelle n'est nécessaire :

from simplemem import SimpleMem

mem = SimpleMem()  # mode="auto" — backend choisi par le premier appel

Le premier appel de méthode détermine le backend :

Premier appel Backend sélectionné Pourquoi
add_dialogue() Texte (SimpleMem) API basée sur les dialogues → mode texte
add_text() / add_image() / add_audio() / add_video() Omni (Omni-SimpleMem) API multimodale → mode omni

📝 Auto → Texte (entrée texte pure)

from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_dialogue() → text backend auto-selected
mem.add_dialogue(
    "Alice",
    "Bob, let's meet at Starbucks tomorrow at 2pm",
    "2025-11-15T14:30:00",
)
mem.add_dialogue(
    "Bob",
    "Sure, I'll bring the market analysis report",
    "2025-11-15T14:31:00",
)
mem.finalize()

answer = mem.ask("When and where will Alice and Bob meet?")
# → "16 November 2025 at 2:00 PM at Starbucks"

🧠 Auto → Omni (entrée multimodale)

from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_image() → omni backend auto-selected
mem.add_text(
    "User loves hiking in the Rocky Mountains.",
    tags=["session_id:D1"],
)
mem.add_image("photo.jpg", tags=["session_id:D1"])
mem.add_audio("voice_note.wav", tags=["session_id:D1"])

result = mem.query("What does the user enjoy?", top_k=5)
for item in result.items:
    print(item["summary"])

mem.close()

💡 Astuce : Le mode auto sélectionne le backend le plus léger adapté à vos données. Vous pouvez toujours utiliser mode="text" ou mode="omni" explicitement si vous préférez.

🧬 Avancé : Optimiser la configuration de récupération

Ajustez les hyperparamètres de récupération hors ligne sur votre propre ensemble de développement, puis déployez la Config résultante pour l'inférence. Il s'agit d'une fine couche autour de la boucle d'auto-évolution d'EvolveMem :

import simplemem
from simplemem import SimpleMem, load_config

# mem is a finalized SimpleMem instance with memories already built
dev_questions = [
    ("When is the meeting?", "2pm tomorrow at Starbucks"),
    ("What should Bob prepare?", "market analysis report"),
]
config = simplemem.optimize(mem, dev_questions, max_rounds=3)
config.save("my_config.json")

# Later, deploy with the optimized config
config = load_config("my_config.json")
mem = SimpleMem(config=config)

EvolveMem exécute un cycle Évaluer → Diagnostiquer → Proposer → Protéger piloté par LLM sur vos questions de développement, ajustant les indicateurs globaux de récupération (top_k, mode de fusion, vérification des réponses, tours de réflexion, ...). Pour la version autonome complète avec les adaptateurs de benchmarks et les substitutions par catégorie, voir EvolveMem/.

🚄 Avancé : Traitement parallèle

Pour le traitement de dialogues à grande échelle, activez le mode parallèle :

from simplemem import create

mem = create(
    mode="text",
    clear_db=True,
    enable_parallel_processing=True,  # ⚡ Parallel memory building
    max_parallel_workers=8,
    enable_parallel_retrieval=True,   # 🔍 Parallel query execution
    max_retrieval_workers=4
)

💡 Conseil Pro : Le traitement parallèle réduit considérablement la latence pour les opérations par lots !

🌟 Aperçu

SimpleMem est une pile mémoire unifiée pour les agents LLM, construite sur un principe : stocker des souvenirs sémantiquement sans perte à haute densité d'information, afin qu'un agent se rappelle davantage tout en dépensant bien moins de tokens. Le package rassemble trois travaux qui partagent ce principe mais s'attaquent à différentes parties du problème.

📝 SimpleMem : le noyau d'efficacité (texte)

La plupart des systèmes de mémoire imposent un mauvais compromis. Ils accumulent passivement l'historique brut des interactions (redondant, gourmand en tokens) ou exécutent des boucles de raisonnement coûteuses pour filtrer le bruit (lent, onéreux). SimpleMem compresse plutôt les interactions via un pipeline en trois étapes :

Étape Ce qu'elle fait
1. Compression structurée sémantique Distille les interactions non structurées en unités de mémoire compactes (faits autonomes avec coréférences résolues et horodatages absolus), chacune indexée selon plusieurs vues complémentaires pour une récupération flexible.
2. Synthèse sémantique en ligne Fusionne le contexte apparenté au sein d'une session en représentations abstraites unifiées, supprimant la redondance lors de la construction de la mémoire plutôt qu'au moment de la requête.
3. Planification de récupération orientée intention Déduit l'intention de recherche derrière une requête pour décider quoi récupérer et assembler un contexte précis et compact.

Sur le benchmark LoCoMo, cela délivre un gain moyen de F1 de 26,4 % par rapport aux systèmes précédents tout en réduisant la consommation de tokens au moment de l'inférence d'environ 30x. Détails des mécanismes (couches d'index hybrides, exemples de compression, planification de récupération) : Mémoire texte SimpleMem →.

🧠 Omni-SimpleMem : mémoire multimodale (texte, image, audio, vidéo)

Omni-SimpleMem étend la philosophie compression-en-premier à quatre modalités, basée sur trois principes : Ingestion sélective (filtrage basé sur l'entropie par modalité), Récupération progressive (FAISS + BM25 hybride avec expansion pyramidale du budget de tokens), et Augmentation par graphe de connaissances (raisonnement cross-modal multi-sauts). Plutôt que d'être conçue à la main, son architecture a été découverte par un pipeline de recherche autonome qui a mené environ 50 expériences sur deux benchmarks, diagnostiquant les modes d'échec, proposant des changements architecturaux, et même réparant des bugs dans le pipeline de données sans intervention humaine dans la boucle interne. Significativement, les corrections de bugs et les changements architecturaux ont chacun contribué davantage que l'ensemble du réglage des hyperparamètres, faisant passer le système d'une baseline naïve à l'état de l'art sur LoCoMo et Mem-Gallery. Documentation complète : Omni-SimpleMem →.

🧬 EvolveMem : récupération auto-évolutive

EvolveMem comble un angle mort partagé par presque tous les systèmes de mémoire : le contenu stocké évolue, mais la machinerie de récupération (fonctions de score, stratégies de fusion, politiques de génération de réponses) reste figée après le déploiement. EvolveMem exécute un processus AutoResearch en boucle fermée (Évaluer → Diagnostiquer → Proposer → Protéger → Répéter) dans lequel un LLM diagnostique les échecs par question et propose des modifications de configuration, protégées par un rollback automatique en cas de régression et des incitations à l'exploration lors de stagnation. Il découvre de nouvelles dimensions de récupération (décomposition de requêtes, substitution d'entités, vérification des réponses) absentes de la conception originale, améliore LoCoMo de 25,7 % en relatif par rapport à la meilleure baseline, et ses configurations évoluées se transfèrent positivement d'un benchmark à l'autre. Documentation complète : EvolveMem →.

Comment ils s'articulent

from simplemem import SimpleMem vous donne le noyau texte avec routage automatique vers le backend multimodal, et simplemem.optimize(...) exploite EvolveMem pour ajuster la récupération à vos propres données. Un seul package, un seul modèle mental : compresser sans perte, récupérer par intention, et laisser le système continuer à s'améliorer lui-même.

📦 Installation

📝 Notes pour les nouveaux utilisateurs

  • Assurez-vous d'utiliser Python 3.10+ dans votre environnement actif, pas seulement installé globalement.
  • Une clé API compatible OpenAI doit être configurée avant d'exécuter toute construction ou récupération de mémoire, sinon l'initialisation peut échouer.
  • Lorsque vous utilisez des fournisseurs non-OpenAI (par ex., Qwen ou Azure OpenAI), vérifiez à la fois le nom du modèle et OPENAI_BASE_URL dans config.py.
  • Pour les grands ensembles de données de dialogue, activer le traitement parallèle peut réduire considérablement le temps de construction de la mémoire.

📋 Prérequis

  • 🐍 Python 3.10+
  • 🔑 API compatible OpenAI (OpenAI, Qwen, Azure OpenAI, etc.)

🛠️ Configuration

# 📥 Clone repository
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem

# 📦 Install dependencies (pinned versions)
pip install -r requirements.txt

# — OR — install as an editable package
pip install -e .                  # default: text + multimodal + evolver
pip install -e ".[server]"        # + MCP / HTTP server (mcp, fastapi, ...)
pip install -e ".[all]"           # everything, including dev tools

# ⚙️ Configure API settings
cp config.py.example config.py
# Edit config.py with your API key and preferences

⚙️ Exemple de configuration

# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None  # or custom endpoint for Qwen/Azure

LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"  # State-of-the-art retrieval

🐳 Exécuter avec Docker

Le serveur MCP peut être exécuté dans Docker pour un environnement cohérent et isolé. Les données (LanceDB et base de données utilisateur) sont persistées dans un volume hôte.

Prérequis

Démarrage rapide

# From the repository root
docker compose up -d

Les données sont stockées dans ./data sur l'hôte (créé automatiquement).

Configuration personnalisée

  1. Copiez le modèle d'environnement et modifiez-le : 
    cp .env.example .env
# Edit .env: set JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, model URLs, etc.
  2. Exécutez avec le fichier d'environnement : 
    docker compose --env-file .env up -d

Utiliser Ollama sur l'hôte

Lorsque LLM_PROVIDER=ollama et qu'Ollama s'exécute sur votre machine (pas dans Docker), définissez dans .env :

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

Sur Linux, host.docker.internal est activé automatiquement via le fichier Compose.

Commandes utiles

docker compose logs -f simplemem   # Follow logs
docker compose down                 # Stop and remove containers

📖 Pour l'auto-hébergement du serveur MCP (Docker ou bare metal), voir la Documentation MCP.

🔌 Serveur MCP (mémoire texte)

SimpleMem est disponible en tant que service de mémoire hébergé dans le cloud via le Model Context Protocol (MCP), permettant une intégration transparente avec des assistants IA comme Claude Desktop, Cursor et d'autres clients compatibles MCP.

🌐 Service Cloud : mcp.simplemem.cloud — ou hébergez vous-même le serveur MCP localement en utilisant Docker.

Fonctionnalités clés

Fonctionnalité Description
HTTP diffusable Protocole MCP 2025-03-26 avec JSON-RPC 2.0
Isolation multi-locataires Tables de données par utilisateur avec authentification par token
Récupération hybride Recherche sémantique + correspondance par mots-clés + filtrage par métadonnées
Optimisé pour la production Temps de réponse plus rapides avec intégration OpenRouter

Configuration rapide

{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

📖 Pour des instructions de configuration détaillées et un guide d'auto-hébergement, voir la Documentation MCP

📊 Reproduire les résultats de l'article

Reproduisez les chiffres LoCoMo / MemBench / Mem-Gallery des articles. Chaque pilier dispose de son propre lanceur de benchmark dans son propre répertoire. Installez d'abord les extras de benchmark : pip install -e ".[benchmark]".

📝 SimpleMem (texte) — LoCoMo

Exécutez depuis la racine du dépôt :

python test_locomo10.py                       # full LoCoMo benchmark
python test_locomo10.py --num-samples 5       # quick subset
python test_locomo10.py --result-file my_results.json

🧬 EvolveMem — auto-évolution + LoCoMo / MemBench

Exécutez depuis le répertoire EvolveMem/ (voir EvolveMem/README.md) :

cd EvolveMem
python run_evolution.py --data data/locomo10.json --max-rounds 7
python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3
python run_benchmark.py membench --agent FirstAgent --max-rounds 3

🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery

Exécutez depuis le répertoire OmniSimpleMem/ (voir OmniSimpleMem/README.md) :

cd OmniSimpleMem
python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o

🗺️ Feuille de route

Capacité actuelle par canal d'intégration :

Capacité Python (pip install) Serveur MCP (Claude Desktop, Cursor, ...)
Mémoire texte ✅ ✅
Multimodal (image / audio / vidéo) ✅ ⬜ prévu
Récupération auto-évolutive optimize() ✅ ⬜ prévu

Travaux prévus pour combler l'écart (le serveur MCP est un service texte multi-locataires autonome ; ce sont de vraies fonctionnalités, pas des corrections de documentation) :

  • Multimodal via MCP. Ajouter les outils memory_add_image / memory_add_audio / memory_add_video. Nécessite un chemin de téléchargement de fichier (base64 ou URL, car MCP ne peut pas transmettre les chemins de fichiers locaux), une adaptation multi-locataires du backend de stockage Omni-SimpleMem, et l'accès côté serveur aux modèles de vision/audio.
  • EvolveMem via MCP. Exposer optimize() comme outil MCP. Plus tractable que le multimodal (texte en entrée, config JSON en sortie, pas de transport de fichiers), mais le récupérateur MCP honore actuellement seulement semantic_top_k / keyword_top_k des ~10 dimensions qu'EvolveMem fait évoluer. Nécessite d'étendre le récupérateur MCP pour prendre en charge les curseurs restants (structured top_k, mode/poids de fusion, substitution d'entités, décomposition de requêtes, vérification des réponses), un adaptateur pour exécuter la boucle d'évolution sur les souvenirs stockés d'un locataire, la persistance de la configuration par locataire, et une exécution asynchrone (la boucle est intensive en LLM et ferait expirer une requête synchrone).
  • Docker hérite des deux automatiquement une fois que le serveur MCP les supporte (ajouter les dépendances multimodales à l'image et un volume de stockage Omni).

Pour le multimodal complet et la récupération auto-évolutive aujourd'hui, utilisez l'API Python (voir Démarrage rapide).

📝 Citation

Si vous utilisez SimpleMem dans vos recherches, veuillez citer :

@article{simplemem2026,
  title={SimpleMem: Efficient Lifelong Memory for LLM Agents},
  author={Liu, Jiaqi and Su, Yaofeng and Xia, Peng and Zhou, Yiyang and Han, Siwei and  Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2601.02553},
  year={2026},
  url={https://arxiv.org/abs/2601.02553}
}
@article{evolvemem2026,
  title={EvolveMem: Self-Evolving Memory Architecture via AutoResearch for LLM Agents},
  author={Liu, Jiaqi and Ye, Xinyu and Xia, Peng and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2605.13941},
  year={2026},
  url={https://arxiv.org/abs/2605.13941}
}
@article{omnisimplemem2026,
  title   = {Omni-SimpleMem: Autoresearch-Guided Discovery of Lifelong Multimodal Agent Memory},
  author  = {Liu, Jiaqi and Ling, Zipeng and Qiu, Shi and Liu, Yanqing and Han, Siwei and Xia, Peng and Tu, Haoqin and Zheng, Zeyu and Xie, Cihang and Fleming, Charles and Ding, Mingyu and Yao, Huaxiu},
  journal = {arXiv preprint arXiv:2604.01007},
  year    = {2026},
}

📄 Licence

Ce projet est sous licence MIT — voir le fichier LICENSE pour plus de détails.

🙏 Remerciements

Nous souhaitons remercier les projets et équipes suivants :

  • 🔍 Modèle d'embedding : Qwen3-Embedding - Performance de récupération à la pointe de l'état de l'art
  • 🗄️ Base de données vectorielle : LanceDB - Stockage en colonnes haute performance
  • 📊 Benchmark : LoCoMo - Framework d'évaluation de la mémoire à long contexte