Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Uso de memória

Status: Atual

Escopo: estado atual

Última revisão: 2026-09-13

Responsável: runtime do ax-code

O AX Code divide a máquina com servidores de linguagem, compilações do repositório, navegadores e qualquer runtime de modelo local. Um servidor TypeScript ou o rust-analyzer pode usar mais memória do que o próprio backend do AX Code. Esses processos fazem análise de código; não são serviços de voz. Somar o RSS dos processos pode contar páginas compartilhadas mais de uma vez.

Perfis

AX_CODE_MEMORY_PROFILE aceita auto (padrão), low ou normal. Em auto, um host que informa no máximo 8 GiB de RAM física seleciona low; os demais hosts selecionam normal. Valores inválidos usam detecção automática. A detecção usa a RAM física do host, não a RAM livre nem um limite de memória de contêiner; selecione low de forma explícita em uma VM ou em um contêiner restrito, quando for necessário. Defina a variável antes de iniciar o AX Code; ela não reconfigura um backend que já esteja em execução.

AX_CODE_MEMORY_PROFILE=low ax-code

PowerShell:

$env:AX_CODE_MEMORY_PROFILE = "low"
ax-code

Os servidores de linguagem iniciam sob demanda, por padrão, nos dois perfis. A inicialização e as leituras comuns de arquivo não disparam o pré-aquecimento semântico especulativo. Navegação semântica explícita, diagnósticos e indexação ainda iniciam a análise necessária, então o primeiro pedido semântico pode demorar mais. Para restaurar o pré-aquecimento especulativo de inicialização e de leitura em um host com margem adequada, defina as duas variáveis antes de iniciar:

AX_CODE_MEMORY_PROFILE=normal AX_CODE_LSP_PREWARM=1 ax-code

Somente o valor exato 1 ativa o pré-aquecimento especulativo; low sempre o suprime. Esta configuração não encerra servidores já existentes e não é uma proibição global de iniciar o LSP: edições que exigem diagnóstico e operações explícitas de semântica ou de indexação ainda usam servidores de linguagem. A recuperação de ociosidade do modo baixo continua separada.

O cache de código-fonte também tem limite de 1.000 entradas. A contabilização inclui uma folga conservadora de texto e de chave; não é um limite de heap do V8 nem de RSS. Um arquivo que não cabe ainda sincroniza o conteúdo atual completo com o servidor de linguagem. A remoção do cache não fecha um documento enquanto um pedido ainda puder precisar dele.

O modo baixo enfileira o trabalho, em vez de omitir a análise. O primeiro uso, ou o uso depois de um encerramento por ociosidade, pode demorar mais. Clientes selecionados ou enfileirados, RPCs subjacentes pendentes e esperas de diagnóstico ficam protegidos contra o encerramento por ociosidade. Um pedido com tempo esgotado pode deixar trabalho em execução no servidor: duas operações aguardadas não garantem apenas dois cálculos dentro dos servidores de linguagem. O inventário de diagnóstico é marcado como degradado depois da recuperação por ociosidade, porque reiniciar um arquivo não prova a cobertura completa do workspace anterior.

Estes limites valem dentro de cada processo do AX Code. Eles não limitam a RAM total, não coordenam instâncias separadas do AX Code, não impõem teto aos heaps dos servidores de linguagem e não controlam um compilador, um navegador ou um modelo local. A seleção de modelo, o contexto exigido do prompt e os comandos de verificação permanecem iguais.

Retenção de sessão e de evidência

A TUI guarda os eventos pesados da transcrição da sessão em exibição. Sessões inativas conservam resumos, status e aprovações ou perguntas pendentes; abri-las recarrega o histórico salvo a partir do SQLite. A janela normal de exibição tem 100 mensagens e um orçamento de 16 MiB de payload serializado. Mensagens antigas e completas são liberadas primeiro. A mensagem indivisível mais recente e o histórico recuperado de Desfazer/Restaurar podem ultrapassar o orçamento flexível; a TUI mostra um indicador. São limites de projeção, não limites do histórico durável da sessão nem do contexto do modelo.

Quando o heap do V8 se aproxima do limite rígido, o orçamento da transcrição diminui sozinho (até um piso de 2 MiB com 90% de uso do heap), para que o conjunto retido encolha antes de o processo chegar a FatalProcessOutOfMemory; acima de 80%, a TUI também mostra um aviso que sugere /compact ou um reinício. A pressão volta ao normal depois de um GC completo, mas o histórico já descartado continua ausente até ser recarregado.

Partes que chegam antes da mensagem pai usam uma área pendente limitada (128 IDs de mensagem / 1 MiB). Se o conteúdo pendente precisar ser liberado, a TUI oferece recarregar a partir do histórico salvo. Eventos tardios de mensagens já descartadas não podem recriar, de forma permanente, partes órfãs.

O cache de evidência usa, por padrão, memória limitada (128 entradas / 4 MiB de valores serializados por instância). O RocksDB continua opcional e explícito; mudar apenas o backend do cache não reduz as chamadas de ferramenta do modelo. Veja Cache de evidência.

Saída de comando em segundo plano

A saída de segundo plano ainda não lida usa arquivos transitórios privados, em vez de reter textos JavaScript de vários megabytes para cada shell concluído. Cada arquivo é um anel UTF-8 de 2 MiB; a saída não lida mais antiga, além desse limite, é descartada e rotulada. Até 32 arquivos de anel reservam no máximo 64 MiB por processo. Quando as vagas em disco estão cheias, o spool concluído mais antigo pode expirar; a posse de um shell ativo não é removida. As leituras devolvem, aos poucos, a saída não lida que foi retida e liberam a vaga de disco correspondente.

O registro permite 16 shells ativos por sessão e 32 por processo, e retém no máximo 16 registros concluídos por sessão e 64 por processo. A saída concluída expira após 30 minutos (conferida no acesso e cerca de uma vez por minuto). As listagens de comando e de descrição são prévias limitadas a 8 KiB e 1 KiB; o comando executado não muda. A reprodução do observador tem limites separados de 64 KiB e de 128 registros por shell, com orçamento de 2 MiB de bytes para o processo inteiro; uma reprodução incompleta fica rotulada.

bash_output informa a integridade da saída à parte do status real de saída do processo. Saída descartada, expirada ou ilegível é evidência incompleta de verificação, mesmo quando o comando terminou com código zero. Esses avisos continuam visíveis quando se usa um filtro de saída. Um registro ausente pode significar que ele já foi consumido ou descartado; saída indisponível não prova que uma verificação tenha passado.

Os arquivos usam um diretório temporário privado, pertencente ao processo (0700), e arquivos 0600 no POSIX. Leituras, remoção da sessão, limpeza da retenção e o encerramento normal do processo liberam os arquivos sob posse dele. O spool não é armazenamento de sessão que resista a uma falha. Um encerramento forçado, ou uma queda, pode deixar para trás um diretório temporário privado; a varredura automática entre processos não está implementada, então o limite de 64 MiB descreve o processo atual, e não sobras acumuladas de quedas. Erros de limpeza do sistema de arquivos são informados e não liberam a reserva de cota do arquivo que falhou. A E/S de arquivo síncrona e limitada evita filas de escrita sem teto, mas pode acrescentar latência em um sistema de arquivos temporário lento.

Escolher a carga de trabalho

Em hosts com poucos recursos, comece com um provedor de nuvem, uma sessão ativa de programação e um repositório pequeno. Execute compilações grandes e sessões adicionais de agente somente quando a máquina tiver margem. A inferência local precisa de um orçamento separado para pesos, cache KV, contexto e sobrecarga do runtime; a orientação de hardware de um provedor de nuvem não se aplica a ela.

Use a CLI empacotada no uso comum; pnpm run dev é um fluxo de código-fonte para quem contribui, com outro custo de inicialização e de carga de módulos. Inspecione o AX Code junto com os processos filhos de servidor de linguagem e de compilação no Activity Monitor, ou no monitor de processos da plataforma. Um limite menor de cache não estabelece uma redução fixa da memória física.

As mudanças de memória têm testes determinísticos de retenção e de equivalência semântica. Elas não foram qualificadas por um teste de carga em um Mac físico de 8 GB. O modo baixo não garante que um projeto qualquer caiba em uma máquina de 8 GB.