La puerta que se niega a compactar: qué protege realmente compression.checkpoint_required

Tres horas dentro de una sesión, la ventana de contexto se llena, Hermes comprime y tú sigues trabajando. Dos días después preguntas por qué se tomó una decisión y recibes una respuesta segura de sí misma que resulta ser el resumen de un resumen. Nada está corrupto exactamente, pero lo que necesitabas nunca quedó escrito en ningún sitio duradero, y la transcripción que lo contenía ha sido reescrita.
Ese es el fallo que compression.checkpoint_required existe para evitar. Es un instrumento contundente: con la puerta armada, Hermes prefiere negarse a compactar antes que reescribir tu historial sin una copia de seguridad.
La idea en una frase
La compactación es con pérdida por definición: una transcripción larga se convierte en un resumen más corto y una cola reciente. La puerta dice: antes de que ocurra esa reescritura, alguien tiene que haber confirmado una copia duradera de la transcripción sin comprimir, y tiene que haberme dicho que la ha confirmado.
¿Quién es «alguien»? Un plugin de proveedor de memoria. No el sumarizador, no la base de datos de sesiones, no el modelo.
Cómo activarla
compression:
checkpoint_required: true # por defecto: false
o, de forma equivalente:
hermes config set compression.checkpoint_required true
hermes config get compression.checkpoint_required
Esa es toda la superficie de operación. Todo lo que sigue trata de lo que cambia, porque las consecuencias son mayores de lo que sugiere un solo booleano.
Qué bloquea la puerta
Con la puerta armada, un intento de compactación falla de forma cerrada antes de cualquier reescritura con pérdida:
- la transcripción sin comprimir se conserva exactamente como está;
- el intento devuelve un error
BLOCKED_MISSING_PREREQUISITEy un motivo que nombra lo que faltaba; - se puede reintentar cuando tu almacén de archivo se recupere.
La puerta además obliga a toda autoridad de compactación, no solo al sumarizador de Hermes. La compactación nativa del lado del servidor queda suprimida mientras la puerta está armada, la micro-compactación posterior al turno se fuerza a desactivarse en el arranque del agent (absorbe intercambios antiguos en un resumen rotatorio sin ningún enganche de checkpoint en su ruta), y el modo de API codex_app_server se rechaza al iniciar, porque ese runtime compacta su propio hilo sin una frontera previa a la compactación fiable, así que no se puede garantizar allí un checkpoint obligatorio. El compresor de Hermes, consciente de los checkpoints, sigue siendo la única autoridad con pérdida.
Esa última parte es el intercambio honesto: activar la puerta hace la compactación más estricta y, en algunos runtimes, imposible. Es un ajuste de integridad de datos, no de rendimiento.
Qué tiene que implementar un proveedor
El contrato es pequeño y explícito. Un proveedor se suma declarando la versión 2 de la API:
from agent.memory_provider import MemoryProvider
class MyArchivingProvider(MemoryProvider):
pre_compress_checkpoint_api_version = 2
def on_pre_compress(self, messages, *, require_checkpoint=False):
ids = self._archive(messages) # debe ser duradero antes de retornar
return f"checkpoint: {ids}" # se reenvía al prompt del resumen
require_checkpoint refleja el ajuste del operador: cuando es True, lanzar una excepción desde este método es lo que bloquea la reescritura con pérdida. Retornar significa «la copia duradera está confirmada», así que el éxito parcial no es una opción, y la documentación es explícita en que hay que lanzar la excepción ante cualquier fallo en lugar de retornar con optimismo.
Los proveedores de la versión 2 también reciben evidencia directa normalizada en lugar de la lista en bruto: solo filas de texto de usuario y de asistente. Los resultados de tools, los mensajes de sistema, el payload tool_calls de los mensajes de asistente y los resúmenes de compactaciones previas se filtran del lado del host. Los resúmenes previos se reconocen mediante un marcador persistente, así que una sesión retomada nunca reinyecta resúmenes derivados en tu archivo como si fueran evidencia original.
Un requisito más que sorprende a la gente: los checkpoints tienen que ser idempotentes. Después de un bloqueo de fallo cerrado, el siguiente intento vuelve a llamar a on_pre_compress() con la misma transcripción, y una transcripción que creció un poco produce evidencia que se solapa en gran parte. Indexa las escrituras del archivo por contenido — un digest de la transcripción, por ejemplo — y haz upsert, o los reintentos acumularán duplicados.
Qué cambió el 6 de noviembre
La puerta llegó antes, pero tenía una arista afilada que necesitó un follow-up (PR #149763, merged el 6 de noviembre de 2026). Dos problemas:
- Los subagents y los forks se construían con la memoria desactivada.
delegate_task, el curator, el ejecutor por lotes y los turnos de comentarios de Feishu ejecutan cada uno su propia transcripción, y esos forks se construían conskip_memory=True. Con la puerta armada, su primera compactación fallaba conBLOCKED_MISSING_PREREQUISITE, no porque tu proveedor tuviera algo mal, sino porque al fork nunca se le dio uno. - La poda proactiva de resultados de tools ignoraba la puerta. Descarta resultados de tools grandes para recuperar tokens sin una llamada al LLM, y los estaba descartando sin ningún checkpoint previo: borrando en silencio evidencia que la puerta debía proteger.
Ambos están corregidos. Los forks ahora conservan el proveedor mientras la puerta está armada, y el host suprime sus escrituras y su recall (se ejecutan bajo un contexto de subagent en lugar de fingir ser tú). La poda se retiene en su punto de llamada hasta que exista un checkpoint.
Si activaste la puerta antes de ese arreglo y viste turnos de subagent muriendo en su primera compactación, ya sabes por qué, y merece la pena reintentarlo ahora.
¿Deberías activarla?
Hazte una pregunta: ¿hoy puedes recuperar una transcripción compactada?
Si tu respuesta es «el resumen me basta», deja la puerta desactivada. Está desactivada por defecto, y ninguno de los proveedores que vienen con Hermes anuncia la API de checkpoint v2: activa la puerta sin un proveedor v2 y bloquearás todos los intentos de compactación, manuales y automáticos. El arranque del agent registra un aviso que nombra el proveedor activo, y cada rechazo nombra compression.checkpoint_required como la clave que hay que desactivar, así que falla de forma ruidosa en lugar de silenciosa.
Si tu respuesta es «tenemos un archivo de todas las conversaciones y necesitamos que esté completo», la puerta convierte una pérdida silenciosa en una parada ruidosa, que suele ser justo lo que quieres en un despliegue regulado o de larga vida. Combínala con un proveedor que haga upsert por digest, y cuenta con que el comportamiento de la compactación pasa a ser determinista en lugar de best-effort.
Para el panorama que la rodea — cuánto de tu ventana recupera la compactación y adónde van realmente los tokens — la guía de optimización de tokens de contexto es la lectura complementaria. Y si de todos modos vas a actualizar, la página de la release v0.23.0 lista los demás cambios de compresión de este ciclo, incluida la compactación preparada opcional que escribe el siguiente resumen en segundo plano.