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

memU

Memoria personal en archivos

Recuperación rápida · Mayor precisión · Menor costo

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

---

Warning

🚧 En plena reconstrucción — memU está en pleno rediseño; las APIs, los comandos de la CLI y la documentación pueden cambiar sin previo aviso. Se espera que se estabilice alrededor del 15 de julio de 2026.

memU compila conversaciones, documentos, código, imágenes, audio, video, URLs y trazas de herramientas en archivos Markdown legibles por humanos (INDEX.md, MEMORY.md, SKILL.md). El agente recorre el árbol y carga solo la memoria que necesita en el momento — sin escanear todo ni meter historiales largos en cada prompt:

• INDEX.md — mapa de todo: categorías, archivos y resúmenes, para que el agente sepa dónde mirar primero
• MEMORY.md — perfil, preferencias, objetivos, hechos y eventos clave extraídos de los datos fuente
• SKILL.md — patrones de herramientas y flujos de trabajo reutilizables, extraídos automáticamente de trazas y refinados en cada memorize()

workspace/
├── INDEX.md              ← mapa de todo: categorías, archivos y resúmenes
├── MEMORY.md             ← perfil, preferencias, objetivos y eventos clave
└── skill/
    ├── {skill_name}/
    │   └── SKILL.md       ← una habilidad o patrón de herramienta aprendido
    └── {another_skill}/
        └── SKILL.md

Tres cosas lo diferencian de meter todo en el prompt:

• Recuperación rápida — ir a la carpeta relevante y ordenar archivos en lugar de escanear todo cada vez.
• Mayor precisión — acotar por usuario, tarea o sesión, y rastrear cada elemento hasta su fuente original.
• Menor costo — recuperar contexto compacto y acotado en lugar de reinyectar historiales largos en cada prompt.
• Auditable — un árbol de archivos legible por humanos que puedes revisar, editar y enrutar con tu propio almacenamiento y proveedores de LLM.

---

🔄 Cómo funciona

Piénsalo como dos operaciones de sistema de archivos: escribir fuentes en bruto en una memoria organizada y leer los archivos correctos de vuelta hacia el agente.

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

Escribir en el sistema de archivos (memorize)

1. Ingerir (Ingest): almacena cada fuente como un Resource (el archivo en bruto) con su modalidad y ubicación de origen
2. Preprocesar (Preprocess): analiza texto, genera descripciones de imágenes/video, transcribe audio y normaliza las entradas
3. Extraer (Extract): convierte el contenido en bruto en registros RecallEntry tipados (los archivos): memorias de tipo profile, event, knowledge, behavior, skill o tool
4. Organizar (Organize): clasifica los elementos en carpetas RecallFile (una categoría de memoria, o una habilidad), los enlaza entre sí, los vectoriza y los resume en un árbol navegable
5. Persistir (Persist): escribe registros, relaciones, embeddings y resúmenes de carpeta a través del backend configurado

Leer del sistema de archivos (retrieve)

6. Recuperar (Retrieve): navega por las carpetas y devuelve solo los archivos relevantes para el usuario, agente, sesión o tarea actuales

---

🗂️ El sistema de archivos de memoria

La salida principal de memU es un árbol de memoria navegable —carpetas, archivos y los artefactos de origen detrás de ellos— persistido mediante contratos de repositorio y devuelto como diccionarios desde memorize() y retrieve().

RecallFile                           ← carpeta: un tema con un resumen en evolución
├── name, track (memory | skill), description, content
├── embedding
└── RecallEntry[]                    ← archivos: memorias atómicas y tipadas
    ├── memory_type: profile | event | knowledge | behavior | skill | tool
    ├── summary, extra, happened_at, embedding
    └── Resource                     ← fuente: el archivo en bruto del que proviene esta memoria
        └── url, modality, local_path, caption, embedding

Registro	Rol en el sistema de archivos	Usado para
RecallFile	Carpeta: agrupa memorias relacionadas (o contiene una habilidad) y mantiene un resumen a nivel de tema; un campo track lo marca como memory o skill	Cargar contexto compacto para consultas amplias
RecallEntry	Archivo: memoria atómica tipada con un resumen y metadatos opcionales	Inyectar hechos, preferencias, eventos, habilidades y patrones de herramientas precisos
Resource	Artefacto de origen: el archivo original detrás de una memoria, con descripción/texto	Rastrear el contexto hasta su origen
RecallFileEntry	Enlace: la arista que archiva un elemento bajo una carpeta	Navegar memorias relacionadas sin reprocesar la fuente

Esto da a los agentes un sistema de archivos de memoria estable: ingieren las fuentes en bruto una sola vez y luego solicitan archivos delimitados y ordenados, en lugar de releer cada artefacto de origen.

---

🧩 Qué construye memU

Cada capa del sistema de archivos se almacena como un registro estructurado:

Capa	Qué representa	Por qué la usan los agentes
RecallFile	Carpeta autogenerada: un tema (o una habilidad) con un resumen en evolución	Cargar contexto de alto nivel antes de profundizar en detalles
RecallEntry	Un archivo: memoria estructurada atómica con un tipo y un resumen	Inyectar hechos, preferencias, eventos, habilidades y patrones de herramientas precisos
Resource	Artefacto de origen detrás de un archivo: conversación, documento, imagen, video, audio, URL o archivo	Rastrear la memoria hasta su origen
RecallFileEntry	El enlace que archiva un elemento bajo una carpeta	Navegar memorias relacionadas sin reprocesar la fuente
Embedding	Índice vectorial sobre carpetas, archivos y fuentes	Recuperar contexto relevante con baja latencia

Ejemplo de salida 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" }
  ]
}

Luego un agente puede llamar a retrieve() para obtener una carga de contexto delimitada y ordenada por relevancia:

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

---

⭐️ Dale una estrella al repositorio

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.

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.

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.

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.

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 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: 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 <token>

Method	Endpoint	Description
POST	/api/v3/memory/memorize	Ingiere datos en bruto y construye memoria estructurada
GET	/api/v3/memory/memorize/status/{task_id}	Consulta el estado del procesamiento
POST	/api/v3/memory/categories	Lista las categorías autogeneradas
POST	/api/v3/memory/retrieve	Consulta la memoria para obtener contexto del agente

📚 Documentación completa de la API

---

Opción 2: Autoalojado

Instalación

Desde un clon de este repositorio:

uv sync
# o, para la configuración completa de desarrollo:
make install

Para instalar el paquete publicado en su lugar:

pip install memu-py

Requisitos: Python 3.13+. Los ejemplos por defecto usan OpenAI, así que define OPENAI_API_KEY o pasa otro proveedor mediante llm_profiles.

Ejecuta un script de prueba en memoria:

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

Ejecuta con 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

---

Proveedores personalizados de LLM y embeddings

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"
        }
    },
)

---

Integración con 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(): estructura datos en bruto

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

# 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

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

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

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.

Ver resultados detallados: memU-experiment

---

🧩 Ecosistema

Repositorio	Descripción
memU	Sistema de archivos de memoria central: ingesta, extracción, recuperación
memU-server	Backend con sincronización en tiempo real y disparadores webhook
memU-ui	Panel visual para explorar y monitorizar la memoria

Enlaces rápidos:

• 🚀 Prueba MemU Cloud
• 📚 Documentación de la API
• 💬 Comunidad de Discord

---

🤝 Socios

---

🤝 Contribuir

# Haz fork y clona
git clone https://github.com/YOUR_USERNAME/memU.git
cd memU

# Instala las dependencias de desarrollo
make install

# Ejecuta las comprobaciones de calidad antes de enviar
make check

Consulta CONTRIBUTING.md para las pautas completas.

Requisitos previos: Python 3.13+, uv, Git

---

📄 Licencia

Apache License 2.0

---

🌍 Comunidad

• GitHub Issues: Reporta errores y solicita funciones
• Discord: Únete a la comunidad
• X (Twitter): Sigue a @memU_ai
• Contacto: info@nevamind.ai

---

⭐ Danos una estrella en GitHub para recibir notificaciones sobre nuevas versiones.