# Compactación de contexto compatible con caché en OpenCode: por qué importa la estabilidad del prefijo
Respuesta directa
La compactación compatible con caché permite continuar sesiones largas de OpenCode sin obligar al modelo a reprocesar toda la conversación. El plugin añade al historial existente una petición de resumen y después envía el prefijo estable de sistema y herramientas, el resumen y los turnos nuevos. Puede reducir el prefill local, pero no conserva cada detalle ni garantiza aciertos de caché.
Qué necesita saber quien busca compactación de contexto en OpenCode
Las búsquedas sobre compactación en OpenCode se concentran en cuatro dudas: qué elimina la compactación, por qué una sesión larga tarda tanto antes de producir el siguiente token, cómo se diferencia un plugin alternativo del mecanismo nativo y qué ajustes son seguros con modelos locales. Son cuestiones relacionadas, pero no equivalentes.
La compactación resuelve un problema de capacidad. La caché de prompt o prefijo reduce cálculo repetido. Un resumen puede acortar la petición siguiente y, a la vez, destruir la reutilización de un prefijo ya procesado. En sentido contrario, una conversación que solo añade mensajes conserva la caché, pero sigue creciendo hacia el límite. Un diseño útil debe gestionar ambos efectos.
`opencode-cache-compact` es un plugin de OpenCode con licencia MIT, pensado principalmente para modelos alojados localmente, donde el prefill de un prompt grande puede dominar la espera anterior a la generación. Su técnica central es solicitar el resumen como un turno normal añadido y recortar después solo el contexto enviado al modelo. La sesión completa permanece almacenada y visible en la interfaz.
Es un proyecto joven. El repositorio nació el 21 de septiembre de 2026 y, al revisarlo el 1 de octubre, documentaba compatibilidad con OpenCode V1 y con la superficie beta de plugins V2. Debe tratarse como una optimización operativa interesante, no como un valor predeterminado maduro.
Contexto, compactación y caché pertenecen a capas distintas
Un modelo recibe una secuencia finita de tokens. OpenCode incorpora instrucciones de sistema, esquemas de herramientas, mensajes, resultados, archivos y la petición actual. A medida que el agente trabaja, la secuencia crece. Cerca del límite, el material antiguo debe eliminarse, resumirse o trasladarse a otra memoria.
La documentación oficial de OpenCode define la compactación como la sustitución de conversación antigua por un resumen, conservando el trabajo reciente. Así libera espacio para continuar. Es inevitablemente una operación con pérdida: el resumen representa el trabajo anterior, pero no es el registro completo.
La caché de prompt ataca otro coste. Muchos servidores reutilizan el cálculo de un prefijo idéntico que ya procesaron. Si la petición siguiente comienza con el mismo sistema, herramientas e historial, puede reutilizar estados KV en lugar de prefijar todos los tokens. Añadir un turno conserva el prefijo anterior; insertar, borrar o reescribir contenido al principio puede invalidarlo.
La diferencia es especialmente visible en inferencia local. Una API cloud puede ocultar el prefill detrás de una flota rápida. Una estación de trabajo tiene ancho de banda y cómputo fijos. Releer un prompt muy largo puede multiplicar el tiempo hasta el primer token aunque la velocidad de salida siga siendo aceptable.
Para ejecutar modelos sin pagar inferencia consulta las guías de FreeAI Tokens sobre herramientas locales gratuitas, créditos GPU gratuitos y API de IA gratis.
Cómo funciona el plugin compatible con caché
El README describe una secuencia de tres etapas.
1. Medir uso y activar un umbral
Después de cada paso, el plugin lee `tokens.total` de OpenCode y lo compara con `limit.context` del modelo. El umbral predeterminado es el 68 %. Si el proveedor no informa del límite, existe un fallback configurable de 131.072 tokens.
Ese porcentaje no es una recomendación universal. Reserva espacio para resumen, herramientas y un paso largo, pero el margen correcto depende del modelo, la salida máxima y la carga. Un modelo de 32k con resultados de herramientas voluminosos requiere otra política que uno de 128k usado para ediciones breves.
2. Resumir añadiendo
Al cruzar el umbral, el plugin añade un mensaje de usuario ordinario para pedir un resumen de traspaso. No reconstruye antes una versión reducida de la conversación. Si el servidor conserva la caché, puede reutilizar la mayor parte del historial y calcular únicamente la cola nueva y el resumen.
La salida del resumen se limita a 1.200 tokens por defecto. Es un compromiso: un resumen corto es barato de prefijar, pero puede perder decisiones, rutas, pasos pendientes o evidencias. Uno largo conserva más, aunque pasa a formar parte de la nueva base en todas las peticiones.
3. Recortar el contexto saliente y reanudar
Tras recibir el resumen, el plugin recuerda el límite y reescribe las peticiones posteriores con una forma compacta: sistema, herramientas, resumen y mensajes nuevos. Puede enviar automáticamente un breve turno para continuar.
La palabra importante es saliente. La sesión guardada no se borra. La interfaz muestra la conversación previa mientras el modelo recibe una vista reducida. Esto ayuda a inspeccionar y recuperar, pero el modelo ya no puede razonar sobre detalles omitidos salvo que el resumen los retenga o una herramienta los recupere.
Por qué conservar el prefijo puede reducir la espera
La inferencia autorregresiva tiene dos fases visibles. En prefill, el modelo procesa el prompt y crea el estado de atención. En decode, genera nuevos tokens. En sesiones extensas, el prefill puede ser la parte lenta aunque los tokens por segundo de salida sean buenos.
La guía oficial de caché de OpenAI confirma el principio general: mantener estables instrucciones e historial reutilizable, añadir mensajes y recordar que resumir o truncar puede reiniciar la reutilización al cambiar el prefijo. La implementación y duración de la caché varían por proveedor y servidor, pero la estabilidad del prefijo es una regla más amplia que una API concreta.
El autor del plugin informó de una reducción desde más de diez minutos hasta aproximadamente uno o dos en un sistema Strix Halo. Es una observación del autor, no un benchmark reproducido independientemente. Hardware, modelo, longitud, cuantización, política del servidor y expulsión de caché pueden alterar el resultado.
La conclusión defendible no es que “compacta cinco veces más rápido”. Es que resumir mediante un mensaje añadido ofrece a un servidor capaz de cachear la oportunidad de reutilizar el prefijo, mientras una petición reconstruida puede obligar a un prefill frío.
Instalación en OpenCode V1 y V2
El repositorio documenta configuraciones distintas para ambas generaciones.
En V1, el paquete npm se añade al array `plugin` con opciones como el umbral. Depende del hook experimental `experimental.chat.messages.transform`. En V2 beta, se coloca en `plugins` y utiliza `session.hook("context")` junto con el flujo de eventos.
También se documenta la carga desde un checkout local. V1 admite una ruta `file://`. La compilación V2 beta actual rechaza esas rutas, por lo que propone un pequeño archivo de reexportación en el directorio global de plugins. Los plugins descubiertos automáticamente reciben opciones predeterminadas; el formato npm permite personalizarlas.
Si debe ser el único compactador, el README indica desactivar la compactación automática nativa. Ejecutar dos compactadores crea una carrera: la vía nativa puede resumir primero y cambiar el contexto antes de que actúe el plugin.
Secuencia prudente:
- Confirma la versión exacta de OpenCode y su API de plugins.
- Registra el límite real del modelo y su salida máxima.
- Verifica que el servidor reutiliza caché KV entre peticiones.
- Fija la versión del paquete o un commit concreto.
- Limita el plugin a los `providerID/modelID` locales previstos.
- Desactiva la compactación nativa solo después de comprobar que carga.
- Empieza con `autoResume` desactivado para revisar el primer recorte.
- Activa logs de depuración en una sesión desechable.
- Comprueba que ocurre un resumen, un recorte y una reanudación.
- Conserva exportación o copia de la sesión antes de usarlo en trabajo importante.
Ajustes que requieren una decisión consciente
| Ajuste | Predeterminado | Pregunta práctica |
|---|---|---|
| `threshold` | 68 | ¿Qué margen necesitan herramientas, resumen y el paso más largo? |
| `models` | todos | ¿Deben excluirse proveedores cloud o sin caché? |
| `summaryMaxTokens` | 1200 | ¿Cuánto estado debe sobrevivir sin agrandar demasiado la nueva base? |
| `contextLimit` | 131072 | ¿Coincide el fallback con el modelo configurado? |
| `autoResume` | true | ¿Debe continuar el trabajo sin revisión humana tras un resumen con pérdida? |
| `abortOnTrip` | true | ¿Es aceptable detener el paso activo al cruzar el umbral? |
| `disablePrune` | true | ¿La versión de OpenCode aún expone ese comportamiento? |
| `debug` | false | ¿Pueden activarse logs sin retener datos sensibles indebidamente? |
`models` merece especial atención. Una lista vacía aplica a todos los modelos. Quien alterna entre llama.cpp local y un proveedor alojado puede querer esta compactación solo en local. Cada proveedor informa y gestiona contexto y caché de forma distinta; una política única rara vez será óptima.
Qué conserva y qué no puede conservar
Conserva la conversación en disco, el sistema, las herramientas, el resumen y los turnos posteriores. También mantiene la posibilidad de reutilizar la caché existente durante la petición del resumen.
No garantiza que el servidor conserve esa caché. Un reinicio, expulsión, cambio de modelo, worker diferente, caducidad o serialización modificada puede provocar un fallo. La primera petición tras el recorte debe procesar la nueva base de sistema, herramientas y resumen.
Tampoco vuelve perfecto el resumen. Salidas exactas, hipótesis descartadas, diseños rechazados y preferencias sutiles pueden desaparecer. En programación, debe retener objetivos, archivos cambiados, comandos ejecutados, pruebas, errores pendientes y la siguiente acción segura.
No crea memoria persistente entre sesiones independientes. El límite de recorte vive en memoria; si OpenCode reinicia, no aplicará el corte anterior hasta cruzar otro umbral. El humano conserva el transcript, pero cambia el contexto activo del modelo.
Cuándo encaja bien
Es buen candidato cuando:
- OpenCode apunta a un servidor local compatible con OpenAI.
- El prefill largo es un problema medido.
- El servidor reutiliza prefijos entre peticiones secuenciales.
- Las sesiones acumulan largas cadenas de herramientas.
- El operador puede revisar logs y recuperarse de un resumen incompleto.
- El proyecto acepta el mantenimiento de un plugin joven.
Puede ser innecesario si las sesiones rara vez alcanzan el límite, el proveedor ya compacta eficientemente, el servidor no mantiene caché o el cuello está en decode. Tampoco conviene en tareas reguladas donde un resumen generado no puede convertirse en estado autorizado.
Cómo probarlo sin fiarse de impresiones
Construye una prueba A/B con el mismo modelo, cuantización, contexto, historial y proceso servidor. Calienta una conversación larga no sensible. Registra, si existe, la métrica de tokens cacheados, tiempo al primer token, duración total, tokens procesados y completitud factual del resumen.
Ejecuta el compactador nativo y el plugin en sesiones limpias separadas. Repite cada condición: la primera ejecución puede incluir carga del modelo, caché del sistema o compilación de shaders. Un resultado útil contiene varias medidas, no un cronómetro único.
Después prueba continuidad semántica. Pide al agente objetivo, archivos editados, verificaciones, fallos conocidos y siguiente paso. Compáralo con el transcript. Un resumen rápido que pierda una advertencia destructiva o un cambio sin commit no mejora el sistema.
Prueba también fallos: resumen vacío, reinicio del servidor, expulsión de caché, reinicio de OpenCode, bucle de herramientas y cambio a un modelo no incluido. La suite del proyecto cubre la máquina de estados y formas de peticiones con mocks, pero no certifica todas las combinaciones.
Seguridad y privacidad
El plugin se ejecuta dentro de un agente de programación con acceso a conversación y posibles herramientas potentes. Revisa código y dependencias, fija versión, limita permisos y trata los logs como sensibles.
Como la sesión completa sigue en disco, compactar lo que ve el modelo no equivale a borrar datos. Si el objetivo es reducir retención, hay que gestionar el almacenamiento y las copias de OpenCode. Enviar el resumen a un proveedor cloud sigue enviando el prefijo correspondiente; la caché no cambia la frontera de datos.
Consulta más evaluaciones en el centro editorial de FreeAI Tokens y verifica las condiciones en el directorio de planes gratuitos.
Veredicto
`opencode-cache-compact` aplica una idea de sistemas razonable a un cuello de botella local real: no reescribir un prefijo reutilizable antes de pedir el resumen. Su flujo de añadir, recortar y reanudar puede reducir prefill frío manteniendo intacta la sesión visible.
El beneficio depende de servidor con caché, serialización estable, contexto bien informado y un resumen que preserve el estado. El plugin es reciente y usa superficies experimentales o beta de OpenCode. Debe adoptarse como optimización medida: fijar versión, limitar a modelos locales, probar continuidad y recuperación, y comparar caché y latencia antes de sustituir la compactación nativa.
Fuentes y evidencia
- Repositorio y README de opencode-cache-compact: diseño, instalación, valores, compatibilidad, pruebas y límites.
- Documentación de compactación de OpenCode: objetivo de la compactación nativa, forma de contexto y configuración.
- Documentación de plugins de OpenCode: instalación y ciclo de vida de plugins.
- Guía de caché de prompts de OpenAI: fuente primaria independiente sobre prefijos estables, historial añadido e invalidación por compactación.
Fuentes revisadas el 1 de octubre de 2026. Las cifras de tiempo del autor se identifican como resultados publicados por el proyecto y FreeAI Tokens no las reprodujo independientemente.