# memU
### Memoria personal en archivos
**Recuperación rápida · Mayor precisión · Menor costo**
[](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 encuentras memU útil o interesante, una estrella ⭐️ en GitHub sería muy apreciada.
---
## ✨ Funciones principales
| Capacidad | Descripción |
|------------|-------------|
| 🗂️ **Ingesta multimodal** | Escribe conversaciones, documentos, imágenes, video, audio, URLs, registros y archivos locales en la memoria |
| 📁 **Sistema de archivos de memoria** | Persiste carpetas (categorías), archivos (elementos), artefactos de origen, enlaces, resúmenes y embeddings |
| 🧠 **Extracción de memoria tipada** | Extrae memorias profile, event, knowledge, behavior, skill y tool a partir de fuentes en bruto |
| 🧭 **Carpetas autoorganizadas** | Construye automáticamente categorías, enlaces, resúmenes y embeddings sin etiquetado manual |
| 🤖 **Recuperación lista para agentes** | Lee contexto delimitado y ordenado que puede inyectarse en cualquier flujo de trabajo de agente |
| 🧱 **Almacenamiento conectable** | Usa backends in-memory, SQLite o Postgres con los mismos contratos de repositorio |
| 🔀 **Enrutamiento de LLM basado en perfiles** | Enruta tareas de chat, embeddings, visión y transcripción a través de perfiles de LLM configurables |
---
## 🎯 Casos de uso
### 1. **Memoria de conversación**
*Convierte registros de chat en preferencias, objetivos, eventos y contexto de relación del usuario.*
```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. **Contexto de espacio de trabajo para agentes de programación**
*Convierte documentos, notas de PR, registros y decisiones de diseño en memoria de proyecto reutilizable.*
```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. **Capa de conocimiento multimodal**
*Extrae hechos buscables de documentos, capturas de pantalla, imágenes, videos y notas de 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. **Aprendizaje de herramientas y agentes**
*Convierte las trazas de ejecución en memorias de herramientas que indican a los agentes futuros cuándo usar una herramienta y qué errores evitar.*
```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?"}}],
)
```
---
## 🗂️ Arquitectura
El sistema de archivos de memoria es lo bastante jerárquico para navegarlo y lo bastante estructurado para una recuperación directa:
| Capa | Rol principal | Rol en la recuperación |
|-------|--------------|----------------|
| **Category (carpeta)** | Mantener resúmenes a nivel de tema | Ensamblar contexto compacto para consultas amplias |
| **Item (archivo)** | Almacenar memorias atómicas tipadas | Cargar hechos, eventos, preferencias, habilidades y patrones de herramientas precisos |
| **Resource (fuente)** | Preservar artefactos de origen y descripciones | Recuperar el contexto original cuando los resúmenes de elemento/categoría no bastan |
Consulta [docs/architecture.md](../docs/architecture.md) para la vista en tiempo de ejecución de `MemoryService`, los pipelines de flujo de trabajo, los backends de almacenamiento y el enrutamiento de LLM.
---
## 🚀 Inicio rápido
### Opción 1: Versión en la nube
👉 **[memu.so](https://memu.so)**: API alojada para ingesta gestionada, memoria estructurada y recuperación
Para despliegue empresarial: **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", # ruta de archivo local o URL HTTP
modality="conversation", # conversation | document | image | video | audio
user={"user_id": "123"}, # opcional: delimitar a un usuario o agente
)
# Devuelve tras completar el procesamiento:
# { "resource": {...}, "items": [...], "categories": [...], "relations": [...] }
```
- Convierte la entrada en bruto en elementos de memoria tipados
- Categoriza y vectoriza los elementos sin etiquetado manual
- Preserva los recursos de origen y las relaciones elemento-categoría
---
### `retrieve()`: carga contexto del agente
```python
# La estrategia de recuperación se define una vez en el servicio mediante retrieve_config:
# MemoryService(retrieve_config={"method": "rag"}) # recuperación con vectores primero
# MemoryService(retrieve_config={"method": "llm"}) # recuperación ordenada por LLM
result = await service.retrieve(
queries=[{"role": "user", "content": {"text": "What are their preferences?"}}],
where={"user_id": "123"}, # filtro de alcance
)
# Devuelve:
# {
# "needs_retrieval": true,
# "original_query": "...",
# "rewritten_query": "...",
# "next_step_query": "...",
# "categories": [...],
# "items": [...],
# "resources": [...]
# }
```
| `retrieve_config.method` | Comportamiento | Coste | Mejor para |
|--------------------------|----------|------|----------|
| `rag` | Recuperación de categorías/elementos/recursos con vectores primero, con enrutamiento LLM y comprobaciones de suficiencia opcionales activadas por defecto | Embeddings más llamadas a LLM, salvo que se desactiven `route_intention` y `sufficiency_check` | Recuperación delimitada y rápida con razonamiento controlable |
| `llm` | Recuperación de categorías/elementos/recursos ordenada por LLM | Ordenación por LLM en cada nivel | Ordenación semántica más profunda |
---
## 💡 Flujos de trabajo de ejemplo
### Asistente que aprende siempre
```bash
export OPENAI_API_KEY=your_key
uv run python examples/example_1_conversation_memory.py
```
Extrae preferencias automáticamente, construye modelos de relación y hace aflorar contexto relevante en conversaciones futuras.
### Agente que se mejora a sí mismo
```bash
uv run python examples/example_2_skill_extraction.py
```
Supervisa las acciones del agente, identifica patrones en éxitos y fracasos, y autogenera guías de habilidades a partir de la experiencia.
### Constructor de contexto multimodal
```bash
uv run python examples/example_3_multimodal_memory.py
```
Cruza automáticamente texto, imágenes y documentos en una capa de memoria unificada.
---
## 📊 Rendimiento
memU alcanza un **92,09 % de precisión promedio** en el benchmark Locomo en todas las tareas de razonamiento.
