Como funciona a base de conhecimento

A base de conhecimento guarda o que a IA deve saber sobre o seu negócio e não consegue aprender com o próprio correio: preços, políticas, horários de funcionamento, factos sobre produtos e a forma como a sua equipa responde. Adiciona notas, ficheiros e páginas web, e a IA lê as partes que interessam sempre que escreve por si.

Há um repositório por espaço de trabalho, com três níveis, para que uma resposta que só vale para uma marca ou uma equipa fique com ela. Lê-se e altera-se na aplicação em Espaço de trabalho → Base de conhecimento, através da API REST, a partir dos SDK e da CLI, e pelo assistente e pelos clientes MCP.

Cada item está num nível, o seu scope. A IA que escreve para um endereço lê esse endereço, depois o seu domínio, depois todo o espaço de trabalho, e quando dois itens se contradizem ganha o mais específico.

• —Um endereço com sinal de mais lê também o seu endereço base, por isso [email protected] usa o que está guardado para [email protected].
• —GET /knowledge/levels lista cada nível que pode ver, quantos itens tem cada um e se pode alterar itens aí.
• —Mover um domínio para outro espaço de trabalho leva consigo os itens guardados para esse domínio e os seus endereços.

• —Uma nota é texto que escreve no próprio local, até 20.000 caracteres, em Markdown se quiser. Costuma estar pronta para a IA em um ou dois segundos.
• —Um ficheiro é lido como texto em segundo plano: PDF, documentos Word, folhas de cálculo (Excel, OpenDocument, Numbers e CSV), texto OpenDocument, HTML, XML, Markdown, texto simples, JSON e imagens (JPEG, PNG, WebP e SVG). Um documento pode ter até 20 MB e uma imagem até 10 MB.
• —Uma página web é obtida de um endereço http ou https público e lida em segundo plano, até 5 MB dela. Um nível guarda uma página uma só vez, e atualizá-la obtém-na de novo depois de mudar.
• —De um item são guardados até 1.000.000 de caracteres de texto, e o texto é dividido em trechos sob os seus títulos para a pesquisa.

Um item está queued e depois processing enquanto é lido, ready quando a IA já o pode usar, e failed com um failure que diz porquê quando não pôde ser lido. Um item alterado volta a queued, e a IA continua a usar o texto anterior até o novo estar pronto. Atualizar um item volta a lê-lo e limpa uma falha.

• —As sugestões de resposta sob a última mensagem de uma conversa leem os níveis do endereço a que a mensagem chegou.
• —Um rascunho escrito a partir de uma descrição, no editor ou com POST /emails/compose, lê os níveis do endereço de onde sai. A resposta lista em sources os itens em que se baseou.
• —O assistente lê os níveis da conversa que tem aberta, ou cada nível que pode ver quando nenhuma está aberta, e pode pesquisar ele próprio a base de conhecimento com a sua ferramenta searchKnowledge.
• —A resposta de GET /threads/{id}/reply-suggestions lista em sources os itens em que as sugestões se basearam.

As notas afixadas entram em cada prompt do seu nível, até 2.000 caracteres por nível, quer correspondam ou não ao que se está a escrever. O resto do espaço, cerca de 6.000 caracteres no total, vai para os trechos que melhor correspondem ao pedido, encontrados pelo significado e pelas palavras. Quando o índice não responde num instante, a IA escreve sem ele em vez de o fazer esperar.

Adicione itens na aplicação em Espaço de trabalho → Base de conhecimento, ou a partir de código com a API, os SDK e a CLI. O assistente e os clientes MCP podem guardar uma nota ou adicionar uma ligação quando lhes pede para se lembrarem de algo, e também podem alterar, atualizar e eliminar itens. Na conversa da aplicação, adicionar, alterar e atualizar um item perguntam primeiro a menos que o tenha pedido, e eliminá-lo pergunta sempre primeiro.

Cada item regista de onde veio em origin: app, api, assistant ou mcp, e quem o adicionou em createdBy.

Também cresce sozinha. A IA sugere notas a partir das respostas da sua equipa e anota as perguntas a que nada responde ainda, os conectores mantêm atualizados sites inteiros, sitemaps, feeds e centros de ajuda, e as ligações podem ser lidas de novo segundo um calendário. As secções seguintes explicam cada um.

Quando alguém do espaço de trabalho responde numa conversa, a IA lê a resposta e a mensagem a que responde, e sugere até três factos que valeriam também para outras pessoas, como um preço, uma política ou um prazo de entrega. Cada sugestão é uma nota à espera de revisão, ao nível do domínio a partir do qual a resposta foi enviada, ou de todo o espaço de trabalho quando esse domínio não é um dos seus. Os factos que a base de conhecimento já tem ficam de fora, e são lidas até 100 respostas por dia.

Reveja-as na aplicação ou com GET /knowledge/suggestions. Aceite uma para a guardar como nota, alterando pelo caminho o título, o texto, o nível ou se está afixada, ou descarte-a. O mesmo facto sugerido de novo soma em occurrences em vez de acrescentar uma segunda sugestão, e uma sugestão descartada não volta a ser sugerida.

Quando a IA sugere respostas a uma mensagem recebida, também anota até três coisas que o remetente perguntou sobre o negócio e a que nem a conversa nem a base de conhecimento respondem, como se envia para o país dele. Cada uma torna-se uma pergunta ao nível do domínio onde a mensagem chegou, ou de todo o espaço de trabalho quando esse domínio não é um dos seus, e a mesma pergunta feita de novo soma em occurrences, para que veja quais surgem mais.

Responda a uma pergunta e ela torna-se uma nota: aceite-a com a resposta como texto, e o título continua a ser a pergunta, a menos que o altere. A partir daí, a IA usa a resposta sempre que a pergunta surge. Descarte uma pergunta que não precisa de resposta e ela não volta a ser anotada.

Cada item é comparado com os itens mais próximos de todos os níveis quando é indexado, e de novo sempre que muda. Dois itens que dizem quase o mesmo são marcados como duplicate. Dois itens muito relacionados que discordam num facto, como um preço ou um prazo, são marcados como conflict, com uma frase sobre o que discorda. A IA procura conflitos até 200 vezes por dia.

• —Cada item conta em flags os avisos abertos que o nomeiam, e GET /knowledge/flags lista-os, dos mais recentes para os mais antigos.
• —Altere ou elimine um dos dois itens para resolver um aviso. Um item alterado é comparado de novo quando fica indexado.
• —Descarte um aviso quando os dois itens estão bem como estão, e o mesmo par não volta a ser marcado pelo mesmo motivo.
• —Um aviso só é visível para quem consegue ver os dois itens.

Um conector mantém na base de conhecimento muitas páginas de uma mesma fonte, cada página como um item de ligação ao nível do conector, e mantém-nas atualizadas quando a fonte muda.

• —A primeira sincronização começa em menos de um minuto. Depois volta a sincronizar a cada 7 dias, ou a cada 1 ou 30 dias, ou só quando pedir uma sincronização, que também começa em menos de um minuto.
• —Mantém até 25 páginas, ou tantas quantas definir até 200, e os seus itens contam para a quota do plano. Uma sincronização deixa de acrescentar páginas assim que a quota é atingida.
• —Cada sincronização acrescenta as páginas novas, volta a ler as que mudaram e remove os itens das páginas que já não estão na fonte.
• —Uma página que adicionou como ligação ao mesmo nível fica com esse item, e eliminar um conector remove apenas os itens que ele acrescentou.
• —Mover um conector para outro nível move os seus itens com ele.

Uma ligação pode ser lida de novo sozinha a cada 1, 7 ou 30 dias: defina refreshDays ao adicioná-la, ou mais tarde. Quando a página mudou, o novo texto substitui o antigo assim que é lido, e até lá a IA continua a usar o texto antigo. nextRefreshAt diz quando volta a ser lida, e uma página que não se consegue obter é tentada de novo no dia seguinte.

A IA pode ler uma conversa e redigir uma nota com os factos de que a equipa voltará a precisar, sem dados pessoais nem o que só importa nessa conversa. Nada é guardado até o conservar: leia o rascunho, altere-o como quiser e guarde-o como nota, que regista em threadId a conversa de onde veio.

O rascunho sugere um nível: o domínio onde a conversa chegou, se puder adicionar itens lá, ou então todo o espaço de trabalho ou o endereço. Cada rascunho é uma ação de IA. A partir de código, redija com POST /knowledge/drafts, que precisa de threads:read além de knowledge:write, e guarde com POST /knowledge/notes e o mesmo threadId.

Uma pesquisa encontra trechos pelo significado e pelas palavras. Envie rerank: true com POST /knowledge/search e a IA também lê os 25 melhores trechos e põe-nos na ordem que melhor responde à pergunta, deixando de fora os que não ajudam. Acrescenta um ou dois segundos e é uma ação de IA, por isso só acontece quando o pede. reranked na resposta diz se aconteceu, e quando não termina a tempo os trechos mantêm a ordem habitual.

GET /knowledge/stats mostra como a IA usou a base de conhecimento nos últimos 30 dias, ou até 90 se o pedir.

• —Quantas vezes uma sugestão de resposta, um rascunho, o assistente ou uma pesquisa encontrou algo, quantas vezes procurou e não encontrou nada, e a proporção que encontrou algo, dia a dia.
• —Onde essas utilizações aconteceram: compose, reply, chat, tool e search.
• —Os itens mais usados, e quantos itens prontos nunca foram usados. Cada item tem a sua própria contagem em uses, com lastUsedAt como a mais recente.
• —Quantas sugestões e perguntas aguardam revisão, e quantos avisos estão abertos.

A definição do espaço de trabalho knowledgeLearning está ligada por predefinição. Desligue-a com PATCH /settings e { "knowledgeLearning": false } e a IA deixa de ler as respostas enviadas à procura de factos para sugerir, deixa de anotar perguntas do correio recebido e deixa de verificar conflitos entre os itens. Os duplicados continuam a ser marcados, e o que já foi sugerido fica para o aceitar ou descartar.

• —Ler requer knowledge:read e alterar knowledge:write, que inclui a leitura. As funções incorporadas Admin, Member e Developer podem alterar itens, Viewer pode lê-los, e Billing não os alcança.
• —Alterar um item requer alcançar cada endereço que o seu nível abrange: todo o espaço de trabalho requer todos os endereços, um domínio o domínio inteiro, e um endereço esse endereço. Uma chave ou uma aplicação limitada a certos endereços só pode alterar itens nesses endereços, ou em domínios que tenha inteiros.
• —Quem está limitado a certos endereços lê os itens de todo o espaço de trabalho e os dos seus endereços e dos domínios desses endereços. O assistente e as ferramentas MCP que agem por essa pessoa só adicionam e alteram itens nos endereços a partir dos quais pode enviar.

• —O texto de cada item é cifrado em repouso: o conteúdo de uma nota, o texto lido de um ficheiro ou de uma página, e cada trecho. As palavras que a pesquisa por palavras compara são guardadas como hashes com chave, não como palavras.
• —Os ficheiros são convertidos em texto e as páginas web são lidas pelo OpenEmail. A política de privacidade indica cada serviço que trata os seus dados.
• —Para pesquisar pelo significado, cada excerto e cada pergunta são transformados num vetor: uma lista de números que descreve o seu assunto. Os vetores ficam guardados sem cifra ao lado do texto cifrado, tal como na pesquisa pelo significado no correio.
• —Os trechos que um prompt usa vão para o modelo de IA que escreve a resposta, o rascunho ou a réplica, tal como o resto do prompt.
• —Eliminar um item remove de uma vez o seu ficheiro, o seu texto e os seus trechos. A base de conhecimento faz parte de uma exportação do espaço de trabalho, e eliminar o espaço de trabalho elimina-a.
• —Enquanto a aprendizagem está ligada, o modelo de IA lê cada resposta enviada numa conversa, com a mensagem a que responde, para sugerir notas, e lê dois itens muito relacionados para verificar se se contradizem. A definição knowledgeLearning desliga ambas as coisas.

Tudo o que está acima está na API REST em /knowledge, nos SDK como openemail.knowledge (TypeScript) e client.knowledge (Python, Ruby e PHP), na CLI como openemail knowledge, e nas ferramentas MCP. Uma chave precisa de knowledge:read para ler e de knowledge:write para alterar itens.