# memU
### Mémoire personnelle en fichiers
**Récupération rapide · Plus grande précision · Coût réduit**
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](https://discord.com/invite/hQZntfGsbJ)
[](https://x.com/memU_ai)
**[English](README_en.md) | [中文](README_zh.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [Español](README_es.md) | [Français](README_fr.md)**
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.*
```python
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.*
```python
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.*
```python
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.*
```python
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](../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](https://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 
```python
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
```python
# 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
```bash
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
```bash
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
```bash
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.
