Cómo funciona la base de conocimiento

La base de conocimiento guarda lo que la IA debe saber de tu negocio y no puede aprender del propio correo: precios, políticas, horarios de apertura, datos de productos y la forma en que responde tu equipo. Tú añades notas, archivos y páginas web, y la IA lee las partes que importan cada vez que escribe por ti.

Hay un almacén por espacio de trabajo, con tres niveles, para que una respuesta que solo vale para una marca o un equipo se quede con ellos. Se lee y se cambia en la aplicación en Espacio de trabajo → Base de conocimiento, mediante la API REST, desde los SDK y la CLI, y con el asistente y los clientes MCP.

Cada elemento está en un nivel, su scope. La IA que escribe para una dirección lee esa dirección, luego su dominio y luego todo el espacio de trabajo, y cuando dos elementos se contradicen gana el más específico.

• —Una dirección con signo más lee también su dirección base, así que [email protected] usa lo que se guarda para [email protected].
• —GET /knowledge/levels lista cada nivel que puedes ver, cuántos elementos tiene cada uno y si puedes cambiar elementos ahí.
• —Mover un dominio a otro espacio de trabajo se lleva con él los elementos guardados para ese dominio y sus direcciones.

• —Una nota es texto que escribes en el sitio, hasta 20.000 caracteres, en Markdown si quieres. Suele estar lista para la IA en un segundo o dos.
• —Un archivo se lee como texto en segundo plano: PDF, documentos de Word, hojas de cálculo (Excel, OpenDocument, Numbers y CSV), texto de OpenDocument, HTML, XML, Markdown, texto sin formato, JSON e imágenes (JPEG, PNG, WebP y SVG). Un documento puede tener hasta 20 MB y una imagen hasta 10 MB.
• —Una página web se obtiene de una dirección http o https pública y se lee en segundo plano, hasta 5 MB de ella. Un nivel guarda una página una sola vez, y actualizarla la vuelve a obtener después de que cambie.
• —De un elemento se guardan hasta 1.000.000 de caracteres de texto, y el texto se divide en fragmentos bajo sus encabezados para la búsqueda.

Un elemento está queued y luego processing mientras se lee, ready cuando la IA ya puede usarlo, y failed con un failure que dice por qué cuando no se pudo leer. Un elemento cambiado vuelve a queued, y la IA sigue usando su texto anterior hasta que el nuevo está listo. Actualizar un elemento lo vuelve a leer y borra un fallo.

• —Las sugerencias de respuesta bajo el último mensaje de un hilo leen los niveles de la dirección a la que llegó el mensaje.
• —Un borrador escrito a partir de una descripción, en el editor o con POST /emails/compose, lee los niveles de la dirección desde la que sale. La respuesta lista en sources los elementos en los que se basó.
• —El asistente lee los niveles del hilo que tienes abierto, o cada nivel que puedes ver cuando no hay ninguno abierto, y puede buscar él mismo en la base de conocimiento con su herramienta searchKnowledge.
• —La respuesta de GET /threads/{id}/reply-suggestions enumera en sources los elementos en los que se basaron las sugerencias.

Las notas fijadas entran en cada prompt de su nivel, hasta 2.000 caracteres por nivel, coincidan o no con lo que se escribe. El resto del espacio, unos 6.000 caracteres en total, va a los fragmentos que mejor encajan con la petición, encontrados por significado y por palabras. Cuando el índice no responde en un momento, la IA escribe sin él en lugar de hacerte esperar.

Añade elementos en la aplicación en Espacio de trabajo → Base de conocimiento, o desde código con la API, los SDK y la CLI. El asistente y los clientes MCP pueden guardar una nota o añadir un enlace cuando les pides que recuerden algo, y también pueden cambiar, actualizar y eliminar elementos. En el chat de la aplicación, añadir, cambiar y actualizar un elemento preguntan antes salvo que lo hayas pedido tú, y eliminarlo siempre pregunta antes.

Cada elemento registra de dónde vino en origin: app, api, assistant o mcp, y quién lo añadió en createdBy.

También crece por sí sola. La IA sugiere notas a partir de las respuestas de tu equipo y anota las preguntas que nada responde todavía, los conectores mantienen al día sitios enteros, sitemaps, feeds y centros de ayuda, y los enlaces pueden volver a leerse según un calendario. Las secciones siguientes explican cada uno.

Cuando alguien del espacio de trabajo responde en una conversación, la IA lee la respuesta y el mensaje al que responde, y sugiere hasta tres datos que servirían también para otras personas, como un precio, una política o un plazo de entrega. Cada sugerencia es una nota pendiente de revisión, en el nivel del dominio desde el que se envió la respuesta, o en todo el espacio de trabajo cuando ese dominio no es uno de los suyos. Se omiten los datos que la base de conocimiento ya tiene, y se leen hasta 100 respuestas al día.

Revísalas en la aplicación o con GET /knowledge/suggestions. Acepta una para guardarla como nota, cambiando de paso su título, su texto, su nivel o si está fijada, o descártala. El mismo dato sugerido otra vez suma en occurrences en lugar de añadir una segunda sugerencia, y una descartada no se vuelve a sugerir.

Cuando la IA sugiere respuestas a un mensaje entrante, también anota hasta tres cosas que el remitente preguntó sobre el negocio y que ni la conversación ni la base de conocimiento responden, como si envías a su país. Cada una se convierte en una pregunta en el nivel del dominio al que llegó el mensaje, o en todo el espacio de trabajo cuando ese dominio no es uno de los suyos, y la misma pregunta hecha otra vez suma en occurrences, para que veas cuáles salen más.

Responde una pregunta y se convierte en una nota: acéptala con la respuesta como texto, y su título sigue siendo la pregunta salvo que lo cambies. Desde entonces la IA usa la respuesta siempre que surge la pregunta. Descarta una pregunta que no necesita respuesta y no se vuelve a anotar.

Cada elemento se compara con los elementos más parecidos de todos los niveles cuando se indexa, y otra vez cada vez que cambia. Dos elementos que dicen casi lo mismo se marcan como duplicate. Dos elementos muy relacionados que no coinciden en un dato, como un precio o un plazo, se marcan como conflict, con una frase sobre lo que no coincide. La IA busca conflictos hasta 200 veces al día.

• —Cada elemento cuenta en flags los avisos abiertos que lo nombran, y GET /knowledge/flags los enumera, del más reciente al más antiguo.
• —Cambia o elimina uno de los dos elementos para resolver un aviso. Un elemento cambiado se vuelve a comparar en cuanto se indexa.
• —Descarta un aviso cuando los dos elementos están bien como están, y el mismo par no se vuelve a marcar por el mismo motivo.
• —Un aviso solo lo ve quien puede ver los dos elementos.

Un conector mantiene muchas páginas de una misma fuente en la base de conocimiento, cada página como un elemento de enlace en el nivel del conector, y las mantiene al día cuando la fuente cambia.

• —La primera sincronización empieza en menos de un minuto. Después se sincroniza de nuevo cada 7 días, o cada 1 o 30 días, o solo cuando pides una sincronización, que también empieza en menos de un minuto.
• —Guarda hasta 25 páginas, o tantas como indiques hasta 200, y sus elementos cuentan para la cuota del plan. Una sincronización deja de añadir páginas en cuanto se alcanza la cuota.
• —Cada sincronización añade las páginas nuevas, vuelve a leer las que cambiaron y quita los elementos de las páginas que ya no están en la fuente.
• —Una página que añadiste tú como enlace en el mismo nivel se queda con ese elemento, y eliminar un conector quita solo los elementos que añadió él.
• —Mover un conector a otro nivel mueve sus elementos con él.

Un enlace puede volver a leerse por sí solo cada 1, 7 o 30 días: indica refreshDays al añadirlo, o más tarde. Cuando la página ha cambiado, su texto nuevo sustituye al antiguo en cuanto se lee, y hasta entonces la IA sigue usando el texto antiguo. nextRefreshAt dice cuándo se leerá la próxima vez, y una página que no se puede obtener se vuelve a intentar al día siguiente.

La IA puede leer una conversación y redactar una nota con los datos que el equipo volverá a necesitar, sin los datos personales ni lo que solo importa en esa conversación. No se guarda nada hasta que lo conservas: lee el borrador, cámbialo como quieras y guárdalo como nota, que registra en threadId la conversación de la que viene.

El borrador sugiere un nivel: el dominio al que llegó la conversación si puedes añadir elementos ahí, y si no, todo el espacio de trabajo o la dirección. Cada borrador es una acción de IA. Desde código, redacta con POST /knowledge/drafts, que necesita threads:read además de knowledge:write, y guarda con POST /knowledge/notes y el mismo threadId.

Una búsqueda encuentra fragmentos por significado y por palabras. Envía rerank: true con POST /knowledge/search y la IA también lee los 25 mejores fragmentos y los pone en el orden que mejor responde a la pregunta, dejando fuera los que no ayudan. Añade uno o dos segundos y es una acción de IA, por eso solo se hace cuando lo pides. reranked en la respuesta dice si se hizo, y cuando no termina a tiempo los fragmentos mantienen su orden habitual.

GET /knowledge/stats muestra cómo usó la IA la base de conocimiento en los últimos 30 días, o hasta 90 si lo pides.

• —Cuántas veces una sugerencia de respuesta, un borrador, el asistente o una búsqueda encontró algo, cuántas buscó y no encontró nada, y la proporción que encontró algo, día a día.
• —Dónde ocurrieron esos usos: compose, reply, chat, tool y search.
• —Los elementos más usados, y cuántos elementos listos no se usaron nunca. Cada elemento lleva su propio recuento en uses, con lastUsedAt como el último.
• —Cuántas sugerencias y preguntas esperan revisión, y cuántos avisos están abiertos.

El ajuste del espacio de trabajo knowledgeLearning está activado por defecto. Desactívalo con PATCH /settings y { "knowledgeLearning": false } y la IA deja de leer las respuestas enviadas en busca de datos que sugerir, deja de anotar preguntas del correo entrante y deja de revisar los elementos en busca de conflictos. Los duplicados se siguen marcando, y lo que ya se sugirió sigue ahí para que lo aceptes o lo descartes.

• —Leer requiere knowledge:read y cambiar knowledge:write, que incluye la lectura. Los roles integrados Admin, Member y Developer pueden cambiar elementos, Viewer puede leerlos, y Billing no los alcanza.
• —Cambiar un elemento requiere alcanzar cada dirección que cubre su nivel: todo el espacio de trabajo requiere todas las direcciones, un dominio el dominio entero, y una dirección esa dirección. Una clave o una aplicación limitada a ciertas direcciones solo puede cambiar elementos en esas direcciones, o en dominios que tiene enteros.
• —Quien está limitado a ciertas direcciones lee los elementos de todo el espacio de trabajo y los de sus direcciones y los dominios de esas direcciones. El asistente y las herramientas MCP que actúan por esa persona solo añaden y cambian elementos en las direcciones desde las que puede enviar.

• —El texto de cada elemento se cifra en reposo: el contenido de una nota, el texto leído de un archivo o una página, y cada fragmento. Las palabras que compara la búsqueda por palabras se guardan como hashes con clave, no como palabras.
• —Los archivos se convierten en texto y OpenEmail lee las páginas web. La política de privacidad indica cada servicio que trata tus datos.
• —Para buscar por significado, cada fragmento y cada pregunta se convierten en un vector: una lista de números que describe de qué trata. Los vectores se guardan sin cifrar junto al texto cifrado, igual que en la búsqueda por significado del correo.
• —Los fragmentos que usa un prompt van al modelo de IA que escribe la respuesta, el borrador o la contestación, como el resto del prompt.
• —Eliminar un elemento quita a la vez su archivo, su texto y sus fragmentos. La base de conocimiento forma parte de una exportación del espacio de trabajo, y eliminar el espacio de trabajo la elimina.
• —Mientras el aprendizaje está activado, el modelo de IA lee cada respuesta enviada en una conversación, con el mensaje al que responde, para sugerir notas, y lee dos elementos muy relacionados para comprobar si se contradicen. El ajuste knowledgeLearning desactiva ambas cosas.

Todo lo anterior está en la API REST bajo /knowledge, en los SDK como openemail.knowledge (TypeScript) y client.knowledge (Python, Ruby y PHP), en la CLI como openemail knowledge, y en las herramientas MCP. Una clave necesita knowledge:read para leer y knowledge:write para cambiar elementos.