Bases de Conhecimento Locais

Uma base de conhecimento local é uma pasta comum de arquivos Markdown que você escreve e organiza no VelaTerm. As notas e os anexos ficam nessa pasta, então você pode continuar a editá-los com outros editores. Alguns itens de menu chamam a base de conhecimento local de "caderno"; os dois termos se referem à mesma pasta.

A "Base de conhecimento de sessões" integrada fica ao lado das suas bases de conhecimento locais. Ela guarda o conhecimento que os agentes organizam a partir das suas sessões e mantém entradas, fontes e histórico de revisões próprios; consulte Base de Conhecimento de Sessões.

Abertura da base de conhecimento

Clique no ícone de conhecimento no painel direito (dica "Base de conhecimento"). Uma aba "Base de conhecimento" é aberta no centro com a página inicial:

uma caixa de busca ("Pesquise no conhecimento das sessões e nas notas locais…"; consulte a seção Busca abaixo);
a "Base de conhecimento de sessões";
suas "Bases de conhecimento locais";
os botões "Abrir base de conhecimento" e "Criar base de conhecimento".

O painel direito mostra uma árvore com três raízes: "Base de conhecimento de sessões", "Sessões arquivadas" e "Bases de conhecimento locais". Clique em uma seta para expandir uma pasta ali mesmo; várias bases de conhecimento podem ficar expandidas ao mesmo tempo. Clique no nome de uma pasta para ver o conteúdo dela e clique em uma nota para abri-la. O link "Bases de conhecimento", no topo da árvore, volta à página inicial, e o botão "Subir um nível", no cabeçalho de uma página, leva à página superior sem sair da base de conhecimento.

As notas são abertas em abas de documento comuns, com os mesmos recursos de edição, salvamento, busca e exportação para PDF de qualquer outro arquivo Markdown (consulte Abas de Documento e Navegador). A aba "Base de conhecimento" permanece na barra de abas para que você possa voltar ao ponto onde estava.

Abertura ou criação de uma base de conhecimento local

Abrir: clique em "Abrir base de conhecimento" e escolha uma pasta. O aplicativo desktop mostra o seletor de pastas do sistema; um cliente no navegador mostra um navegador de pastas do computador conectado. Um cofre (vault) existente do Obsidian pode ser aberto diretamente: os arquivos ficam onde estão, e pastas ocultas como .obsidian não são indexadas nem alteradas.
Criar: clique em "Criar base de conhecimento", informe um "Nome", escolha uma "Pasta" (ou use "Procurar"; a sugestão é ~/Notes) e confirme. O VelaTerm cria a pasta e a abre. A pasta superior precisa existir, e não pode haver uma pasta com o mesmo nome; caso contrário, o VelaTerm mostra "O destino já existe. Escolha outro nome ou pasta." Para usar uma pasta existente, escolha "Abrir base de conhecimento".
Renomear: clique com o botão direito em uma base de conhecimento na árvore e escolha "Renomear". Isso renomeia a pasta no disco.
Fechar: clique em "Fechar caderno" na barra de ferramentas da base de conhecimento ou clique com o botão direito nela na árvore. Fechar remove a pasta da lista; os arquivos continuam no disco. Quando você abre a mesma pasta de novo, a lixeira e o histórico de importações dela continuam lá.

"Local" significa o computador que executa o backend do VelaTerm ao qual você está conectado. Em um cliente no navegador, "Abrir base de conhecimento" navega pelas pastas desse computador, e a importação envia para ele os arquivos que você escolhe no navegador.

Importação de arquivos e pastas

Abra a base de conhecimento de destino e clique em "Importar" na barra de ferramentas dela.
Escolha a "Pasta" de destino e depois "Escolher arquivos" ou "Escolher pasta", ou arraste arquivos e pastas para a área de importação.
Confira a lista e confirme.

A importação é executada em segundo plano, então você pode trocar de página ou abrir notas enquanto os arquivos são copiados. O progresso aparece na barra de ferramentas da base de conhecimento e na página inicial, e a importação pode ser cancelada na caixa de diálogo de importação ou em "Histórico de importações". Ao final, um aviso mostra o número de arquivos importados e ignorados; se a janela não estiver em foco, aparece uma notificação do sistema ("Importação concluída" ou "Falha na importação"). Só é possível executar uma importação por vez em cada base de conhecimento.

A importação copia os arquivos como estão, incluindo nomes de arquivos com caracteres não ASCII, a estrutura relativa de pastas e os anexos, e nunca modifica os originais. Ao importar uma pasta, a própria pasta é incluída. Se algum arquivo for sobrescrever um existente, o lote inteiro é rejeitado. Arquivos ocultos e pastas de configuração ocultas são ignorados. Os seletores de arquivos do navegador não fornecem pastas vazias, por isso pastas vazias não são importadas.

Uma importação pode conter até 5.000 arquivos (os arquivos ocultos ignorados entram nessa contagem) e até 1 GiB no total, com no máximo 100 MiB por arquivo. Os arquivos ficam primeiro em uma área temporária e só aparecem no destino depois que o lote inteiro chega; assim, um envio interrompido nunca aparece como uma nota escrita pela metade.

"Histórico de importações" lista cada importação com o horário, o destino ("Raiz da base de conhecimento" para a pasta principal), o status ("Importando", "Concluída", "Falhou", "Cancelada" ou "Interrompida"), o número de arquivos importados e ignorados, o tamanho e a duração. Clique em "Arquivos (N)" para ver cada arquivo e o motivo pelo qual foi ignorado. "Excluir registro" remove o item do histórico; os arquivos importados não são removidos. Uma importação cujo progresso tenha parado por mais de dois minutos, por exemplo porque o aplicativo foi fechado inesperadamente, é marcada como "Interrompida"; excluir o registro dela também remove os arquivos que estavam na área temporária.

Escrita e organização de notas

A página de uma base de conhecimento tem as visualizações "Notas recentes", "Lixeira" e "Histórico de importações", um botão "Nova nota" e, na barra de ferramentas, os botões "Nova pasta", "Importar" e "Fechar caderno". A lista de notas pode ser filtrada por etiqueta ("Todas as etiquetas") e ordenada por "Atualização recente" ou "Título".

Enquanto a página de uma base de conhecimento está aberta, ⌘N / Ctrl+N cria uma "Nova nota", ⌘O / Ctrl+O abre a "Abertura rápida" (para encontrar uma nota pelo caminho) e ⌘⇧F / Ctrl+Shift+F leva à caixa "Pesquisar notas…".
Para renomear uma nota, clique com o botão direito nela na árvore e escolha "Renomear". Para movê-la, arraste-a para outra pasta da mesma base de conhecimento. "Excluir" a envia para a lixeira da base de conhecimento.
Com uma pasta aberta, "Renomear ou mover" move a pasta para um caminho relativo à raiz da base de conhecimento; a pasta superior já precisa existir. Quando uma nota ou pasta é movida, os links nas outras notas da mesma base de conhecimento são atualizados, mantendo o texto do link e sem alterar os trechos de código.
Os itens excluídos vão para uma pasta .vkb-trash dentro da base de conhecimento. Abra "Lixeira" e clique em "Restaurar" para recuperar um item; um arquivo existente com o mesmo nome nunca é sobrescrito.
As etiquetas vêm de #tag no texto e de uma lista ou array tags em YAML.
As imagens coladas em uma nota são salvas em uma pasta assets ao lado da nota.

A árvore e as listas são atualizadas aproximadamente a cada cinco segundos enquanto a página está visível e também quando a janela volta a ficar em foco. Uma aba de documento aberta detecta alterações feitas por outros programas e oferece a opção de recarregar.

As páginas da base de conhecimento, as caixas de diálogo, o histórico de importações, as buscas, o escopo da busca, as etiquetas, a ordenação e a abertura rápida têm URLs próprias; assim, você pode atualizar a página ou usar os botões voltar e avançar do navegador. O texto não salvo e o conteúdo dos formulários não fazem parte da URL.

Busca

Página inicial: pesquisa a base de conhecimento de sessões e todas as bases de conhecimento locais de uma vez e agrupa os resultados por origem. As sessões arquivadas não são incluídas.
Painel direito: "Pesquisar notas…", acima da árvore, pesquisa todas as bases de conhecimento locais.
Página da base de conhecimento: "Pesquisar notas…" pesquisa nomes, caminhos e texto das notas. "Escopo da busca" alterna entre "Esta base de conhecimento" e "Todas as bases de conhecimento".

Quando há várias palavras, todas precisam corresponder. Cada resultado mostra a base de conhecimento ou o grupo de sessões, um trecho, o número da linha, o número de correspondências e as "Notas relacionadas" para as quais a nota tem links; clique em qualquer um deles para abri-lo. Use as setas para cima e para baixo para selecionar um resultado, Enter para abri-lo e Esc para limpar a busca. Os resultados são ordenados primeiro pelas correspondências no nome ou no caminho, depois pelo número de correspondências e, por fim, pela atualização mais recente. São listados até 100 resultados; quando há mais, a lista termina com "Apenas os primeiros resultados são listados. Refine a busca para ver os demais."

O VelaTerm procura primeiro correspondências exatas e só recorre a correspondências aproximadas quando não encontra nenhuma, mostrando "Nenhuma correspondência exata. Exibindo resultados aproximados." A correspondência aproximada vale para palavras formadas por letras latinas e dígitos: letras em ordem (knwl encontra knowledge), iniciais (kb encontra knowledge base) e pequenos erros de digitação (um erro em palavras com quatro ou mais caracteres, dois em palavras com oito ou mais; knoledge encontra knowledge). Chinês e outros textos em alfabetos não latinos são comparados de forma exata.

Links e compatibilidade com arquivos existentes

O VelaTerm reconhece as formas comuns [[note]], [[folder/note|label]] e [[note#heading]], os links relativos padrão do Markdown e ![[image.png]]. Ele as usa para atualizar os links quando as notas são movidas, para listar as "Notas relacionadas" nos resultados da busca e nos comandos vkb descritos abaixo. No editor, os links [[…]] são exibidos como texto simples. Quando vários arquivos têm o mesmo nome, um link curto só é resolvido se o destino for único; caso contrário, escreva o caminho da pasta.

Os arquivos continuam sendo Markdown simples, e o front matter em YAML permanece no arquivo; o modo Código-fonte do editor o mostra exatamente como está. Arquivos Markdown que não estão em UTF-8 ou que têm mais de 5 MiB não são listados como notas e são contados em "Ignorados". Uma base de conhecimento pode conter até 50.000 arquivos e pastas; uma pasta maior não pode ser aberta e mostra "O arquivo ou a seleção excede os limites do caderno." Links simbólicos não são seguidos.

Esses recursos cobrem o trabalho do dia a dia com arquivos locais, pastas, Markdown, links e busca. Plugins, temas, Canvas, referências a blocos, notas incorporadas e aliases em YAML do Obsidian não são compatíveis; os arquivos correspondentes ficam inalterados. Para o modelo de arquivos e a sintaxe de links, consulte a documentação do Obsidian sobre cofres, links internos e anexos.

Cópia a partir da base de conhecimento de sessões e consultas de agentes

Abra uma entrada na base de conhecimento de sessões, escolha "Copiar para um caderno local" e depois selecione a base de conhecimento de destino e o nome do arquivo. A cópia é uma nota Markdown independente; a entrada original, os instantâneos de origem e o histórico de revisões dela permanecem onde estão.

Em uma sessão do VelaTerm, você ou um agente pode ler as bases de conhecimento locais registradas com vkb:

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes pesquisa todas as bases de conhecimento locais registradas no backend atual. Cada resultado inclui vaultId, vaultName, path, absolutePath, line, matches, score, matched (o texto que de fato correspondeu), related (as notas para as quais esta nota tem links) e summary (o texto em torno da correspondência). A resposta também informa total, hasMore, unavailable (bases de conhecimento que não puderam ser lidas) e fuzzy (se os resultados são aproximados). São retornados até 100 resultados.
note retorna o texto, a estrutura de títulos, os links, os backlinks e as etiquetas de uma nota.
search retorna correspondências da base de conhecimento de sessões, das notas locais e, quando existe um índice de código, do grafo de código (consulte Grafo de Código e Base de Conhecimento).

Esses comandos são somente leitura. Eles nunca alteram as notas, e o VelaTerm não adiciona o conteúdo das bases de conhecimento às sessões automaticamente.

Armazenamento e logs

Os arquivos no disco são a cópia oficial das suas notas e dos anexos. O banco de dados do aplicativo (tabelas kb_*) armazena apenas a lista de bases de conhecimento registradas, os registros da lixeira, o histórico de importações e um cache de busca que pode ser reconstruído. A base de conhecimento de sessões usa as próprias tabelas memory_*.

Abertura, escrita, movimentação, exclusão, restauração e importação são registradas no log de execução com um ID de operação, contagens e o tempo gasto, nunca com o conteúdo das notas. Essas linhas usam o evento knowledge; quando VLX_LOG_DIR não está definida, VLX_KNOWLEDGE_LOG_DIR define o diretório delas. O histórico de importações é armazenado no banco de dados e exibido na página "Histórico de importações". Para fazer um backup completo de uma base de conhecimento, guarde tanto a pasta dela quanto os dados do aplicativo, que contêm os registros da lixeira e das importações.