simplemem_logo

## Memoria Vitalicia Eficiente para Agentes LLM — Texto y Multimodal Almacena, comprime y recupera memorias a largo plazo con compresión semántica sin pérdidas. Ahora con soporte multimodal para texto, imagen, audio y vídeo.

Compatible con cualquier plataforma de IA que soporte MCP (memoria de texto) o integración con Python (multimodal completo)

_{Claude Desktop}

_Cursor

_{LM Studio}

_{Cherry Studio}

_{Paquete PyPI}

_{+ Cualquier Cliente MCP}

[🇬🇧 English](../../README.md) • [🇨🇳 中文](./README.zh-CN.md) • [🇯🇵 日本語](./README.ja.md) • [🇰🇷 한국어](./README.ko.md) • **🇪🇸 Español** • [🇫🇷 Français](./README.fr.md) • [🇩🇪 Deutsch](./README.de.md) • [🇧🇷 Português](./README.pt-br.md)
[🇷🇺 Русский](./README.ru.md) • [🇸🇦 العربية](./README.ar.md) • [🇮🇹 Italiano](./README.it.md) • [🇻🇳 Tiếng Việt](./README.vi.md) • [🇹🇷 Türkçe](./README.tr.md)
[![Project Page](https://img.shields.io/badge/🎬_DEMO_INTERACTIVO-Visitar_Nuestro_Sitio_Web-FF6B6B?style=for-the-badge&labelColor=FF6B6B&color=4ECDC4&logoColor=white)](https://aiming-lab.github.io/SimpleMem-Page)

[🚀 Inicio Rápido](#-inicio-rápido) • [🌟 Descripción General](#-descripción-general) • [📦 Instalación](#-instalación) • [🔌 Servidor MCP](#-servidor-mcp-memoria-de-texto) • [📊 Reproducir](#-reproducir-resultados-del-artículo) • [📝 Citación](#-citación)

## 🔥 Novedades - **[05/21/2026]** 📦 **¡Paquete `simplemem` unificado — una sola importación, enrutamiento automático!** SimpleMem, Omni-SimpleMem y EvolveMem ahora conviven en un único paquete. `from simplemem import SimpleMem` selecciona automáticamente el backend de texto o multimodal según el primer método que invoques, y `simplemem.optimize(...)` accede al bucle de auto-evolución de EvolveMem. Instala en un solo paso con `pip install -e .`. - **[05/14/2026]** 🧬 **EvolveMem (v3.0) — ¡Memoria Auto-Evolutiva mediante AutoResearch!** La propia infraestructura de recuperación ahora se auto-evoluciona mediante diagnóstico en bucle cerrado impulsado por LLM. En LoCoMo, EvolveMem supera a la línea base más fuerte en **+25,7% relativo**; en MemBench, en **+18,9% relativo**. El sistema descubre dimensiones de recuperación completamente nuevas no presentes en el diseño original. [Ver EvolveMem →](../../EvolveMem/) - **[04/02/2026]** 🧠 **Omni-SimpleMem (v2.0) — ¡La Memoria Multimodal ya está aquí!** SimpleMem ahora soporta memoria de **texto, imagen, audio y vídeo**. Alcanzando **nuevo SOTA en LoCoMo (F1=0,613, +47%)** y **Mem-Gallery (F1=0,810, +51%)** sobre el mejor resultado anterior. [Ver Omni-SimpleMem →](../../OmniSimpleMem/) - **[02/09/2026]** 🚀 **¡Memoria Cross-Session — Superando a Claude-Mem en un 64%!** [Ver Documentación Cross-Session →](../../cross/README.md) - **[01/20/2026]** 📦 **¡SimpleMem ya está disponible en PyPI!** Instala con `pip install simplemem`. [Ver Guía de Uso del Paquete →](../PACKAGE_USAGE.md) - **[01/14/2026]** 🎉 **¡El Servidor MCP de SimpleMem está EN VIVO!** Alojado en la nube en [mcp.simplemem.cloud](https://mcp.simplemem.cloud). [Ver Documentación MCP →](../../MCP/README.md) - **[01/05/2026]** El artículo de SimpleMem fue publicado en [arXiv](https://arxiv.org/abs/2601.02553). --- ## 📑 Tabla de Contenidos - [🚀 Inicio Rápido](#-inicio-rápido) - [🌟 Descripción General](#-descripción-general) - [📦 Instalación](#-instalación) - [🐳 Docker](#-ejecutar-con-docker) - [🔌 Servidor MCP](#-servidor-mcp-memoria-de-texto) - [📊 Reproducir Resultados del Artículo](#-reproducir-resultados-del-artículo) - [🗺️ Hoja de Ruta](#️-hoja-de-ruta) - [📝 Citación](#-citación) --- ## 🚀 Inicio Rápido ### 🧠 Comprensión del Flujo de Trabajo Básico A grandes rasgos, SimpleMem funciona como un sistema de memoria a largo plazo para agentes basados en LLM. El flujo de trabajo consta de tres pasos sencillos: 1. **Almacenar información** – Los diálogos o hechos se procesan y convierten en memorias estructuradas y atómicas. 2. **Indexar la memoria** – Las memorias almacenadas se organizan mediante embeddings semánticos y metadatos estructurados. 3. **Recuperar memoria relevante** – Ante una consulta, SimpleMem recupera la información almacenada más relevante basándose en el significado en lugar de en palabras clave. Este diseño permite a los agentes LLM mantener el contexto, recordar información pasada de forma eficiente y evitar el procesamiento repetido de historial redundante. ### 🎓 Uso Básico SimpleMem se distribuye como un único paquete `simplemem`. El modo predeterminado `mode="auto"` **detecta automáticamente** qué backend usar en función de lo que invoques — sin necesidad de configuración manual: ```python from simplemem import SimpleMem mem = SimpleMem() # mode="auto" — backend elegido por la primera llamada ``` El primer método que invoques determina el backend: | Primera llamada | Backend seleccionado | Por qué | |:--|:--|:--| | `add_dialogue()` | **Texto** (SimpleMem) | API basada en diálogo → modo texto | | `add_text()` / `add_image()` / `add_audio()` / `add_video()` | **Omni** (Omni-SimpleMem) | API multimodal → modo omni |

**📝 Auto → Texto** (entrada de texto puro) ```python from simplemem import SimpleMem mem = SimpleMem() # auto mode # add_dialogue() → backend de texto seleccionado automáticamente 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** (entrada multimodal) ```python from simplemem import SimpleMem mem = SimpleMem() # auto mode # add_image() → backend omni seleccionado automáticamente 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() ```

> **💡 Consejo**: El modo auto elige el backend más ligero que se adapte a tus datos. Aún puedes usar `mode="text"` o `mode="omni"` de forma explícita si lo prefieres. --- ### 🧬 Avanzado: Optimizar la Configuración de Recuperación Ajusta los hiperparámetros de recuperación sin conexión sobre tu propio conjunto de desarrollo y despliega luego la `Config` resultante para inferencia. Este es un envoltorio delgado sobre el bucle de auto-evolución de EvolveMem: ```python import simplemem from simplemem import SimpleMem, load_config # mem es una instancia de SimpleMem finalizada con memorias ya construidas 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") # Más adelante, despliega con la configuración optimizada config = load_config("my_config.json") mem = SimpleMem(config=config) ``` > EvolveMem ejecuta un ciclo Evaluar → Diagnosticar → Proponer → Guardar impulsado por LLM sobre tus preguntas de desarrollo, ajustando indicadores globales de recuperación (top_k, modo de fusión, verificación de respuestas, rondas de reflexión, ...). Para la versión independiente completa con adaptadores de benchmark y sobreescrituras por categoría, consulta [`EvolveMem/`](../../EvolveMem/). --- ### 🚄 Avanzado: Procesamiento Paralelo Para el procesamiento de diálogos a gran escala, activa el modo paralelo: ```python from simplemem import create mem = create( mode="text", clear_db=True, enable_parallel_processing=True, # ⚡ Construcción de memoria en paralelo max_parallel_workers=8, enable_parallel_retrieval=True, # 🔍 Ejecución de consultas en paralelo max_retrieval_workers=4 ) ``` > **💡 Consejo Pro**: ¡El procesamiento paralelo reduce significativamente la latencia en operaciones por lotes! --- ## 🌟 Descripción General **SimpleMem** es una pila de memoria unificada para agentes LLM, construida sobre un principio: almacenar memoria *semánticamente sin pérdidas* con alta densidad de información, de modo que un agente recuerde más gastando muchos menos tokens. El paquete reúne tres trabajos que comparten este principio pero atacan distintas partes del problema. ### 📝 SimpleMem: el núcleo de eficiencia (texto) La mayoría de los sistemas de memoria imponen un mal compromiso. O bien acumulan pasivamente el historial de interacción en bruto (redundante, voraz en tokens) o ejecutan costosos bucles de razonamiento para filtrar el ruido (lentos, costosos). SimpleMem, en cambio, comprime las interacciones mediante un pipeline de tres etapas: | Etapa | Qué hace | |:--|:--| | **1. Compresión Estructurada Semántica** | Destila interacciones no estructuradas en unidades de memoria compactas (hechos autocontenidos con correferencias resueltas y marcas de tiempo absolutas), cada una indexada a través de múltiples vistas complementarias para una recuperación flexible. | | **2. Síntesis Semántica en Línea** | Fusiona el contexto relacionado dentro de una sesión en representaciones abstractas unificadas, eliminando la redundancia durante la construcción de la memoria y no en el momento de la consulta. | | **3. Planificación de Recuperación Consciente de la Intención** | Infiere la intención de búsqueda tras una consulta para decidir *qué* recuperar y ensamblar un contexto preciso y compacto. | En el benchmark LoCoMo esto proporciona una ganancia media de F1 del 26,4% sobre sistemas anteriores mientras reduce el consumo de tokens en tiempo de inferencia aproximadamente 30 veces. Detalles del mecanismo (capas del índice híbrido, ejemplos de compresión, planificación de recuperación): [**Memoria de texto de SimpleMem →**](../text-memory.md). ### 🧠 Omni-SimpleMem: memoria multimodal (texto, imagen, audio, vídeo) Omni-SimpleMem extiende la filosofía de compresión primero a cuatro modalidades, construida sobre tres principios: **Ingestión Selectiva** (filtrado impulsado por entropía por modalidad), **Recuperación Progresiva** (FAISS + BM25 híbrido con expansión piramidal del presupuesto de tokens) y **Aumento por Grafo de Conocimiento** (razonamiento multimodal de múltiples saltos). En lugar de diseñarse manualmente, su arquitectura fue *descubierta* por un pipeline de investigación autónoma que ejecutó alrededor de 50 experimentos en dos benchmarks, diagnosticando modos de fallo, proponiendo cambios arquitectónicos e incluso reparando errores en el pipeline de datos sin intervención humana en el bucle interno. De manera reveladora, las correcciones de errores y los cambios arquitectónicos contribuyeron más que todo el ajuste de hiperparámetros combinado, llevando el sistema de una línea base naive al estado del arte en LoCoMo y Mem-Gallery. Documentación completa: [**Omni-SimpleMem →**](../../OmniSimpleMem/). ### 🧬 EvolveMem: recuperación auto-evolutiva EvolveMem cierra un punto ciego compartido por casi todos los sistemas de memoria: el contenido almacenado evoluciona, pero la *maquinaria de recuperación* (funciones de puntuación, estrategias de fusión, políticas de generación de respuestas) permanece congelada tras el despliegue. EvolveMem ejecuta un proceso de AutoResearch en bucle cerrado (**Evaluar → Diagnosticar → Proponer → Guardar → Repetir**) en el que un LLM diagnostica fallos por pregunta y propone cambios de configuración, guardados por reversión automática ante regresiones e incentivos de exploración durante el estancamiento. Descubre nuevas dimensiones de recuperación (descomposición de consultas, intercambio de entidades, verificación de respuestas) no presentes en el diseño original, mejora LoCoMo en un 25,7% relativo sobre la línea base más fuerte, y sus configuraciones evolucionadas se transfieren positivamente entre benchmarks. Documentación completa: [**EvolveMem →**](../../EvolveMem/). ### Cómo encajan entre sí `from simplemem import SimpleMem` te proporciona el núcleo de texto con enrutamiento automático al backend multimodal, y `simplemem.optimize(...)` accede a EvolveMem para ajustar la recuperación a tus propios datos. Un paquete, un modelo mental: comprime sin pérdidas, recupera por intención y deja que el sistema siga mejorándose a sí mismo. --- ## 📦 Instalación ### 📝 Notas para Usuarios Primerizos - Asegúrate de estar usando **Python 3.10+ en tu entorno activo**, no solo instalado globalmente. - Se debe configurar una clave API compatible con OpenAI **antes de ejecutar cualquier construcción de memoria o recuperación**, de lo contrario la inicialización puede fallar. - Al usar proveedores que no sean OpenAI (p. ej., Qwen o Azure OpenAI), verifica tanto el nombre del modelo como `OPENAI_BASE_URL` en `config.py`. - Para grandes conjuntos de datos de diálogo, habilitar el procesamiento paralelo puede reducir significativamente el tiempo de construcción de la memoria. ### 📋 Requisitos - 🐍 Python 3.10+ - 🔑 API compatible con OpenAI (OpenAI, Qwen, Azure OpenAI, etc.) ### 🛠️ Configuración ```bash # 📥 Clonar el repositorio git clone https://github.com/aiming-lab/SimpleMem.git cd SimpleMem # 📦 Instalar dependencias (versiones fijadas) pip install -r requirements.txt # — O — instalar como paquete editable pip install -e . # predeterminado: texto + multimodal + evolver pip install -e ".[server]" # + servidor MCP / HTTP (mcp, fastapi, ...) pip install -e ".[all]" # todo, incluidas herramientas de desarrollo # ⚙️ Configurar ajustes de API cp config.py.example config.py # Editar config.py con tu clave API y preferencias ``` ### ⚙️ Ejemplo de Configuración ```python # config.py OPENAI_API_KEY = "your-api-key" OPENAI_BASE_URL = None # o endpoint personalizado para Qwen/Azure LLM_MODEL = "gpt-4.1-mini" EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B" # Recuperación de última generación ``` --- ## 🐳 Ejecutar con Docker El **Servidor MCP** puede ejecutarse en Docker para un entorno consistente y aislado. Los datos (LanceDB y la base de datos de usuarios) se persisten en un volumen del host. ### Requisitos Previos - [Docker](https://docs.docker.com/get-docker/) y [Docker Compose](https://docs.docker.com/compose/install/) ### Ejecución rápida ```bash # Desde la raíz del repositorio docker compose up -d ``` - **Interfaz Web:** http://localhost:8000/ - **API REST:** http://localhost:8000/api/ - **MCP (SSE):** http://localhost:8000/mcp/sse?token=<TOKEN> Los datos se almacenan en `./data` en el host (se crea automáticamente). ### Configuración personalizada 1. Copia la plantilla de entorno y edítala: ```bash cp .env.example .env # Editar .env: establece JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, URLs de modelos, etc. ``` 2. Ejecuta con el archivo de entorno: ```bash docker compose --env-file .env up -d ``` ### Usar Ollama en el host Cuando `LLM_PROVIDER=ollama` y Ollama se ejecuta en tu máquina (no en Docker), establece en `.env`: ```bash LLM_PROVIDER=ollama OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 ``` En Linux, `host.docker.internal` se habilita automáticamente a través del archivo Compose. ### Comandos útiles ```bash docker compose logs -f simplemem # Seguir los registros docker compose down # Detener y eliminar contenedores ``` > 📖 Para alojar el servidor MCP por cuenta propia (Docker o bare metal), consulta la [Documentación MCP](../../MCP/README.md). --- ## 🔌 Servidor MCP *(memoria de texto)* SimpleMem está disponible como **servicio de memoria alojado en la nube** mediante el Model Context Protocol (MCP), permitiendo una integración fluida con asistentes de IA como Claude Desktop, Cursor y otros clientes compatibles con MCP. **🌐 Servicio en la Nube**: [mcp.simplemem.cloud](https://mcp.simplemem.cloud) — o aloja el servidor MCP localmente usando [Docker](#-ejecutar-con-docker). ### Características Principales | Característica | Descripción | |---------|-------------| | **HTTP con Streaming** | Protocolo MCP 2025-03-26 con JSON-RPC 2.0 | | **Aislamiento Multi-inquilino** | Tablas de datos por usuario con autenticación por token | | **Recuperación Híbrida** | Búsqueda semántica + coincidencia de palabras clave + filtrado por metadatos | | **Optimizado para Producción** | Tiempos de respuesta más rápidos con integración de OpenRouter | ### Configuración Rápida ```json { "mcpServers": { "simplemem": { "url": "https://mcp.simplemem.cloud/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` > 📖 Para instrucciones de configuración detalladas y guía de auto-alojamiento, consulta la [Documentación MCP](../../MCP/README.md) --- ## 📊 Reproducir Resultados del Artículo Reproduce los números de LoCoMo / MemBench / Mem-Gallery de los artículos. Cada pilar tiene su propio ejecutor de benchmark en su propio directorio. Instala primero los extras de benchmark: `pip install -e ".[benchmark]"`. ### 📝 SimpleMem (texto) — LoCoMo Ejecuta desde la raíz del repositorio: ```bash python test_locomo10.py # benchmark completo de LoCoMo python test_locomo10.py --num-samples 5 # subconjunto rápido python test_locomo10.py --result-file my_results.json ``` ### 🧬 EvolveMem — auto-evolución + LoCoMo / MemBench Ejecuta desde el directorio `EvolveMem/` (consulta [`EvolveMem/README.md`](../../EvolveMem/README.md)): ```bash 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 Ejecuta desde el directorio `OmniSimpleMem/` (consulta [`OmniSimpleMem/README.md`](../../OmniSimpleMem/README.md)): ```bash cd OmniSimpleMem python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o ``` --- ## 🗺️ Hoja de Ruta Capacidad actual por canal de integración: | Capacidad | Python (`pip install`) | Servidor MCP (Claude Desktop, Cursor, ...) | |:--|:--:|:--:| | Memoria de texto | ✅ | ✅ | | Multimodal (imagen / audio / vídeo) | ✅ | ⬜ planificado | | Recuperación auto-evolutiva `optimize()` | ✅ | ⬜ planificado | Trabajo planificado para cerrar la brecha (el servidor MCP es un servicio de texto multi-inquilino independiente; estas son características reales, no correcciones de documentación): - [ ] **Multimodal sobre MCP.** Añadir herramientas `memory_add_image` / `memory_add_audio` / `memory_add_video`. Requiere una ruta de carga de archivos (base64 o URL, ya que MCP no puede pasar rutas de archivos locales), una adaptación multi-inquilino del backend de almacenamiento de Omni-SimpleMem y acceso a modelos de visión/audio en el servidor. - [ ] **EvolveMem sobre MCP.** Exponer `optimize()` como herramienta MCP. Más tratable que el multimodal (texto de entrada, configuración JSON de salida, sin transporte de archivos), pero el recuperador MCP actualmente solo respeta `semantic_top_k` / `keyword_top_k` de las ~10 dimensiones que EvolveMem evoluciona. Requiere extender el recuperador MCP para soportar los controles restantes (structured top_k, modo/pesos de fusión, intercambio de entidades, descomposición de consultas, verificación de respuestas), un adaptador para ejecutar el bucle de evolución sobre las memorias almacenadas de un inquilino, persistencia de configuración por inquilino y ejecución asíncrona (el bucle es intensivo en LLM y agotaría el tiempo de espera de una solicitud síncrona). - [ ] **Docker** hereda ambos automáticamente una vez que el servidor MCP los soporte (añade dependencias multimodales a la imagen y un volumen de almacenamiento Omni). Para multimodal completo y recuperación auto-evolutiva hoy, usa la API de Python (consulta [Inicio Rápido](#-inicio-rápido)). --- ## 📝 Citación Si utilizas SimpleMem en tu investigación, cita: ```bibtex @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} } ``` ```bibtex @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} } ``` ```bibtex @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}, } ``` --- ## 📄 Licencia Este proyecto está licenciado bajo la **Licencia MIT** - consulta el archivo [LICENSE](../../LICENSE) para más detalles. --- ## 🙏 Agradecimientos Queremos agradecer a los siguientes proyectos y equipos: - 🔍 **Modelo de Embeddings**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) - Rendimiento de recuperación de última generación - 🗄️ **Base de Datos Vectorial**: [LanceDB](https://lancedb.com/) - Almacenamiento columnar de alto rendimiento - 📊 **Benchmark**: [LoCoMo](https://github.com/snap-research/locomo) - Marco de evaluación de memoria de contexto largo