Context Crumb

I will translate the natural-language prose to Portuguese (BR), preserving all placeholders and Markdown structure exactly.

ContextCrumb

Tire as migalhas do contexto inflado.

Início Antes/Depois Guia rápido Playground

Antes/Depois - Guia rápido - Playground - Instalação - CLI - Agente + MCP - Modelo

---

O contexto de LLMs fica bagunçado rapidamente: notas, logs, discussões de issues, documentação, acúmulos de pesquisa e descrições de ferramentas se empilham até que o sinal útil fique enterrado sob o excesso.

ContextCrumb é um compressor em nível de token para fluxos de trabalho de LLM e agentes. Ele analisa o texto palavra por palavra e remove tokens de baixo sinal, mantendo o texto sobrevivente na ordem original.

Essa é a ideia por trás do nome: o contexto ainda está lá, mas as migalhas soltas são sacudidas antes de chegarem ao seu modelo. Menos inchaço no prompt. Mais espaço para as partes que importam. Menos uso desperdiçado quando Codex, Claude Code ou outro agente processa arquivos longos repetidamente.

_{Sem necessidade de instalação. Cole o texto, compare o contexto mantido e veja o que é sacudido para fora.}

Antes/Depois

ContextCrumb não é um resumidor. Ele não reescreve seu documento em uma nova explicação. Ele mantém a sequência original e exclui palavras dispensáveis. Este exemplo 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.

Mesma ordem. Menos preenchimento. Mais espaço para o próximo arquivo. Em entradas de agentes com muito texto, ContextCrumb frequentemente economiza cerca de 30-70% do contexto, dependendo de quão agressivamente você comprime e de quanto excesso existe na fonte.

Métrica	Original	Comprimido	Economia
Tokens do modelo	72	52	20 tokens
Orçamento de tokens	100%	72%	28% menos tokens de entrada

Como isso se sente ao longo de um mês

Suponha que seu agente leia notas de 8 mil tokens, logs, tickets, acúmulos de pesquisa ou documentação antes de responder. Isso ajuda com as contas de API de tokens, mas também com agentes de codificação baseados em assinatura, onde leituras de contexto pesadas podem queimar o uso mais rapidamente.

Fluxo de trabalho	Arquivos lidos / dia	Contexto economizado / mês	Custo de API evitado a $5 / 1M tokens de entrada	Sensação de uso da assinatura
Ajudante de agente solo	20	~1,4M-3,4M tokens	~$7-$17	Menos leituras volumosas no Codex ou Claude Code
Espaço de trabalho de projeto movimentado	200	~14M-34M tokens	~$72-$168	Mais espaço para raciocínio e edições reais
Equipe com muitos agentes ou loop de avaliação	2.000	~144M-336M tokens	~$720-$1.680	Menos uso gasto processando arquivos preenchidos

A maior vitória geralmente não é apenas a conta. É manter agentes de longa duração de não encher seu contexto, suas rodadas e o uso da assinatura com palavras que eles não precisavam carregar em primeiro lugar.

Guia rápido (configuração de 30 segundos)

Ensine ao seu agente um pequeno hábito: comprima o excesso antes que ele entre no contexto. ContextCrumb foi feito para ficar em segundo plano como uma habilidade, intervindo sempre que uma nota longa, documento, discussão de issue, acúmulo de pesquisa ou log inundaria a janela de contexto e consumiria seu uso no Codex ou Claude Code.

1. Adicione a habilidade.

npx skills add Yuchen20/Context-Crumb

2. Selecione o agente no qual deseja instalá-la.

A habilidade diz ao seu agente quando comprimir texto, como preservar a sequência útil, quando código suportado pode ser carregado com compressão de comentários/docstrings, e quando texto bruto exato é necessário para configurações, citações diretas ou edições exatas.

3. Use ContextCrumb para comprimir arquivos longos em vez de despejar tudo no contexto.

Use ContextCrumb to compress this long project note before you work from it.

4. Pronto: toda nota longa, log, ticket, acúmulo de pesquisa ou documento entra no contexto já reduzido, economizando tokens e preservando mais da sua assinatura de agente para o trabalho que importa.

Por que ContextCrumb?

Caso de uso	O que muda
Carregamento de arquivos por agentes	Comprima notas longas, documentos, acúmulos de pesquisa e logs antes que eles atinjam a janela de contexto.
Pipelines de prompt	Reduza entradas em linguagem natural sem escrever resumidores manualmente.
Catálogos MCP	Comprima descrições verbosas de ferramentas/recursos preservando nomes e esquemas.
Fluxos locais	Execute inferência ONNX por padrão, com arquivos de modelo em cache após o primeiro download.
Agentes cientes de assinatura	Gaste menos uso do Codex ou Claude Code carregando prosa preenchida repetidamente.
Inspeção e ajuste	Use diff e inspect para ver o que foi mantido, excluído e economizado.

Melhor aplicação: documentos, notas, discussões de issues, logs, contexto de pesquisa, outros arquivos em linguagem natural e arquivos de código suportados onde apenas comentários/docstrings devem ser encurtados. Para edições exatas de código ou comentários exatos, leia o código-fonte bruto.

Instalação

pip install contextcrumb

Extras opcionais:

pip install "contextcrumb[mcp]"
pip install "contextcrumb[serve]"
pip install "contextcrumb[torch]"

ContextCrumb usa o backend ONNX por padrão, então usuários comuns não precisam de PyTorch ou Transformers instalados. Os arquivos de modelo são armazenados em cache localmente após o primeiro download.

CLI

O principal comando amigável para agentes é load:

contextcrumb load notes.txt

Ele imprime apenas o texto comprimido por padrão, o que facilita para agentes, hooks, scripts de shell e pipelines de prompt capturarem stdout e seguirem em frente. Para ferramentas de assinatura como Codex ou Claude Code, isso significa menos leituras volumosas de arquivos antes que o agente chegue à parte útil.

Comandos úteis:

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 deixa o texto comprimido no stdout e escreve um recibo de economia compacto no stderr. ContextCrumb usa compression.content_mode = "auto" por padrão: arquivos de prosa são comprimidos normalmente, enquanto arquivos de código suportados usam um caminho ciente de código que preserva o código executável exatamente e comprime apenas comentários/docstrings. Arquivos não suportados e sensíveis à sintaxe, como diffs, configurações, lockfiles, SQL e arquivos .env ainda são recusados a menos que você passe --force; a saída forçada é apenas para leitura exploratória, não para edições exatas ou comandos de copiar e colar.

As configurações padrão persistentes ficam na configuração do usuário e podem ser alteradas pelo 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 arquivo suportados:

Modo	Comportamento
auto	Prosa usa compressão normal; código suportado usa code-comments.
prose	Trata toda a entrada como linguagem natural.
code-comments	Preserva o código executável exatamente e comprime apenas comentários/docstrings.
raw	Retorna o arquivo inalterado com estatísticas.
refuse	Rejeita a compressão do arquivo.

Linguagens iniciais cientes de código: Python, JavaScript, TypeScript, JSX, TSX, Go e Rust.

diff marca tokens excluídos assim:

kept words [-deleted words-] kept words

Agente + MCP

ContextCrumb inclui um adaptador MCP stdio opcional para clientes de agentes que podem executar ferramentas Python através de uvx.

pip install "contextcrumb[mcp]"

Configuração MCP do pacote publicado:

{
  "mcpServers": {
    "contextcrumb": {
      "command": "uvx",
      "args": [
        "--from",
        "contextcrumb[mcp]",
        "contextcrumb-mcp"
      ]
    }
  }
}

O servidor MCP expõe:

compress_text
compress_file

ContextCrumb também acompanha contextcrumb-shrink, um proxy MCP que comprime descrições verbosas de catálogos antes que um agente as veja, enquanto encaminha nomes de ferramentas, esquemas, chamadas, resultados e conteúdos de recursos inalterados. Isso é útil quando um cliente de agente gasta contexto e uso de assinatura repetidamente apenas olhando descrições longas de ferramentas.

Modelo

Os pesos do modelo e uma demonstração hospedada são públicos no Hugging Face:

• Modelo: ymao20/contextcrumb-32m
• Playground: contextcrumb-32m-demo

Roteiro

Planejado para depois:

• Documentação pública para modos avançados de compressão e implantação de serviços.
• Cliente JavaScript ou TypeScript.
• Experimentos de API hospedada.
• Publicação no npm.

Desenvolvimento

uv pip install --python .\.venv\Scripts\python.exe -e ".[dev,mcp]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m build

As notas de versão são rastreadas em CHANGELOG.md.

Licença

MIT. Veja LICENSE.