Base de Conhecimento de Sessões

Esta página trata da "Base de conhecimento de sessões", do "Histórico de organização" e das "Sessões arquivadas". O gerenciamento, a edição e a importação de arquivos Markdown locais são descritos em Bases de Conhecimento Locais.

A base de conhecimento de sessões armazena conhecimentos, decisões, restrições e lições aprendidas, organizados em projeto → sessão → entrada. As entradas geradas são armazenadas de forma independente: elas não mudam quando a sessão de origem muda, e você pode editá-las manualmente. A base de conhecimento de sessões pertence ao backend do VelaTerm ao qual você está conectado e é compartilhada entre os projetos e as sessões dele; quando você se conecta a outro servidor, vê a base de conhecimento desse servidor.

Ela é separada da busca no conteúdo das sessões. A busca nas sessões encontra texto nas conversas originais, enquanto a base de conhecimento pesquisa apenas as entradas salvas. O VelaTerm organiza, armazena e exibe as entradas quando você pede; ele não adiciona entradas a novas sessões automaticamente.

Organização de uma sessão

Clique com o botão direito em uma sessão na barra lateral ou na aba dela e escolha "Organizar na base de conhecimento de sessões". A mesma ação está disponível para sessões arquivadas.
Escolha o "Agente": Claude, Codex, Grok Build, OpenCode, Pi ou OMP. O VelaTerm usa o caminho do executável definido em Configurações ▸ Agentes ou procura o programa no PATH. Um agente que não é encontrado aparece como "Não instalado ou configurado" e não pode ser selecionado.
Se quiser, escolha um "Modelo (opcional)" e um "Esforço de raciocínio". "Modelo padrão" e "Padrão do agente" deixam a escolha para a configuração do próprio agente. A lista de modelos é a mesma usada na criação de uma sessão, e os níveis de esforço só aparecem para os modelos que os oferecem. O VelaTerm lembra o último agente, modelo e esforço que você usou. O agente precisa estar com o login feito e ter acesso ao modelo escolhido.
Clique em "Organizar e salvar". O agente selecionado recebe o texto da sessão e o processa com a própria configuração de modelo.
Acompanhe a tarefa em "Histórico de organização". Fechar a caixa de diálogo não interrompe a tarefa.

O VelaTerm lê o registro da conversa do agente quando ele está disponível. Caso contrário, usa a gravação do terminal da sessão (consulte Uso do Terminal), sem os códigos de controle do terminal. Quando nenhum dos dois pode ser lido, aparece a mensagem "Esta sessão não tem uma conversa disponível para leitura." Uma gravação do terminal contém o texto visível na tela e pode incluir conteúdo redesenhado; por isso, o agente que organiza o conhecimento não deve tratar essa saída como fato verificado.

Um instantâneo de origem armazena o texto lido para a organização. Os nomes do projeto e da sessão são salvos quando a sessão é adicionada pela primeira vez e não são atualizados quando o projeto ou a sessão é depois renomeado, movido, arquivado ou excluído em outro lugar.

Organizar uma sessão novamente faz com que ela seja lida de novo e substitui as entradas geradas antes a partir dela, incluindo suas edições manuais; isso acontece mesmo que o texto e as configurações do modelo não tenham mudado. Se a sessão já tiver uma tarefa não concluída, a nova tarefa a substitui. Quando a tarefa antiga já está em execução, a nova começa automaticamente depois que o processo antigo para ("Esta tarefa começará automaticamente quando a anterior desta sessão tiver parado."); a tarefa antiga continua no histórico.

Como a organização funciona

A organização tem três etapas, exibidas como o progresso da tarefa:

Extraindo temas: a sessão é lida em partes, e o conhecimento reutilizável é extraído. Os temas são mesclados apenas dentro desta tarefa; as entradas de outras sessões e as edições manuais anteriores não são usadas.
Integrando conhecimentos: as contribuições de cada tema são combinadas, preservando conhecimentos, restrições e incertezas. O agente é instruído a levar em conta correções e contradições posteriores e a não inventar conclusões.
Salvando artigos: o VelaTerm verifica os campos, as fontes, os links e as versões e substitui as entradas geradas da sessão em uma única transação do banco de dados. Uma entrada com o mesmo título mantém a identidade e recebe uma nova revisão. As entradas que não são mais geradas são excluídas junto com o histórico de revisões, e os links que apontam para elas são removidos. Quando a organização é concluída sem encontrar nada reutilizável, as entradas geradas antes para a sessão são removidas ("Nenhum conhecimento reutilizável foi extraído. As entradas geradas anteriormente para esta sessão foram removidas."). Uma verificação com falha, um cancelamento ou um conflito de versões mantém as entradas anteriores inalteradas, e nenhum resultado parcial é salvo.

O agente retorna conteúdo estruturado, e o VelaTerm faz todas as alterações no banco de dados. As entradas têm links entre si, e as listas "Links para este artigo" são calculadas automaticamente. Os instantâneos de origem e o histórico de revisões continuam disponíveis mesmo que a sessão original seja excluída.

A qualidade do conhecimento organizado ainda depende da sua avaliação. Se algo estiver errado, edite a entrada ou restaure uma revisão anterior; a restauração cria uma nova revisão e mantém a versão substituída.

Histórico de organização

"Histórico de organização" lista as tarefas de organização, 40 por página. Cada tarefa mostra o agente, o modelo ("Modelo padrão" quando nenhum foi escolhido), o esforço de raciocínio e o horário; uma tarefa em execução também mostra a etapa atual ("Extraindo temas", "Integrando conhecimentos" ou "Salvando artigos"). O status de uma tarefa é "Aguardando início", "Em andamento", "Cancelando", "Concluído", "Falha" ou "Cancelado", e o "Instantâneo de origem" e as entradas resultantes podem ser abertos a partir da lista.

"Cancelar" interrompe uma tarefa que está aguardando ou em execução. Uma tarefa em execução mostra "Cancelando" até que o processo do agente pare. O cancelamento não exclui o instantâneo de origem.
"Tentar novamente" reinicia uma tarefa com falha ou cancelada usando o mesmo instantâneo de origem, modelo e esforço de raciocínio. O histórico mostra as configurações com que a tarefa foi criada; uma escolha padrão significa que o agente decidiu, e não que o VelaTerm definiu um modelo específico.

Sessões diferentes podem ser organizadas em paralelo. Cada sessão executa uma tarefa por vez, e enviá-la novamente mantém apenas a tarefa em espera mais recente, em vez de formar uma fila. As tarefas em espera são salvas no banco de dados e continuam depois que o aplicativo é reiniciado. Uma tarefa em execução que não informa progresso por dois minutos é marcada como interrompida ("O processamento foi interrompido. Tente novamente com o instantâneo de origem salvo."). O tempo de espera não conta para o tempo limite da tarefa.

Você pode editar entradas enquanto a organização está em andamento. Se alguém editar ou excluir as entradas geradas da sessão durante uma tarefa, a tarefa informa um conflito de versões, suas alterações são mantidas e você pode tentar novamente depois. Sessões diferentes podem usar o mesmo título de entrada; dentro de uma mesma sessão, os títulos precisam ser únicos.

Navegação e manutenção das entradas

Abra a base de conhecimento pelo painel direito (consulte Bases de Conhecimento Locais) e expanda "Base de conhecimento de sessões" por projeto, sessão e entrada. Clique em um projeto ou em uma sessão para listar as entradas e clique em uma entrada para lê-la. O botão "Subir um nível" volta à página superior.

A página de lista oferece busca ("Pesquisar títulos e conteúdo…"), filtro por etiqueta ("Todas as etiquetas"), ordenação por "Atualização recente" ou "Título" e atualização. A busca abrange títulos, resumos, corpo do texto e etiquetas, aceita várias palavras (todas precisam corresponder) e coloca primeiro as correspondências no título; cada resultado também lista as entradas diretamente relacionadas. Quando não há correspondências exatas, são exibidas correspondências aproximadas, como na busca das bases de conhecimento locais.
As entradas de uma sessão são exibidas 40 por página; as listas de projetos e de sessões não são cortadas por esse limite, e as listas longas na árvore oferecem "Carregar mais".
A página de uma entrada mostra o corpo em Markdown, "Artigos relacionados", "Links para este artigo", "Fontes" e "Histórico de revisões". Você pode editar o corpo ali mesmo e salvar com ⌘S / Ctrl+S, usar "Editar" para alterar o título, o resumo e as etiquetas, ou escolher "Exportar Markdown", "Copiar para um caderno local" ou "Excluir". Excluir uma entrada também exclui o histórico de revisões dela, mas mantém a sessão de origem e os instantâneos.
"Novo artigo" cria uma entrada manualmente; essas entradas aparecem no grupo "Criação manual".

A árvore também oferece ações de gerenciamento:

Clique com o botão direito em uma entrada para renomeá-la ou excluí-la; arraste-a para outra sessão para reatribuí-la.
Clique com o botão direito no grupo de um projeto ou de uma sessão para renomeá-lo ou excluir as entradas dele. Renomear um grupo também renomeia o projeto ou a sessão real. Excluir um grupo remove apenas as entradas de conhecimento dele: "Excluir todos os N artigos de conhecimento deste grupo? O projeto ou a sessão em si serão mantidos."
Arrastar uma sessão para outro projeto move a sessão real para esse projeto.
Os grupos "Criação manual", "Entradas mescladas anteriormente" e "Projeto de origem desconhecido" não podem ser renomeados.

As páginas de entradas, os formulários de edição, os instantâneos de origem, as revisões, a caixa de diálogo de organização e o histórico de organização têm URLs próprias, e o projeto, a sessão, a busca, o filtro, a ordenação e a página selecionados fazem parte da URL.

Sessões arquivadas

As sessões arquivadas são gerenciadas na base de conhecimento. "Sessões arquivadas" aparece na árvore da base de conhecimento ao lado da "Base de conhecimento de sessões" e agrupa as sessões arquivadas pelo projeto de origem; o botão "Sessões arquivadas", no cabeçalho da barra lateral, abre o mesmo local.

A área principal lista todas as sessões arquivadas por projeto. Uma sessão aberta tem duas abas: "Conversa" mostra a conversa completa, e "Artigos de conhecimento" mostra as entradas geradas a partir dela.
"Buscar conteúdo arquivado…" pesquisa o texto completo apenas das sessões arquivadas e agrupa as correspondências por sessão.
Uma sessão arquivada aberta oferece "Restaurar como sessão normal", "Organizar na base de conhecimento de sessões", "Exportar contexto completo como Markdown" (para sessões do Claude e do Codex) e "Excluir permanentemente (com a gravação)". A exclusão permanente tem efeito imediato, sem etapa de confirmação.
Arquivar, restaurar e excluir uma sessão não altera as entradas de conhecimento existentes, porque as entradas e os instantâneos de origem são armazenados separadamente. Uma sessão restaurada pode continuar a conversa.

Dados de versões anteriores

Quando o VelaTerm atualizou dados mais antigos, as entradas com uma única sessão de origem foram atribuídas a essa sessão. As entradas que já combinavam várias sessões foram mantidas intactas no grupo "Entradas mescladas anteriormente"; elas não são divididas e nunca são substituídas quando uma dessas sessões é organizada novamente. As entradas sem origem foram para "Criação manual". As informações de projeto que ainda existiam foram preenchidas uma única vez durante a atualização; as fontes cujo projeto não pôde ser determinado aparecem em "Projeto de origem desconhecido", com os nomes originais das sessões e os instantâneos.

Dados e limites

A base de conhecimento de sessões é armazenada no banco de dados SQLite do aplicativo (tabelas memory_*), separada do índice de busca das sessões. A interface guarda apenas o que exibe e o conteúdo não salvo dos formulários; a validação, as verificações de versão, a detecção de duplicatas e todas as gravações acontecem no backend.

Uma fonte pode conter até 2.000.000 de caracteres; cada parte da extração, até 24.000 caracteres; cada texto enviado ao modelo, até 350.000 caracteres; e o corpo de cada entrada, até 200.000 caracteres.
Cada chamada ao agente pode durar até 10 minutos, e cada um dos fluxos de saída dela pode produzir até 8 MiB.
No OpenCode, no Pi e no OMP, o texto passado em uma chamada é limitado a 128 KiB.
Se um agente retornar uma saída que não corresponde à estrutura esperada, o VelaTerm pede de novo, até três vezes.

Tudo o que ultrapassa esses limites falha com uma mensagem clara ("A fonte, o contexto ou a saída excede o tamanho compatível. Nenhum conteúdo foi truncado ou salvo."); nada é truncado e salvo.

A organização é registrada em logs/runtime-*.log, no diretório de dados do aplicativo. Quando VLX_LOG_DIR não está definida, VLX_MEMORY_LOG_DIR define o diretório. VLX_MEMORY_LOG_LEVEL=error registra apenas erros, e off desativa o log deste módulo. O log registra tarefas e etapas, quantidades de itens de entrada e de saída, durações, contagens de caracteres, hashes SHA-256 e números de uso de tokens. Ele nunca registra prompts completos, texto de origem, respostas do modelo, credenciais nem saída de erro; os instantâneos de origem guardam o material original.

Vínculos com o grafo de código

As entradas de conhecimento podem ser vinculadas a símbolos do código, e "Referências ao código", na página de uma entrada, leva ao grafo de código. Quando o arquivo vinculado muda, a entrada indica que precisa de revisão; confirmar a revisão não altera o texto da entrada. Os agentes em uma sessão podem consultar o código e as entradas com vkb. Consulte Grafo de Código e Base de Conhecimento.