Sverklo: Verificando a Cadeia de Evidências de Código-Memória

Muitos agentes de codificação não falham porque um modelo esqueceu uma frase da conversa anterior. Eles falham porque o agente não possui uma camada de contexto que possa explicar de onde veio um fato de código, quão amplo ele se aplica e se ainda está atualizado. Sverklo é interessante como uma hipótese de engenharia: um servidor MCP local-first que combina indexação de repositórios, gráficos de símbolos, rastreamento de dependências, revisão ciente de diffs e memória persistente. A pergunta útil não é se soa como uma caixa de pesquisa inteligente. É se um agente pode receber o contexto do repositório que um humano pode reproduzir e verificar.

O ponto de entrada upstream é npm install -g sverklo, com Node.js >= 24 como o tempo de execução declarado. Uma instalação bem-sucedida apenas prova que o CLI pode ser encontrado. Não prova que o índice está completo, que o repositório atual está sendo servido ou que o cliente MCP está chamando a ferramenta pretendida. Eu começaria em um repositório de teste descartável em vez de vincular a primeira execução a um espaço de trabalho de produção ou ao registro global.

Eu tornaria a primeira execução de aceitação observável em quatro camadas. Primeiro, descoberta de arquivos: o índice inclui os caminhos esperados, respeita as regras de ignorar e produz uma contagem de arquivos plausível após a reindexação? Segundo, estrutura de código: lookup pode encontrar um símbolo conhecido, e refs, deps e impact retornam relacionamentos em vez de uma lista de nomes de arquivos? Terceiro, entrega de contexto: a ferramenta context fornece um pacote de integração útil, e um token fornecido budget produz um mapa de repositório menor podado por PageRank? Quarto, o livro-razão da memória: uma memória com um escopo de projeto, tipo, arquivo relacionado e metadados de tempo pode ser recuperada, e mudar esse arquivo torna a memória visivelmente obsoleta?

Sverklo não é descrito como um único recuperador de vetor. O manual do Doramagic mapeia sua superfície de recuperação para palavras-chave BM25, embeddings ONNX e um gráfico de símbolos PageRank fundido através de sinais. As correspondências de pesquisa expõem found_by, que dá ao operador uma maneira de dizer se vários recuperadores concordam. Há um limite importante aqui: strings exatas ainda pertencem ao Grep/Read. Sverklo é mais adequado para exploração, gráficos de dependência, raio de explosão de refatoração e perguntas semânticas. Enviar cada consulta através de embeddings tornaria o fluxo de trabalho menos previsível e contradiziria a própria orientação MCP do servidor.

Um script de aceitação pode permanecer pequeno e repetível:

1. Criar um repositório temporário com alguns módulos, um teste, um README e uma dependência intencionalmente quebrada.
2. Executar sverklo init, registrar o projeto e aguardar a indexação. Registrar a versão do Node, nome do projeto, timestamp do índice e contagem de arquivos.
3. Chamar context para integração e passar um pequeno budget; verificar se o mapa retornado realmente contrai com o orçamento.
4. Usar lookup em um símbolo conhecido, depois usar refs, deps e impact para rastrear chamadores, dependências e escopo de mudança.
5. Escrever uma decisão fixada em um arquivo com remember, editar esse arquivo e inspecionar sverklo://context ou recuperar um sinal explícito de obsolescência.
6. Executar review_diff em uma pequena mudança e confirmar que o resultado contém tanto Markdown legível quanto descobertas estruturadas com âncoras de caminho, linha e severidade.

O ciclo de vida é onde uma configuração aparentemente saudável pode enganar uma automação. Sverklo armazena projetos registrados em ~/.sverklo/registry.json. O manual registra a questão #74: reindex pode terminar enquanto deixa lastIndexed obsoleto, então o timestamp em sverklo list é consultivo em vez de prova de que o índice atual está fresco. Após a reindexação, a automação deve registrar novamente ou ler o status do índice e evidências de arquivos diretamente. A questão #73 relata que o cancelamento de registro leva o nome do projeto interno, não um caminho absoluto. Um script de limpeza de worktree deve, portanto, resolver o nome a partir de sverklo list antes de cancelar o registro.

A nomenclatura MCP tem outro limite silencioso de produção. Sverklo já expõe prefixos de ferramentas internas sverklo_. Se um host também prefixar nomes de ferramentas usando a chave do servidor, um nome como sverklo_sverklo_impact pode aparecer. Um distintivo conectado não é suficiente. Após a integração, enumere as ferramentas e faça uma chamada real para context, lookup ou status para que os nomes e a forma de resposta do host sejam verificados.

Minha regra de operador é tratar Sverklo como um candidato de contexto de código local observável, não como um cérebro de agente que se torna confiável após a instalação. Antes de colocá-lo em um espaço de trabalho real, mantenha quatro tipos de retorno: escopo e frescor do índice, resultados de símbolo/dependência, comportamento de memória obsoleta e saída de revisão de diffs estruturada. Sem esses artefatos, a única afirmação defensável é que o CLI começou.

Este é um pacote de capacidade independente do Doramagic, não um lançamento ou endosse oficial do Sverklo. Página do projeto: https://doramagic.ai/en/projects/sverklo/; Manual Humano: https://doramagic.ai/en/projects/sverklo/manual/; upstream: https://github.com/sverklo/sverklo.