nevamind-ai--memu/readme/README_fr.md

memU

Mémoire personnelle en fichiers

Récupération rapide · Plus grande précision · Coût réduit

English | 中文 | 日本語 | 한국어 | Español | Français

---

Warning

🚧 En pleine refonte — memU fait l'objet d'une refonte majeure ; les APIs, les commandes CLI et la documentation peuvent changer sans préavis. Stabilisation prévue autour du 15 juillet 2026.

memU compile conversations, documents, code, images, audio, vidéo, URLs et traces d'outils en fichiers Markdown lisibles par l'humain (INDEX.md, MEMORY.md, SKILL.md). L'agent parcourt l'arborescence et ne charge que la mémoire utile au moment présent — sans tout scanner ni remplir chaque prompt d'historiques longs :

• INDEX.md — carte de tout : catégories, fichiers et résumés, pour que l'agent sache où chercher en premier
• MEMORY.md — profil, préférences, objectifs, faits et événements clés extraits des données sources
• SKILL.md — schémas d'outils et workflows réutilisables, extraits automatiquement des traces et affinés à chaque memorize()

workspace/
├── INDEX.md              ← carte de tout : catégories, fichiers et résumés
├── MEMORY.md             ← profil, préférences, objectifs et événements clés
└── skill/
    ├── {skill_name}/
    │   └── SKILL.md       ← une compétence ou un schéma d'outil appris
    └── {another_skill}/
        └── SKILL.md

Trois éléments le distinguent de tout mettre dans le prompt :

• Récupération rapide — aller au dossier pertinent et classer les fichiers au lieu de tout scanner à chaque fois.
• Plus grande précision — cadrer par utilisateur, tâche ou session, et remonter chaque élément jusqu'à sa source exacte.
• Coût réduit — récupérer un contexte compact et cadré au lieu de réinjecter de longs historiques dans chaque prompt.
• Auditable — une arborescence lisible par l'humain que vous pouvez inspecter, modifier et router via votre propre stockage et vos fournisseurs LLM.

---

🔄 Comment ça marche

Voyez cela comme deux opérations de système de fichiers : écrire des sources brutes dans une mémoire organisée, et relire les bons fichiers vers l'agent.

WRITE — memorize()                                         READ — retrieve()
──────────────────────────────────────────────            ──────────────────────────────────────────────
raw files        →  extract  →  files + folders            query  →  walk folders  →  ranked files
─────────────       ─────────    ──────────────            ─────     ────────────     ─────────────
chat logs        →  parse    →  profile / event items      user / task query
documents / URLs →  facts    →  knowledge / skill items       │
images / video   →  caption  →  resources + summaries         ├─ route + scope    → relevant folders (categories)
audio            →  transcribe→ event / knowledge items       ├─ rank by relevance → matching files (items)
tool logs        →  mine      → tool / skill items            └─ trace to source   → original resources

Écrire dans le système de fichiers (memorize)

1. Ingérer (Ingest) : stocke chaque source sous forme de Resource (le fichier brut) avec sa modalité et son emplacement d'origine
2. Prétraiter (Preprocess) : analyse le texte, légende les images/vidéos, transcrit l'audio et normalise les entrées
3. Extraire (Extract) : transforme le contenu brut en enregistrements RecallEntry typés (les fichiers) : mémoires de type profile, event, knowledge, behavior, skill ou tool
4. Organiser (Organize) : range les éléments dans des dossiers RecallFile (une catégorie de mémoire, ou une compétence), les relie entre eux, les vectorise et les résume en une arborescence navigable
5. Persister (Persist) : écrit les enregistrements, relations, embeddings et résumés de dossier via le backend configuré

Lire depuis le système de fichiers (retrieve)

6. Récupérer (Retrieve) : parcourt les dossiers et ne renvoie que les fichiers pertinents pour l'utilisateur, l'agent, la session ou la tâche en cours

---

🗂️ Le système de fichiers de mémoire

La sortie principale de memU est une arborescence de mémoire navigable — dossiers, fichiers et les artefacts source qui se trouvent derrière — persistée via des contrats de dépôt et renvoyée sous forme de dictionnaires par memorize() et retrieve().

RecallFile                           ← dossier : un thème avec un résumé en évolution
├── name, track (memory | skill), description, content
├── embedding
└── RecallEntry[]                    ← fichiers : des mémoires atomiques et typées
    ├── memory_type: profile | event | knowledge | behavior | skill | tool
    ├── summary, extra, happened_at, embedding
    └── Resource                     ← source : le fichier brut dont provient cette mémoire
        └── url, modality, local_path, caption, embedding

Enregistrement	Rôle dans le système de fichiers	Utilisé pour
RecallFile	Dossier : regroupe les mémoires liées (ou contient une compétence) et tient un résumé au niveau du thème ; un champ track le marque memory ou skill	Charger un contexte compact pour les requêtes larges
RecallEntry	Fichier : mémoire atomique typée avec un résumé et des métadonnées optionnelles	Injecter des faits, préférences, événements, compétences et schémas d'outils précis
Resource	Artefact source : le fichier d'origine derrière une mémoire, avec légende/texte	Remonter le contexte jusqu'à son origine
RecallFileEntry	Lien : l'arête qui classe un élément sous un dossier	Naviguer entre les mémoires liées sans retraiter la source

Cela donne aux agents un système de fichiers de mémoire stable : ils ingèrent les sources brutes une seule fois, puis demandent des fichiers délimités et classés plutôt que de relire chaque artefact source.

---

🧩 Ce que memU construit

Chaque couche du système de fichiers est stockée sous forme d'enregistrement structuré :

Couche	Ce qu'elle représente	Pourquoi les agents l'utilisent
RecallFile	Dossier auto-généré : un thème (ou une compétence) avec un résumé en évolution	Charger un contexte de haut niveau avant de plonger dans les détails
RecallEntry	Un fichier : mémoire structurée atomique avec un type et un résumé	Injecter des faits, préférences, événements, compétences et schémas d'outils précis
Resource	Artefact source derrière un fichier : conversation, document, image, vidéo, audio, URL ou fichier	Remonter la mémoire jusqu'à son origine
RecallFileEntry	Le lien qui classe un élément sous un dossier	Naviguer entre les mémoires liées sans retraiter la source
Embedding	Index vectoriel couvrant dossiers, fichiers et sources	Récupérer le contexte pertinent avec une faible latence

Exemple de sortie de memorize() :

{
  "resource": {
    "id": "res_01",
    "url": "files/launch-meeting.mp4",
    "modality": "video",
    "caption": "A product planning discussion about onboarding and launch risks."
  },
  "items": [
    {
      "id": "mem_01",
      "memory_type": "event",
      "summary": "The team decided to simplify onboarding before the next launch review."
    },
    {
      "id": "mem_02",
      "memory_type": "profile",
      "summary": "The user prefers concise implementation plans with explicit verification steps."
    },
    {
      "id": "mem_03",
      "memory_type": "tool",
      "summary": "Use repository-wide search before editing configuration files to avoid missing duplicated settings."
    }
  ],
  "categories": [
    {
      "id": "cat_01",
      "name": "product_goals",
      "summary": "Current launch priorities, onboarding decisions, and unresolved risks."
    }
  ],
  "relations": [
    { "item_id": "mem_01", "category_id": "cat_01" }
  ]
}

Un agent peut ensuite appeler retrieve() pour obtenir une charge de contexte délimitée et classée par pertinence :

context = await service.retrieve(
    queries=[{"role": "user", "content": {"text": "What context matters for this launch task?"}}],
    where={"user_id": "123"},
)

---

⭐️ Mettez une étoile au dépôt

Si vous trouvez memU utile ou intéressant, une étoile ⭐️ sur GitHub serait grandement appréciée.

---

✨ Fonctionnalités principales

Capacité	Description
🗂️ Ingestion multimodale	Écrit conversations, documents, images, vidéos, audio, URL, journaux et fichiers locaux dans la mémoire
📁 Système de fichiers de mémoire	Persiste dossiers (catégories), fichiers (éléments), artefacts source, liens, résumés et embeddings
🧠 Extraction de mémoire typée	Extrait des mémoires profile, event, knowledge, behavior, skill et tool à partir de sources brutes
🧭 Dossiers auto-organisés	Construit automatiquement catégories, liens, résumés et embeddings sans étiquetage manuel
🤖 Récupération prête pour les agents	Lit un contexte délimité et classé pouvant être injecté dans n'importe quel workflow d'agent
🧱 Stockage enfichable	Utilise des backends in-memory, SQLite ou Postgres avec les mêmes contrats de dépôt
🔀 Routage de LLM basé sur les profils	Achemine les tâches de chat, embeddings, vision et transcription via des profils de LLM configurables

---

🎯 Cas d'usage

1. Mémoire de conversation

Transforme les journaux de chat en préférences, objectifs, événements et contexte relationnel de l'utilisateur.

await service.memorize(
    resource_url="examples/resources/conversations/conv1.json",
    modality="conversation",
    user={"user_id": "123"},
)

context = await service.retrieve(
    queries=[{"role": "user", "content": {"text": "What should I remember about this user?"}}],
    where={"user_id": "123"},
)

2. Contexte d'espace de travail pour les agents de codage

Convertit documents, notes de PR, journaux et décisions de conception en mémoire de projet réutilisable.

await service.memorize(resource_url="docs/architecture.md", modality="document")
await service.memorize(resource_url="examples/resources/logs/log1.txt", modality="document")

context = await service.retrieve(
    queries=[{"role": "user", "content": {"text": "How should I structure this module?"}}],
)

3. Couche de connaissances multimodale

Extrait des faits interrogeables à partir de documents, captures d'écran, images, vidéos et notes audio.

await service.memorize(resource_url="examples/resources/docs/doc1.txt", modality="document")
await service.memorize(resource_url="examples/resources/images/image1.png", modality="image")
# Audio is supported for your own .mp3/.wav/.m4a files.
await service.memorize(resource_url="meeting-audio.mp3", modality="audio")

context = await service.retrieve(
    queries=[{"role": "user", "content": {"text": "What matters for the next research plan?"}}],
)

4. Apprentissage des outils et des agents

Transforme les traces d'exécution en mémoires d'outils qui indiquent aux agents futurs quand utiliser un outil et quelles erreurs éviter.

await service.memorize(resource_url="examples/resources/logs/log1.txt", modality="document")

context = await service.retrieve(
    queries=[{"role": "user", "content": {"text": "Which tools worked for config editing?"}}],
)

---

🗂️ Architecture

Le système de fichiers de mémoire est assez hiérarchique pour être parcouru et assez structuré pour une récupération directe :

Couche	Rôle principal	Rôle dans la récupération
Category (dossier)	Maintenir des résumés au niveau du thème	Assembler un contexte compact pour les requêtes larges
Item (fichier)	Stocker des mémoires atomiques typées	Charger des faits, événements, préférences, compétences et schémas d'outils précis
Resource (source)	Préserver les artefacts source et les légendes	Rappeler le contexte d'origine lorsque les résumés d'élément/catégorie ne suffisent pas

Consultez docs/architecture.md pour la vue à l'exécution de MemoryService, des pipelines de workflow, des backends de stockage et du routage de LLM.

---

🚀 Démarrage rapide

Option 1 : Version cloud

👉 memu.so : API hébergée pour l'ingestion gérée, la mémoire structurée et la récupération

Pour un déploiement en entreprise : info@nevamind.ai

Cloud API (v3)

Base URL	https://api.memu.so
Auth	Authorization: Bearer <token>

Method	Endpoint	Description
POST	/api/v3/memory/memorize	Ingère des données brutes et construit une mémoire structurée
GET	/api/v3/memory/memorize/status/{task_id}	Vérifie l'état du traitement
POST	/api/v3/memory/categories	Liste les catégories auto-générées
POST	/api/v3/memory/retrieve	Interroge la mémoire pour obtenir le contexte de l'agent

📚 Documentation complète de l'API

---

Option 2 : Auto-hébergé

Installation

À partir d'un clone de ce dépôt :

uv sync
# ou, pour la configuration de développement complète :
make install

Pour installer le paquet publié à la place :

pip install memu-py

Prérequis : Python 3.13+. Les exemples par défaut utilisent OpenAI ; définissez donc OPENAI_API_KEY ou passez un autre fournisseur via llm_profiles.

Exécuter un script de test en mémoire :

export OPENAI_API_KEY=your_key
cd tests
uv run python test_inmemory.py

Exécuter avec PostgreSQL + pgvector :

uv sync --extra postgres
docker run -d --name memu-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=memu \
  -p 5432:5432 \
  pgvector/pgvector:pg16

export OPENAI_API_KEY=your_key
export POSTGRES_DSN=postgresql+psycopg://postgres:postgres@127.0.0.1:5432/memu
cd tests
uv run python test_postgres.py

---

Fournisseurs de LLM et d'embeddings personnalisés

from memu import MemUService

service = MemUService(
    llm_profiles={
        "default": {
            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "api_key": "your_key",
            "chat_model": "qwen3-max",
            "client_backend": "sdk"
        },
        "embedding": {
            "base_url": "https://api.voyageai.com/v1",
            "api_key": "your_key",
            "embed_model": "voyage-3.5-lite"
        }
    },
)

---

Intégration OpenRouter

from memu import MemoryService

service = MemoryService(
    llm_profiles={
        "default": {
            "provider": "openrouter",
            "client_backend": "httpx",
            "base_url": "https://openrouter.ai",
            "api_key": "your_key",
            "chat_model": "anthropic/claude-3.5-sonnet",
            "embed_model": "openai/text-embedding-3-small",
        },
    },
    database_config={"metadata_store": {"provider": "inmemory"}},
)

---

📖 APIs principales

memorize() : structurer les données brutes

result = await service.memorize(
    resource_url="path/to/file.json",    # chemin de fichier local ou URL HTTP
    modality="conversation",            # conversation | document | image | video | audio
    user={"user_id": "123"},            # optionnel : délimiter à un utilisateur ou un agent
)
# Renvoie une fois le traitement terminé :
# { "resource": {...}, "items": [...], "categories": [...], "relations": [...] }

• Convertit l'entrée brute en éléments de mémoire typés
• Catégorise et vectorise les éléments sans étiquetage manuel
• Préserve les ressources source et les relations élément-catégorie

---

retrieve() : charger le contexte de l'agent

# La stratégie de récupération est définie une fois sur le service via retrieve_config :
#   MemoryService(retrieve_config={"method": "rag"})   # rappel vecteurs d'abord
#   MemoryService(retrieve_config={"method": "llm"})   # rappel classé par LLM
result = await service.retrieve(
    queries=[{"role": "user", "content": {"text": "What are their preferences?"}}],
    where={"user_id": "123"},   # filtre de portée
)
# Renvoie :
# {
#   "needs_retrieval": true,
#   "original_query": "...",
#   "rewritten_query": "...",
#   "next_step_query": "...",
#   "categories": [...],
#   "items": [...],
#   "resources": [...]
# }

retrieve_config.method	Comportement	Coût	Idéal pour
rag	Rappel des catégories/éléments/ressources avec vecteurs d'abord, avec routage LLM et vérifications de suffisance optionnels activés par défaut	Embeddings plus appels LLM, sauf si route_intention et sufficiency_check sont désactivés	Rappel délimité et rapide avec un raisonnement contrôlable
llm	Rappel des catégories/éléments/ressources classé par LLM	Classement par LLM à chaque niveau	Classement sémantique plus profond

---

💡 Exemples de workflows

Assistant en apprentissage permanent

export OPENAI_API_KEY=your_key
uv run python examples/example_1_conversation_memory.py

Extrait automatiquement les préférences, construit des modèles de relation et fait remonter le contexte pertinent dans les conversations futures.

Agent qui s'améliore lui-même

uv run python examples/example_2_skill_extraction.py

Surveille les actions de l'agent, identifie les schémas de réussites et d'échecs, et génère automatiquement des guides de compétences à partir de l'expérience.

Constructeur de contexte multimodal

uv run python examples/example_3_multimodal_memory.py

Recoupe automatiquement texte, images et documents dans une couche de mémoire unifiée.

---

📊 Performances

memU atteint une précision moyenne de 92,09 % sur le benchmark Locomo, sur l'ensemble des tâches de raisonnement.

Voir les résultats détaillés : memU-experiment

---

🧩 Écosystème

Dépôt	Description
memU	Système de fichiers de mémoire central : ingestion, extraction, récupération
memU-server	Backend avec synchronisation en temps réel et déclencheurs webhook
memU-ui	Tableau de bord visuel pour explorer et surveiller la mémoire

Liens rapides :

• 🚀 Essayer MemU Cloud
• 📚 Documentation de l'API
• 💬 Communauté Discord

---

🤝 Partenaires

---

🤝 Contribuer

# Forkez et clonez
git clone https://github.com/YOUR_USERNAME/memU.git
cd memU

# Installez les dépendances de développement
make install

# Lancez les contrôles qualité avant de soumettre
make check

Consultez CONTRIBUTING.md pour les directives complètes.

Prérequis : Python 3.13+, uv, Git

---

📄 Licence

Apache License 2.0

---

🌍 Communauté

• GitHub Issues : Signaler des bugs et demander des fonctionnalités
• Discord : Rejoindre la communauté
• X (Twitter) : Suivre @memU_ai
• Contact : info@nevamind.ai

---

⭐ Mettez-nous une étoile sur GitHub pour être averti des nouvelles versions !