Cómo BibGenie compacta el contexto

Toda conversación de investigación prolongada acaba encontrando una restricción inevitable: la ventana de contexto del modelo es finita.

Esta limitación se hace especialmente visible en Zotero. Una sola sesión puede abarcar búsquedas bibliográficas, lectura de PDF, extracción de citas, organización de notas, llamadas a herramientas y correcciones sucesivas. A medida que crece el historial, reenviarlo por completo resulta cada vez más costoso y, finalmente, supera la capacidad del modelo. Eliminar sin más los mensajes antiguos no es una solución válida: al principio de la conversación suelen encontrarse el objetivo de investigación, las fuentes clave, las restricciones y las decisiones de las que depende el trabajo posterior.

La función Context Compaction de BibGenie resuelve este problema. Convierte el contexto anterior en un checkpoint de investigación estructurado, al tiempo que conserva el historial completo y una cola reciente de mensajes en su forma original. De este modo, el modelo recibe un contexto de trabajo más pequeño y denso, sin perder de vista lo que ya se hizo ni lo que debe hacerse después.

Este artículo explica las decisiones de ingeniería que sustentan el diseño.

Por qué una solicitud del agente sigue creciendo

Una interfaz de chat parece añadir mensajes uno tras otro, pero el modelo no recuerda automáticamente la solicitud anterior. Cada petición debe volver a incluir el contexto necesario. Las llamadas a herramientas, las lecturas de PDF y las búsquedas en Zotero hacen crecer ese contexto hasta que el proveedor rechaza la siguiente petición por superar la ventana de contexto.

En ese punto hay dos opciones: iniciar una conversación nueva sin historial o convertir el contexto existente en una representación más pequeña que siga permitiendo trabajar. Compact utiliza la segunda opción.

Gestionar el contexto no significa borrar los mensajes más antiguos

Las soluciones más obvias son conservar solo los últimos N mensajes o empezar a borrar desde el principio al alcanzar un límite. Ninguna es fiable para un agente de investigación.

En primer lugar, el número de mensajes no guarda una relación estable con el número de tokens. Un simple «continúa» puede ocupar unos pocos, mientras que una lectura de PDF o el resultado de una herramienta puede contener miles. Recortar por cantidad de mensajes no refleja la carga real que debe procesar el modelo.

En segundo lugar, antiguo no significa irrelevante. El objetivo de investigación, los criterios de inclusión, los artículos indicados, el estilo de cita y las decisiones fundamentales suelen aparecer al inicio. Si se eliminan, el agente puede recordar la última frase, pero olvidar por qué empezó el trabajo.

Por último, una conversación con un agente no es una lista de texto. Un proceso de investigación completo también puede contener:

• llamadas a herramientas y sus resultados;
• claves de elementos de Zotero, adjuntos y localizadores;
• correcciones a conclusiones anteriores;
• intentos fallidos que no deben repetirse;
• tareas pendientes e hipótesis por verificar;
• contenido multimodal, como imágenes.

Compact no puede limitarse a truncar. Debe reorganizar la información de forma controlada: descartar detalles de proceso sustituibles y preservar el estado necesario para continuar.

BibGenie define Compact así:

La diferencia es esencial: se compacta el contexto que se enviará en la próxima solicitud, no el historial del usuario.

Del historial completo a «Checkpoint + Recent Tail»

Supongamos que una sesión contiene tres turnos:

U1 → A1 → U2 → A2 → U3 → A3

Después de Compact, BibGenie no elimina ni reescribe estos nodos. Añade un checkpoint interno C1 al final de la sesión activa:

U1 → A1 → U2 → A2 → U3 → A3 → C1
                              ↑
                    hoja duradera de la sesión

C1 guarda el resumen del contexto anterior. Su campo firstKeptMessageId apunta al primer mensaje que debe conservarse literalmente. Si el límite es U3, la siguiente solicitud al modelo contiene:

C1.summary → U3 → A3

Tras una nueva pregunta del usuario, el contexto pasa a ser:

C1.summary → U3 → A3 → U4

Así se crean dos vistas compatibles:

• Historial duradero: la base de datos y la interfaz conservan la cadena completa U1 → A1 → … → C1 → U4.
• Proyección del modelo: el modelo recibe solo el checkpoint más reciente, la cola reciente sin modificar y los mensajes posteriores al checkpoint.

La clave no es acortar una cadena de texto, sino separar un historial completo y auditable de una memoria de trabajo densa para el modelo.

Cuándo se ejecuta Compact

BibGenie ofrece tres puntos de entrada. Los tres comparten la misma resolución de modelo, estimación de capacidad y lógica de umbrales.

1. Activación manual

El usuario puede seleccionar Compact cuando termina una fase de investigación y quiere organizar el contexto antes de pasar a la siguiente.

La compactación manual no está limitada por el umbral automático. Se comporta como una orden explícita de crear un checkpoint en ese momento:

• Antes del primer checkpoint, una sesión corta puede compactarse cuando contiene al menos dos turnos: el primero se resume y el segundo permanece literal.
• Si ya existe un checkpoint y aparecen nuevos mensajes después, se puede crear uno actualizado a partir del resumen anterior aunque el límite retenido no tenga que avanzar. Si avanza, el historial recién excluido se incorpora al resumen.
• Si la sesión solo contiene un turno que no se puede compactar, o el checkpoint más reciente ya es la hoja de la rama, la operación se considera un no-op correcto en lugar de mostrar un error poco útil.

Así pueden marcarse hitos de investigación significativos sin tratar «no hay nada que compactar» como un fallo.

2. Comprobación automática después de un turno

Una vez persistida correctamente la respuesta final del asistente, BibGenie comprueba la ocupación actual del contexto. Si se aproxima al límite seguro, inicia Compact de forma proactiva.

Al sacar este trabajo de la siguiente ruta de envío, normalmente el usuario no tiene que esperar a que se genere un resumen antes de formular otra pregunta.

La comprobación solo se ejecuta cuando la sesión está estable. Si sigue pendiente una llamada a herramienta, un resultado o una aprobación del usuario, Compact se omite para no fijar un flujo incompleto en un checkpoint.

3. Preflight antes de enviar

La comprobación posterior al turno mejora la latencia, pero el preflight previo al envío es la última frontera de corrección.

Antes de que un nuevo mensaje entre en el estado de AI SDK, BibGenie lo añade temporalmente a la proyección y estima la siguiente solicitud. Así detecta un texto pegado de gran tamaño, una imagen adjunta o un cambio a un modelo con una ventana de contexto menor.

Si la solicitud sigue siendo demasiado grande después de Compact, BibGenie no envía al proveedor una petición destinada a fallar. Conserva el borrador y pide al usuario que lo reduzca.

Decidir por capacidad del modelo, no por número de mensajes

Los modelos difieren en ventana de contexto y longitud máxima de salida. Por ello, BibGenie no aplica un único umbral global.

La relación básica es:

Límite de entrada seguro = Ventana de contexto - Tokens reservados

La reserva deja espacio para la siguiente respuesta y se calcula a partir de la ventana del modelo activo. Los modelos de gran contexto pueden reservar una salida más amplia; los pequeños reducen la reserva en lugar de heredar una constante global inadecuada.

El presupuesto del Recent Tail también se adapta a la capacidad. Compact no aplana toda la conversación reciente solo para ahorrar tokens, pero tampoco conserva una cola que no cabe en un modelo más pequeño.

El límite se elige siempre al inicio de un turno completo del usuario; nunca divide una respuesta del asistente ni un resultado de herramienta. Si un único turno asistente/herramienta ya supera el presupuesto, BibGenie selecciona el siguiente límite de usuario más cercano, en vez de conservar el bloque sobredimensionado mientras busca un mensaje anterior.

Priorizar el uso real del proveedor

Mantener un tokenizer exacto para cada proveedor añadiría mucha complejidad, y los proveedores no calculan contexto y facturación de forma idéntica. BibGenie utiliza por ello los datos reales cuando existen y solo estima el incremento restante:

1. Busca, después del checkpoint más reciente, el último mensaje del asistente con usage válido.
2. Usa el número de tokens comunicado por el proveedor como base.
3. Estima los mensajes añadidos después y aún no incluidos en ese uso.
4. Si no hay datos fiables, estima la proyección completa actual.

El resultado representa el contexto que probablemente acompañará a la siguiente solicitud, no el gasto acumulado del usuario. El totalUsage destinado a facturación no se interpreta como ocupación de contexto.

El texto se aproxima de forma conservadora por caracteres. El reasoning se incluye cuando el proveedor puede volver a reproducirlo. Las imágenes reciben un coste fijo en el preflight para evitar que un mensaje multimodal quede reducido al nombre de archivo. En el plugin actual, los file parts del usuario proceden principalmente de imágenes pegadas y capturas de Zotero.

La estimación no pretende ofrecer una precisión falsa. Responde de forma estable a una pregunta operativa: ¿sigue la próxima solicitud dentro de un margen seguro?

El resumen es una instantánea del estado del agente, no una recapitulación

Un resumen convencional describe lo ocurrido. Un checkpoint de agente debe conservar además suficiente estado para continuar el trabajo.

BibGenie exige una estructura fija:

• Research Goal: objetivo actual;
• User Requirements and Constraints: requisitos, preferencias y límites;
• Research Progress: trabajo completado, activo y bloqueado;
• Findings and Evidence: hallazgos y evidencias asociadas;
• Key Zotero Resources: elementos, adjuntos y claves Zotero importantes;
• Decisions: decisiones ya tomadas;
• Next Steps: acciones concretas siguientes;
• Critical Context: cualquier otra información imprescindible.

El prompt también pide distinguir afirmaciones del usuario, hechos devueltos por herramientas e inferencias del modelo. Así se reduce el riesgo de que una hipótesis provisional se convierta en un hecho establecido tras Compact.

Serialización para contexto de investigación

Antes de generar el resumen, BibGenie convierte los UIMessage en una representación textual compacta orientada a investigación:

• el texto normal conserva contenido y etiqueta de rol;
• el reasoning no entra en el checkpoint a largo plazo;
• las entradas de herramientas se conservan y los resultados excesivos se truncan;
• los errores y operaciones denegadas se marcan explícitamente;
• imágenes y adjuntos mantienen nombre de archivo y tipo MIME;
• los datos de Zotero mantienen los campos necesarios para reanudar el trabajo.

Cada recurso de Zotero conserva información distinta:

• referencias: item key, título y texto de cita;
• páginas PDF: nombre del adjunto, página actual y total de páginas;
• EPUB: índice de sección, href y CFI;
• anotaciones: annotation key, texto, comentario, página y parent item key;
• colecciones y etiquetas: identificadores estables e información visible.

De este modo, no se envían objetos fuente completos y potencialmente grandes en cada resumen, pero se mantienen los localizadores necesarios para llamadas posteriores a herramientas.

Evitar la acumulación de checkpoints

Una sesión larga puede compactarse varias veces. BibGenie nunca envía todos los checkpoints históricos; solo proyecta el más reciente.

En una nueva compactación, el sistema combina:

resumen anterior + nuevos mensajes que han pasado a ser contexto antiguo

para producir uno nuevo:

Resumen 1 + historial nuevo → Resumen 2
Resumen 2 + historial nuevo → Resumen 3

El contexto no crece linealmente con el número de checkpoints.

El límite también es monótono: la nueva frontera retenida no puede retroceder más allá de la del checkpoint anterior. El historial ya sustituido por un resumen nunca vuelve a desplegarse dentro del Recent Tail.

La compactación manual y la automática difieren deliberadamente:

• Compact automático solo se ejecuta si el límite puede avanzar y liberar más contexto.
• Compact manual puede reutilizar el límite cuando hay mensajes nuevos después del checkpoint y generar un resumen actualizado a partir del anterior. Si el límite avanza, también incorpora el historial recién excluido.

Esta diferencia concentra el mantenimiento automático en obtener capacidad, sin eliminar la posibilidad de que el usuario marque una nueva fase de investigación.

El presupuesto de salida del resumen procede de la reserva y está limitado por la salida máxima del modelo. Es un techo de seguridad para investigaciones complejas; el prompt sigue exigiendo concisión.

Por qué Compact debe comprender una sesión en árbol

Las sesiones de BibGenie no son arrays simples, sino árboles de mensajes que pueden ramificarse.

El usuario puede volver a generar una respuesta, editar su último mensaje o crear un fork desde una respuesta anterior del asistente. Los nodos iniciales pueden compartirse entre sesiones, mientras cada sesión identifica su rama activa mediante su propia hoja duradera.

Compact no debe reescribir nodos antiguos ni copiar el Recent Tail después del checkpoint. De hacerlo, podrían producirse estos problemas:

• la compactación de una rama afectaría a otras;
• cambiarían las relaciones parent de nodos compartidos;
• Retry heredaría un checkpoint que ya no es válido;
• se almacenarían mensajes recientes por duplicado;
• el historial visible y el contexto real del modelo divergirían.

BibGenie utiliza un checkpoint append-only:

C1.parentId = A3 indica cuándo y dónde se añadió el checkpoint al árbol. C1.firstKeptMessageId = U3 define dónde se reanuda la proyección literal. Son dimensiones distintas y no pueden sustituirse.

Un fork creado desde A2 no hereda C1. Uno creado desde un mensaje estable del asistente posterior a C1 incluye el checkpoint de forma natural en su cadena de ancestros. No es necesario copiar ni modificar nodos compartidos.

Tratar el checkpoint como un commit de estado seguro ante concurrencia

Generar el resumen puede llevar varios segundos. Si durante ese intervalo la rama se edita, se regenera o cambia de otra forma, el resumen basado en el historial anterior no debe confirmarse.

BibGenie trata Compact como un commit de estado condicionado por versión. Al comenzar registra dos valores:

• leafId: extremo actual de la rama duradera;
• branchRevision: versión que solo aumenta cuando cambia realmente el contenido persistido.

Tras generar el resumen, una transacción específica compara ambos valores, confirma que el flujo de herramientas es estable y verifica que el límite retenido sigue perteneciendo a la rama activa. Solo entonces añade el checkpoint, mueve la hoja e incrementa la revisión. Cualquier diferencia convierte el resumen en obsoleto y obliga a rechazarlo.

Si la rama cambia mientras se genera el resumen, BibGenie vuelve a cargar la rama real en lugar de imponerle un checkpoint obsoleto. Una cancelación anterior al final de la transacción provoca rollback. Después de un commit correcto, el estado en memoria se sincroniza con el checkpoint para que la base y la interfaz converjan en la misma rama.

Coordinación con Retry, Edit, Fork y otras acciones

Una compactación fiable debe preservar la semántica de las operaciones existentes, no limitarse a generar un resumen.

Retry

Un checkpoint es un mensaje interno. Retry apunta a la última respuesta conversacional del asistente. Si hay un checkpoint después del turno reintentado, queda invalidado con la cola antigua; la nueva respuesta vuelve a pasar por los controles normales de capacidad.

Edit

Al editar el último mensaje real del usuario, la respuesta siguiente del asistente y los checkpoints posteriores salen de la rama activa. El reenvío pasa de nuevo por el preflight.

Fork

Solo los mensajes conversacionales estables del asistente pueden ser objetivo de un fork, nunca los checkpoints internos. Que la nueva rama herede un checkpoint depende exclusivamente de la cadena de ancestros del nodo objetivo.

Protección ante historiales dañados

Al cargar una sesión, BibGenie comprueba parents ausentes, ciclos y mensajes duraderos no válidos. Si la topología está dañada, la interfaz muestra solo la parte que puede leerse con seguridad y establece la sesión como de solo lectura. Nunca reescribe silenciosamente la base original durante la carga o Compact.

Experiencia de usuario durante Compact

La compactación del contexto es infraestructura, pero no debe sentirse como un bloqueo inexplicable de la interfaz.

Cuando comienza un Compact manual o automático, el chat muestra Compacting earlier context… y permite cancelarlo. El editor sigue disponible para preparar la siguiente pregunta.

Solo cuando el usuario envía explícitamente esa pregunta se congela su contenido mientras espera a que termine una compactación en curso. BibGenie continúa automáticamente al finalizar. Si falla o se cancela, el mensaje no se envía a escondidas y el borrador permanece intacto.

Retry, Edit, Fork, el cambio de modelo y una segunda compactación se desactivan temporalmente porque modificarían la rama en la que se basa el resumen. Editar el campo de entrada no cambia el historial duradero y no necesita bloquearse antes de tiempo.

Para el usuario, el resultado es claro:

• una investigación larga no se interrumpe de repente al crecer el contexto;
• no hace falta abrir un chat nuevo y volver a explicar los antecedentes;
• cambiar a un modelo con menos contexto provoca una nueva evaluación antes de la solicitud;
• se conservan fuentes clave, claves Zotero, conclusiones y tareas pendientes;
• los mensajes recientes permanecen literales y conservan referencias locales y tono;
• los checkpoints siguen perteneciendo a la rama correcta después de reiniciar el plugin;
• todo el historial anterior a Compact continúa disponible.

Compactación tiene un coste: la caché de prompts empieza de nuevo

Un contexto más corto no hace necesariamente más barata la primera petición después de compactar. La compactación sustituye parte del prefijo por un resumen, por lo que esa primera petición debe recalcularse; después puede construirse una nueva caché alrededor del contexto compactado.

El objetivo no es el prompt más corto posible, sino equilibrar capacidad de contexto, información necesaria, reutilización de caché, latencia y coste.

Decisiones de diseño: verificabilidad en lugar de falsa precisión

La implementación de BibGenie parte de patrones consolidados de compactación de agentes y los adapta a Zotero, las entradas multimodales y la persistencia en árbol. Evita deliberadamente complicar el sistema sin una ventaja clara:

• no usa un tokenizer supuestamente universal y exacto para todos los proveedores;
• no elimina físicamente ni cambia el parent de mensajes anteriores;
• no duplica el Recent Tail;
• no ejecuta Compact y reintenta automáticamente tras un overflow del proveedor;
• no permite crear o modificar checkpoints mediante la persistencia ordinaria;
• no confunde tokens acumulados de facturación con ocupación de contexto.

Estas decisiones facilitan verificar las propiedades esenciales: cuándo se activa Compact, qué rama representa el resumen, qué mensajes recibe el modelo, qué confirma la base de datos y en qué estado queda el sistema tras un fallo.

Compact sigue siendo una compresión con pérdida. Su objetivo no es que el modelo recuerde literalmente cada token, sino preservar la continuidad de la tarea dentro de una ventana finita. El historial completo aporta trazabilidad, el checkpoint conserva el estado de trabajo y el Recent Tail mantiene el detalle local.

Del chatbot al colaborador de investigación a largo plazo

Un sistema de chat convencional se pregunta sobre todo: «¿Cómo debo responder en este turno?». Un agente de investigación también debe responder: «¿Qué estado debo llevar al siguiente turno?»

Context Compaction en BibGenie es más que una llamada de resumen. Combina preflight de capacidad, serialización del contexto de investigación, checkpoints estructurados, proyección de sesiones en árbol, validación de versiones concurrentes, persistencia transaccional y comportamiento coherente con Retry, Edit y Fork.

Cuando una investigación abarca decenas de turnos, varios artículos y muchas llamadas a herramientas, recordar cada token importa menos que saber de forma consistente:

• qué quiere conseguir finalmente el usuario;
• qué afirmaciones ya cuentan con evidencia;
• qué conclusiones siguen siendo hipótesis;
• qué trabajo se ha completado;
• cuál debe ser el siguiente paso.

Eso es lo que Compact aporta a BibGenie: la capacidad de utilizar una ventana de contexto finita para sostener una sesión de agente que progresa a largo plazo, puede recuperarse con fiabilidad y conserva el hilo de la investigación.