Bases e documentos

Camada funcional

Uma base de conhecimento é um conjunto de documentos que o agente lê. Cada documento é um arquivo markdown, e o caminho do arquivo é a identidade do documento — inclusive as "pastas", que são convenção dentro do nome. Quem organiza por pastas ganha navegação; nada disso é mágica de banco.

O modelo é wiki, não busca vetorial

O agente encontra informação lendo e buscando texto nos arquivos, não por similaridade semântica. Um modo antigo baseado em busca vetorial foi removido do produto: não há mais geração de representações numéricas do texto nem busca por proximidade de significado. Todas as bases existentes foram migradas para o modelo atual, sem perda de conteúdo.

Consequência prática para quem organiza uma base: nome de arquivo, estrutura de pastas e títulos importam muito mais do que importariam num sistema de busca por similaridade. Um bom nome é o que faz o documento ser encontrado.

Onde cada coisa mora

A identidade é o caminho. Quando o próprio agente escreve o arquivo, o caminho que ele usou é preservado como está, sem derivar slug nem sufixo — justamente para não mutilar a identidade que ele escolheu.

Abrir um documento (mudou em 03/09/2026)

O documento abre numa página própria, com o conteúdo renderizado como markdown — títulos, listas, tabelas e blocos de código aparecem formatados, não mais como texto cru. A página da base se organiza em três seções: Documentos (a lista), Quem usa (os agentes que consultam a base e os times por onde ela circula) e Configurações. Uma linha de documento com erro mostra o motivo e o botão para reenviar.

Caminho único de escrita

Toda escrita passa pelo mesmo caminho, seja o upload pela interface ou a sincronização feita pelo agente:

resumir (quando aplicavel) -> subir o arquivo
   -> gravar o metadado do documento
   -> recalcular a contagem de documentos da base

Duas chaves de comportamento:

• Resumo opcional. A sincronização feita pelo agente pula a regeneração do resumo para não atrasar a execução; o upload pela interface deixa ligado e ganha resumo novo.
• Concorrência otimista. Quem informa a versão que leu só sobrescreve se o documento ainda estiver naquela versão; caso contrário, recebe um conflito em vez de sobrescrever o trabalho de outro. Quem não informa versão assume o comportamento de "última escrita vence" — o caminho de quem é a fonte da verdade no momento em que escreve (upload pela interface, criação de documento).

O que dá para fazer

Limites conhecidos

• Não há busca semântica. Base gigante sem estrutura de pastas fica difícil de navegar — o remédio é organização, não um mecanismo de busca por significado.