Materialização e sincronização

Quando a base aparece para o agente, e como o que ele escreve volta para ela.

Camada funcional

Quando o agente começa a trabalhar, as bases de conhecimento ligadas a ele aparecem como pastas de arquivos dentro do próprio ambiente de execução. Ele lê com as ferramentas normais de arquivo — sem busca vetorial. Se ele escrever, editar ou apagar algo ali, a mudança volta para a base sozinha, sem ninguém copiar nada à mão.

Quando a base aparece

Uma base recém-vinculada a um agente não aparece na hora: ela só passa a existir como pasta de arquivos a partir da próxima execução depois de o vínculo ser criado. Em execuções seguintes, se o conteúdo da base não mudou desde a última vez, a preparação é praticamente instantânea — só refaz o trabalho quando algo de fato mudou.

Quando a mudança volta para a base

• Escrever ou editar um arquivo sincroniza de volta para a base na hora, ainda durante a execução.
• Operações em lote — mover, copiar ou apagar vários arquivos de uma vez, por exemplo, por comandos de terminal — são reconciliadas com a base ao final da execução, não instantaneamente. Não são imediatas, mas são confiáveis: a base termina refletindo o resultado — com uma exceção desde 04/09/2026, quando a operação esvazia a pasta por inteiro. Nesse caso os documentos ficam, e sair desse estado exige uma ação explícita: ver "Quando a listagem falha" abaixo.
• Apagar um arquivo apaga o documento correspondente na base. A remoção viaja pelo mesmo caminho de volta que a escrita — com uma salvaguarda (04/09/2026): ver "Quando a listagem falha" abaixo.

Quando a listagem falha, nada é apagado por engano (04/09/2026)

Havia um jeito de perder documento sem ninguém ter mandado apagar nada: se a leitura da pasta de arquivos do agente falhasse no meio, a sincronização podia entender o resultado incompleto como "o agente apagou tudo" e remover os documentos correspondentes na base. O problema nunca esteve na exclusão — estava em tratar uma leitura que falhou como se fosse uma leitura que voltou vazia.

Agora a exclusão em lote só acontece quando a leitura é confiável, por duas regras:

1. Leitura incompleta não decide exclusão. Se não deu para confirmar o que a pasta tem de fato, a sincronização não conclui que algo sumiu.
2. Leitura completa que não acha nada, numa base que tem documentos, também não apaga. Uma base esvaziada de verdade é indistinguível, à primeira vista, de uma leitura que falhou sem avisar — e errar para um lado custa muito mais caro que errar para o outro.

A troca é deliberada, e vale ser explícito sobre o preço dela: a base fica à frente do que está no computador do agente, e isso não se desfaz sozinho. Se você apagou de verdade todos os arquivos da pasta de uma base, a leitura seguinte vai encontrar a pasta vazia outra vez e cair na mesma regra — os documentos continuam registrados. Não é uma defasagem que a próxima execução acerta; é um estado que espera uma ação sua.

E há um caminho para ela: quem quer mesmo esvaziar uma base faz isso pela tela ou pedindo ao agente, e aí a exclusão acontece. A salvaguarda vale só para o caminho silencioso — o da sincronização automática, que é onde o estrago acontecia sem ninguém ver. Perder documento por engano é pior que precisar apagar de propósito.

Quando duas escritas colidem

Se alguém edita o mesmo documento por fora enquanto o agente está escrevendo nele, a escrita mais recente é recusada em vez de sobrescrever em silêncio o que a outra pessoa fez. Quem perde a corrida precisa tentar de novo.

Essa garantia só valia por completo no caminho em lote até 09/09/2026 — ver a seção seguinte.

Perda de conteúdo por ler um arquivo: incidente de 08/09/2026, corrigido em 10/09/2026

Em produção, um documento ganhou uma seção nova e a perdeu de volta poucos minutos depois, sem ninguém ter mandado apagar nada. A causa, isolada e reproduzida em teste no dia seguinte: uma sessão que só leu o arquivo — bastava nomear o caminho num comando de leitura, sem escrever nada — disparava o mesmo aviso de "o agente mexeu aqui" que uma escrita de verdade, e esse aviso regravava o arquivo com a cópia antiga, do momento em que aquela sessão tinha começado. Quanto mais tempo uma sessão ficasse aberta sem escrever, mais velha era a cópia que ela carregava de volta ao simplesmente ler.

Havia um segundo problema por trás, mais sério: o caminho rápido de sincronização (o que grava a mudança na hora, "ainda durante a execução", descrito acima) gravava o conteúdo do sandbox sem nenhuma das duas proteções que o caminho em lote já tinha desde agosto — nem a checagem de "o conteúdo mudou mesmo" nem a recusa por versão descrita na seção anterior. Era uma assimetria entre dois caminhos que escrevem na mesma base: bastava uma sessão comprida nomear o arquivo por engano para o caminho rápido devolver a cópia congelada de quando ela abriu, e a corrida por edição simultânea (a mesma que a seção anterior descreve) não protegia esse caminho.

Corrigido em 10/09/2026:

• O caminho rápido passou a diferenciar ler de escrever pela mesma regra que já valia no caminho em lote — só comando que escreve de fato dispara o aviso e a regravação.
• O caminho rápido ganhou as duas proteções que faltavam: a checagem de conteúdo (não regrava se o agente não mudou nada) e a recusa por versão (a mesma da seção anterior), com o conflito registrado em vez de ser engolido em silêncio.
• Um efeito colateral do próprio acerto foi encontrado e fechado no mesmo dia: apagar um documento e recriá-lo em seguida, na mesma execução, podia deixar a "memória" de curto prazo da sincronização fora de ordem — em certas sequências, o arquivo sobrevivia no disco do agente mas a base "esquecia" dele, e a próxima sincronização apagava o arquivo por engano. A ordem das duas etapas (tirar da memória de curto prazo, depois apagar de fato) passou a ser uma peça própria e testada.
• Essa mesma "memória de curto prazo" (o que a sincronização acumula sobre cada arquivo durante uma execução) não sobrevivia corretamente entre uma execução e a próxima: ficava presa na pasta errada quando o agente usa um ambiente compartilhado entre conversas, e não era limpa ao final do turno — então o estado de ontem podia rebaixar ou apagar informação que deveria valer hoje.
• Uma falha passageira ao ler um arquivo (a mesma que, em 04/09/2026, já tinha motivado a guarda "leitura incompleta não decide exclusão" descrita acima) ainda conseguia, por outra porta, ser confundida com "o agente apagou este arquivo" e levar o documento junto. Agora só conta como ausência a resposta que diz, com todas as letras, que aquele arquivo não existe — qualquer outra falha de leitura não decide mais exclusão nenhuma.
• Mais formas de escrever pelo terminal que escapavam da classificação de leitura — edição de texto no lugar, busca que grava no arquivo encontrado, entre outras — passaram a ser reconhecidas como escrita.

O efeito prático de todo o pacote: a garantia da seção anterior — o que já está guardado vence, e a escrita apoiada numa versão vencida é recusada em vez de sobrescrever — agora vale igual nos dois caminhos, em lote e por arquivo. E uma sessão que só leu um arquivo não tem mais como reescrevê-lo com uma cópia velha.

O que dá para fazer

Limites conhecidos

• Teto de tamanho: uma base com mais de 200 mil documentos ultrapassa o que a preparação consegue trazer para dentro do ambiente do agente; o excedente não aparece.
• Reconhecer que "algo mudou" ficou mais preciso e mais barato (04/09/2026). A plataforma descobria que o agente havia mexido na base lendo o texto do comando que ele rodou, à procura do caminho da pasta. Funcionava por coincidência: bastava o agente entrar na pasta antes de escrever, e o caminho deixava de aparecer no comando — a mudança escapava. Agora vale a pasta em que ele estava de fato, o que fecha esse buraco. Na outra ponta, qualquer menção à base disparava a releitura inteira ao final da execução, mesmo quando o agente só tinha lido algo; hoje só o que de fato escreve dispara, o que poupa releitura de bases grandes à toa.