mnemiq

mnemiq

Text-to-SQL que puedes ajustar a tu base de datos. /NEM-ik/ — la "m" es muda, como en mnemónico.

Un motor de código abierto que responde preguntas en lenguaje natural sobre tu base de datos, construido para que cada etapa entre la pregunta y el SQL sea un ajuste que puedas leer, cambiar y medir.

Dos respuestas y una negativa. La tercera pregunta pide ingresos que la base de datos no contiene, y el motor lo dice — nombrando las columnas que habría necesitado — en lugar de devolver un número que parece correcto. Esa distinción es todo el diseño.

Leer más · Artículo de lanzamiento · Informe técnico (PDF) · Artículo (PDF) · beacon — el calificador y el rastreador de resultados

Por qué existe mnemiq

Cada producto de text-to-SQL tiene una cifra de precisión. Casi ninguno fue medido en una base de datos que se parezca a la tuya.

Un sistema puede funcionar bien en un benchmark y luego tener dificultades con tu almacén porque el esquema es más grande, los nombres son diferentes, las definiciones de negocio viven en las cabezas de las personas, o la configuración que funcionó para el benchmark simplemente no se adapta a tus datos. Cuando rinde por debajo de lo esperado, un sistema cerrado no te da forma de descubrir por qué, y nada que puedas cambiar.

Entonces, la pregunta que vale la pena hacer no es qué tan preciso es. Es:

¿Qué tan bien funcionará esto en mi base de datos — y qué puedo cambiar si no funciona?

mnemiq está construido para que ambas mitades sean respondibles. Es Apache-2.0, se ejecuta dentro de tu propio entorno en modelos que tú eliges, y expone las partes principales del pipeline como ajustes en lugar de internals. Ninguna cifra de precisión se aplica a tu base de datos hasta que la hayas ejecutado en tu base de datos; mnemiq es el motor y el arnés de evaluación para hacer eso.

Cómo funciona

mnemiq separa escribir SQL de decidir ejecutarlo. Un modelo propone una consulta. Una capa determinista luego decide sobre ella antes de que algo toque la base de datos. La consulta debe ser de solo lectura, solo puede hacer referencia a objetos que el llamador tiene permitido ver, tiene que compilar en el dialecto SQL propio de la fuente, y tiene que sobrevivir a un EXPLAIN. Si falla cualquiera de esos, obtienes una negativa con una razón declarada en lugar de un número plausible.

Dos propiedades se derivan de ese orden. Los permisos se aplican antes de la recuperación del esquema, por lo que el modelo nunca ve una tabla que el llamador no pueda ver — nombrarla es inútil en lugar de rechazada. Y cada respuesta lleva un rastro: el SQL que se ejecutó, las tablas que tocó, la versión de enriquecimiento detrás de él.

Lee el diagrama de izquierda a derecha, de arriba a abajo. Las etapas en rojo son las que pueden detener una respuesta: el decisor rechaza o repara, la ejecución se realiza bajo política, y la verificación puede diferir. El modelo aparece una vez, en la etapa 05, y todo lo que lo rodea es determinista.

El pipeline son ajustes, no internals

Las partes que la gente normalmente no puede alcanzar son las partes que mnemiq pone en tus manos:

• Qué modelo escribe el SQL — alojado o local, un candidato o varios.
• Cuánto contexto de esquema se recupera, y cómo se clasifica.
• Cuánto enriquecimiento semántico se construye, y si un humano lo certifica.
• Qué tan agresivamente el sistema rechaza — el verificador y su umbral.
• Qué aplica el decisor, incluyendo la política de filas y columnas aplicada al árbol de consulta en lugar de solicitada al modelo.

Cada uno de esos es un dial con un costo al otro lado, por eso son diales y no valores predeterminados. Más contexto no es gratis. Más cómputo no es automáticamente mejor. El ajuste correcto depende de tus datos, y el punto del arnés es que puedas descubrirlo en lugar de adivinar.

La capa semántica tiene niveles

Antes de que se haga cualquier pregunta, mnemiq puede inspeccionar la base de datos y construir contexto alrededor del esquema:

• Nivel 0 — solo tablas y columnas.
• Nivel 1 — agrega información estructural: claves primarias y foráneas, perfilado, distribuciones de valores.
• Nivel 2 — agrega significado que un LLM propone: descripciones de tablas y columnas, granularidad, términos de glosario, significados de valores codificados.

El enriquecimiento es un multiplicador de significado que no ya está en el esquema. Donde los nombres de columnas ya dicen lo que contienen, tarjetas más ricas agregan longitud sin agregar señal. Donde tres columnas se llaman todas revenue por tres equipos diferentes, el significado está en una persona, no en el esquema — y eso es exactamente lo que captura una definición certificada. Para uso en producción, las definiciones pueden ser revisadas y certificadas por un propietario nombrado, y el diccionario del operador anula todo lo que el modelo propuso.

Los códigos están fundamentados o se dejan desnudos, nunca se adivinan. E11 o NC-17 toman su significado de los datos en sí, de un sistema de códigos estándar (TTL/SKOS/OWL), o de un diccionario escrito a mano, con la fuente registrada. Sin evidencia, sin significado. Ver docs/grounding.md.

Mídelo en tu propia base de datos

El arnés de evaluación es parte del motor, no un proyecto de investigación separado. Ejecuta un conjunto de preguntas contra una configuración, califica los resultados por los datos devueltos en lugar de hacer coincidir cadenas del SQL, e informa correcto, rechazado e incorrecto como tres números separados — porque un sistema puede comprar precisión respondiendo con menos frecuencia, y una sola cifra oculta eso.

Un primer paso útil, en tus datos:

• Toma un segmento significativo de tu esquema, no todo el almacén.
• Escribe 20–30 preguntas que la gente realmente hace, y etiqueta cada una: respondible desde nombres de columnas, necesita una definición, debería ser rechazada.
• Ejecútalo con enriquecimiento activado y desactivado, un modelo local y uno alojado, el verificador en dos umbrales.
• Lee el resultado por etiqueta. Las etiquetas son el diagnóstico: si las preguntas de la banda de definición fallan mientras las de la banda de esquema pasan, tienes un problema de glosario y la documentación se pagará sola. Si ambas ya pasan, estabas a punto de gastar un trimestre en algo que vale muy poco.

El mismo arnés ejecuta los benchmarks públicos (BIRD mini-dev, Spider 1.0, Spider 2.0-lite) y los scripts de comparación de almacenes bajo scripts/, por lo que la configuración que usas en tus datos es la configuración de la que provienen los números publicados.

La calificación en sí vive en beacon, un repositorio separado Apache-2.0: el calificador que decide qué cuenta como correcto, y el rastreador que guarda cada ejecución detrás de las cifras publicadas. Mantenerlo fuera del motor es deliberado — un sistema no debería calificar su propia tarea, y el mismo calificador puntúa a mnemiq, Snowflake Cortex Analyst y Databricks Genie en la comparación. Los resultados por pregunta se publican allí, por lo que un número en el artículo de lanzamiento se puede rastrear hasta el SQL y las filas que lo produjeron.

Inicio rápido

Se ejecuta en un clon limpio sin base de datos propia y sin Docker. El paso de semilla escribe una pequeña base de datos SQLite más su manifiesto de fuente y política de acceso bajo demo/.

uv sync
uv run python scripts/seed_demo.py

export MNEMIQ_LLM_BASE_URL=...  MNEMIQ_LLM_API_KEY=...  MNEMIQ_LLM_MODEL=...
export MNEMIQ_SOURCES_PATH=demo/sources.json
export MNEMIQ_AUTHZ_PATH=demo/authz.json
export MNEMIQ_STORE_PATH=demo/store.duckdb

uv run mnemiq enrich      # profile + describe the schema  (~30 s on the demo's 4 tables)
uv run mnemiq build       # index it for retrieval          (~2 s)
uv run mnemiq ask "how many customers are there by country?" --roles analyst

uv sync descarga alrededor de 230 MB de dependencias en una primera ejecución — DuckDB, PyArrow y el cliente OpenAI son la mayor parte — así que dale un minuto en una conexión normal. Es casi instantáneo en cualquier checkout posterior, ya que uv almacena en caché los wheels globalmente.

mnemiq enrich es el único paso lento: perfila cada columna y hace una pasada de LLM sobre el esquema, así que espera aproximadamente 30 segundos para las cuatro tablas de la demo y más en proporción a las tuyas. No imprime nada hasta que cada tabla se completa — está trabajando, no colgado. El resultado está en caché, por lo que lo pagas una vez por esquema en lugar de por pregunta.

Dos más que vale la pena probar, porque muestran las partes que no son el modelo:

uv run mnemiq ask "how many enterprise customers are there?" --roles analyst
uv run mnemiq ask "what was our total revenue last quarter?"   --roles analyst

El primero une a través de una tabla de búsqueda para resolver una columna codificada — segment_cd contiene A/B/C y nada en el nombre dice "enterprise". El segundo es rechazado: el esquema de la demo no tiene columna de precio o ingresos, y el motor lo dice en lugar de devolver un número.

El acceso es de cierre ante fallos. --roles analyst es requerido — sin un rol el motor no concede nada y difiere, que es el comportamiento correcto y lo primero que la gente confunde con un error. Sin política, sin concesiones, sin snapshot — sin datos.

Qué endpoints de LLM funcionan

Cualquier endpoint /v1 compatible con OpenAI. mnemiq habla con MNEMIQ_LLM_BASE_URL a través del cliente estándar de OpenAI, por lo que vLLM, Ollama, el servidor de llama.cpp, LM Studio, pasarelas de proveedores y las APIs alojadas funcionan todos — configura la URL base, una clave (cualquier cadena no vacía para servidores locales que la ignoren) y un nombre de modelo. Nada sobre el motor asume un proveedor alojado, que es lo que "se ejecuta dentro de tu perímetro" significa en la práctica: apúntalo a un servidor local y ningún esquema, ninguna pregunta y ninguna fila sale de tu red. Los embeddings siguen el mismo ajuste, o el suyo propio a través de MNEMIQ_EMBED_*.

Úsalo desde un navegador (workbench)

cd workbench && pnpm install && pnpm build
uv run mnemiq serve --http     # http://127.0.0.1:8080

Un proceso sirve tanto al workbench como a la API HTTP — POST /v1/ask (JSON), POST /v1/chat (SSE, vocabulario de eventos AG-UI), GET /v1/schema. Cada respuesta muestra el SQL que la produjo y las tablas que leyó; una pregunta que los datos no pueden soportar vuelve como una razón declarada, no una suposición — esa es la interfaz que se muestra en la parte superior de este archivo. Ver workbench/README.md.

Úsalo desde un agente de IA (MCP)

uv run mnemiq serve expone dos herramientas de solo lectura, con alcance de acceso, sobre stdio — db_read(question) (respuesta + SQL + rastro) y get_schema(). Apunta cualquier cliente MCP a él:

{ "mcpServers": { "mnemiq": { "command": "mnemiq", "args": ["serve"] } } }

Fuentes

Postgres, SQLite, DuckDB, Oracle, Snowflake y Databricks, con DuckDB como ejecutor universal. El modelo semántico (mnemiq-contract) es abierto, y la importación/exportación de dbt-semantic-interfaces se incluye con él.

Despliegue contra Oracle

El plano de lectura de Oracle rechaza escrituras, pero ese rechazo es en parte una propiedad de tu despliegue en lugar del motor: un SELECT puede alcanzar una función AUTONOMOUS_TRANSACTION a través de una vista, y restringir al llamador no lo cierra, porque una vista resuelve sus referencias con los derechos del propietario de la vista. Apuntar el plano de lectura a una base de datos que está abierta en solo lectura sí lo cierra, medido, y mnemiq informa al arrancar si estás en ese despliegue o descansando solo en la puerta del motor. Ver docs/oracle-deployment.md antes de conectar una fuente de producción.

Qué es comercial

El motor es Apache-2.0 y siempre lo será — enriquecimiento incluido. Nada aquí es una compilación con límite de tiempo o con funciones restringidas, y ninguna capacidad está incompleta pendiente de una clave de licencia.

Específicamente abiertos, porque estas son las partes que la gente asume que se retienen: el pipeline de enriquecimiento incluyendo la pasada de LLM y la fundamentación de valores codificados (src/mnemiq/enrichment/), el verificador y su juez (src/mnemiq/verify/), los controles de acceso (src/mnemiq/authz/, src/mnemiq/sql/), el calificador de resultados (src/mnemiq/eval/grade.py), y el arnés de benchmark que produjo los números publicados (scripts/).

Comerciales son dos cosas que se sientan alrededor del motor en lugar de dentro de él: Verity, un servicio gestionado de calificación y deriva, y el plano de control Agentic Fabriq — identidad, credenciales guardadas en bóveda, concesiones por grupo y auditoría en muchas fuentes. Ambos hablan con el motor a través del contrato abierto (mnemiq-contract), por lo que un despliegue autoalojado no es uno degradado; es el mismo camino de lectura sin un servicio gestionado delante de él.

Lee el código en lugar de tomar esto por confianza — ese es el punto de publicarlo.

Debilidades conocidas

Registrados como problemas abiertos en lugar de dejarlos para descubrir, porque son legibles en el código fuente de cualquier manera: el verificador falla abierto cuando su juez es inalcanzable, la verificación está desactivada por defecto a pesar de ser la única palanca medida para reducir la tasa de errores, MNEMIQ_ROLES es ignorado por la CLI, y los informes de linaje reportan unconfirmed-function-identity en consultas ordinarias. Contribuciones y argumentos bienvenidos sobre los cuatro.

Estado

v0.1: la ruta de lectura completa — enriquecimiento, recuperación, el decisor, ejecución, traza — evaluada en ACME, BIRD mini-dev, Spider 1.0 y Spider 2.0-lite, con un programa de modelo local junto a ella. Los modos escalonados (instant / thinking / deep), la seguridad a nivel de fila y columna, la ruta de escritura gobernada, la federación entre fuentes y el despliegue multi-réplica están construidos y conectados detrás de las mismas interfaces. Siguiente: adaptadores de fuente adicionales, los bucles de auto-mantenimiento y el endurecimiento del plano de escritura contra una fuente de producción.