Context Crumb
Comprime archivos largos, entradas de prompt y descripciones del catálogo MCP en un contexto más denso para agentes LLM, preservando la señal útil.
Documentación
ContextCrumb
Saca las migas del contexto inflado.
Antes / Después - Inicio rápido - Zona de pruebas - Instalación - CLI - Agente + MCP - Modelo
El contexto de los LLM se desordena rápido: notas, registros, hilos de incidencias, documentación, volcados de investigación y descripciones de herramientas se acumulan hasta que la señal útil queda enterrada bajo el relleno.
ContextCrumb es un compresor a nivel de token para flujos de trabajo con LLM y agentes. Examina el texto palabra por palabra y elimina los tokens de baja señal, manteniendo el texto superviviente en el orden original.
Esa es la idea detrás del nombre: el contexto sigue ahí, pero las migas sueltas se sacuden antes de que lleguen a tu modelo. Menos inflado en el prompt. Más espacio para las partes que importan. Menos uso desperdiciado cuando Codex, Claude Code u otro agente procesa archivos largos repetidamente.
Sin necesidad de instalación. Pega texto, compara el contexto conservado y mira qué se sacude.
Antes / Después
ContextCrumb no es un resumidor. No reescribe tu documento en una nueva explicación. Conserva la secuencia original y elimina palabras prescindibles. Este ejemplo usa target_keep_ratio=0.72.
Original
Agents spend context on notes, logs, tickets, docs, and tool descriptions. Those files contain useful facts, but they also carry filler phrases and repeated wording. ContextCrumb compresses the text before it reaches the model. It keeps the original order, removes low-value tokens, and leaves a shorter version with the names, actions, constraints, and sequence still intact.
Comprimido
Agents spend context notes, logs, tickets, docs tool descriptions. Those files useful facts, carry filler phrases repeated wording. ContextCrumb compresses text before reaches model. keeps original order, removes low-value tokens, leaves shorter version names, actions, constraints sequence intact.
Mismo orden. Menos relleno. Más espacio para el siguiente archivo. En entradas de agente con mucho texto, ContextCrumb suele ahorrar alrededor de 30-70% del contexto, dependiendo de cuán agresivamente comprimas y cuánto relleno haya en la fuente.
| Métrica | Original | Comprimido | Ahorrado |
|---|---|---|---|
| Tokens del modelo | 72 | 52 | 20 tokens |
| Presupuesto de tokens | 100% | 72% | 28% menos tokens de entrada |
Cómo se siente eso en un mes
Supón que tu agente lee notas, registros, tickets, volcados de investigación o documentación de 8k tokens antes de responder. Esto ayuda con las facturas de tokens de API, pero también con agentes de codificación por suscripción donde las lecturas de contexto pesadas pueden consumir el uso más rápido.
| Flujo de trabajo | Archivos leídos / día | Contexto ahorrado / mes | Costo de API evitado a $5 / 1M tokens de entrada | Sensación de uso de suscripción |
|---|---|---|---|---|
| Ayudante de agente individual | 20 | ~1.4M-3.4M tokens | ~$7-$17 | Menos lecturas voluminosas en Codex o Claude Code |
| Espacio de trabajo de proyecto ocupado | 200 | ~14M-34M tokens | ~$72-$168 | Más espacio para razonamiento y ediciones reales |
| Equipo con muchos agentes o bucle de evaluación | 2,000 | ~144M-336M tokens | ~$720-$1,680 | Menos uso gastado procesando archivos con relleno |
La mayor ventaja generalmente no es solo la factura. Es mantener a los agentes de larga duración sin llenar su contexto, turnos y uso de suscripción con palabras que no necesitaban llevar en primer lugar.
Inicio rápido (configuración en 30 segundos)
Enséñale a tu agente un pequeño hábito: comprime el inflado antes de que entre al contexto. ContextCrumb está pensado para estar en segundo plano como una habilidad, interviniendo cada vez que una nota larga, documento, hilo de incidencias, volcado de investigación o registro inundaría la ventana de contexto y consumiría tu uso de Codex o Claude Code.
- Añade la habilidad.
npx skills add Yuchen20/Context-Crumb
- Selecciona el agente en el que quieres instalarla.
La habilidad le dice a tu agente cuándo comprimir texto, cómo preservar la secuencia útil, cuándo el código compatible puede cargarse con compresión de comentarios/docstrings, y cuándo se requiere texto crudo exacto para configuraciones, citas directas o ediciones exactas.
- Usa ContextCrumb para comprimir archivos largos en lugar de soltar todo el archivo en el contexto.
Use ContextCrumb to compress this long project note before you work from it.
- Listo: cada nota larga, registro, ticket, volcado de investigación o documento entra al contexto ya recortado, ahorrando tokens y preservando más de tu suscripción de agente para el trabajo que importa.
¿Por qué ContextCrumb?
| Caso de uso | Qué cambia |
|---|---|
| Carga de archivos de agente | Comprime notas largas, documentos, volcados de investigación y registros antes de que lleguen a la ventana de contexto. |
| Pipelines de prompts | Reduce entradas de lenguaje natural sin escribir resumidores a mano. |
| Catálogos MCP | Comprime descripciones verbosas de herramientas/recursos preservando nombres y esquemas. |
| Flujos de trabajo locales | Ejecuta inferencia ONNX por defecto, con archivos de modelo en caché tras la primera descarga. |
| Agentes conscientes de suscripción | Gasta menos uso de Codex o Claude Code cargando prosa con relleno repetidamente. |
| Inspección y ajuste | Usa diff y inspect para ver qué se conservó, eliminó y ahorró. |
Mejor ajuste: documentación, notas, hilos de incidencias, registros, contexto de investigación, otros archivos de lenguaje natural y archivos de código compatibles donde solo deben acortarse comentarios/docstrings. Para ediciones de código exactas o comentarios exactos, lee la fuente cruda.
Instalación
pip install contextcrumb
Extras opcionales:
pip install "contextcrumb[mcp]"
pip install "contextcrumb[serve]"
pip install "contextcrumb[torch]"
ContextCrumb usa el backend ONNX por defecto, por lo que los usuarios normales no necesitan PyTorch ni Transformers instalados. Los archivos de modelo se guardan en caché localmente tras la primera descarga.
CLI
El comando principal amigable para agentes es load:
contextcrumb load notes.txt
Imprime solo texto comprimido por defecto, lo que facilita que agentes, hooks, scripts de shell y pipelines de prompts capturen stdout y sigan adelante. Para herramientas de suscripción como Codex o Claude Code, eso significa menos lecturas voluminosas de archivos antes de que el agente llegue a la parte útil.
Comandos útiles:
contextcrumb load notes.txt --json
contextcrumb load notes.txt --receipt
contextcrumb config set compression.content_mode auto
contextcrumb diff notes.txt
contextcrumb inspect notes.txt
contextcrumb stats
--receipt deja texto comprimido en stdout y escribe un recibo de ahorro compacto
en stderr. ContextCrumb usa compression.content_mode = "auto" por defecto:
los archivos de prosa se comprimen normalmente, mientras que los archivos de código compatibles usan una
ruta consciente del código que preserva la fuente ejecutable exactamente y comprime solo
comentarios/docstrings. Los archivos no compatibles sensibles a la sintaxis, como diffs, configuraciones,
lockfiles, SQL y archivos .env, se rechazan a menos que pases --force;
la salida forzada es solo para lectura exploratoria, no para ediciones exactas o comandos de copiar y pegar.
Los valores predeterminados persistentes viven en la configuración del usuario y se pueden cambiar desde la CLI:
contextcrumb config show
contextcrumb config set compression.content_mode code-comments
contextcrumb config set code.comment_target_keep_ratio 0.55
contextcrumb config unset compression.content_mode
Modos de archivo compatibles:
| Modo | Comportamiento |
|---|---|
auto | La prosa usa compresión normal; el código compatible usa code-comments. |
prose | Trata toda la entrada como lenguaje natural. |
code-comments | Preserva el código ejecutable exactamente y comprime solo comentarios/docstrings. |
raw | Devuelve el archivo sin cambios con estadísticas. |
refuse | Rechaza la compresión de archivos. |
Lenguajes iniciales conscientes del código: Python, JavaScript, TypeScript, JSX, TSX, Go y Rust.
diff marca los tokens eliminados así:
kept words [-deleted words-] kept words
Agente + MCP
ContextCrumb incluye un adaptador MCP stdio opcional para clientes de agentes que pueden ejecutar herramientas de Python a través de uvx.
pip install "contextcrumb[mcp]"
Configuración MCP del paquete publicado:
{
"mcpServers": {
"contextcrumb": {
"command": "uvx",
"args": [
"--from",
"contextcrumb[mcp]",
"contextcrumb-mcp"
]
}
}
}
El servidor MCP expone:
compress_text
compress_file
ContextCrumb también incluye contextcrumb-shrink, un proxy MCP que comprime descripciones de catálogo verbosas antes de que un agente las vea, mientras reenvía nombres de herramientas, esquemas, llamadas, resultados y contenidos de recursos sin cambios. Esto es útil cuando un cliente de agente gasta repetidamente contexto y uso de suscripción solo mirando descripciones largas de herramientas.
Modelo
Los pesos del modelo y una demo alojada son públicos en Hugging Face:
- Modelo: ymao20/contextcrumb-32m
- Zona de pruebas: contextcrumb-32m-demo
Hoja de ruta
Planeado para más adelante:
- Documentación pública para modos de compresión avanzados y despliegue de servicios.
- Cliente JavaScript o TypeScript.
- Experimentos de API alojada.
- Publicación en npm.
Desarrollo
uv pip install --python .\.venv\Scripts\python.exe -e ".[dev,mcp]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m build
Las notas de versión se rastrean en CHANGELOG.md.
Licencia
MIT. Ver LICENSE.