Skip to main content
Glama

Kaxcav Vortex (kvx v3.1.0-apex)

Version Node Dependencies MCP License: MIT

Motor poliglota de inteligência de código, empacotamento submodular de contexto (L0–L3), matriz de grafo esparsa CSR em memória e federação multi-repositório. Projetado para operações pesadas de engenharia de software com múltiplos agentes de IA simultâneos.


1. O Problema que o Kaxcav Vortex Resolve

Indexadores tradicionais e motores de RAG monolíticos colapsam sob carga pesada de múltiplos agentes de IA porque:

  1. Usam um banco SQLite monolítico global cujo WAL cresce para dezenas de gigabytes (23+ GB) quando vários repositórios sofrem mutações simultâneas;

  2. Tentam parsear PDFs, binários ou dumps SQL na heap principal (causando VirtualAlloc OOM de 14+ GB);

  3. Dependem de .git para ignorar diretórios vendorizados, engolindo 170.000+ arquivos em workspaces desacoplados;

  4. Usam PageRank estático que vicia em arquivos-índice (README.md, INDEX.md) em vez do código-alvo;

  5. Reenviam arquivos inteiros a cada turno da IA, desperdiçando 70% a 90% da janela de tokens.

Benchmarks Reais (Indexadores Monolíticos vs. Kaxcav Vortex v2.0.0-apex)

Métrica Operacional

Indexador RAG Monolítico

Kaxcav Vortex (kvx v2.0.0-apex)

Ganho Real

Memória RAM (3 Repos Simultâneos)

14.36 GB (VirtualAlloc OOM)

12.25 MB Heap (87.66 MB RSS)

-99.1% RAM

Tamanho de Disco SQLite WAL

23.34 GB (store.sqlite-wal global)

< 4 MB por shard (Hard Cap 32 MB)

-99.9% Disco

Admissão em Repo sem .git

174.662 arquivos (travamento de I/O)

107 arquivos reais indexados em 553 ms

Zero Lixo Indexado

Latência de Contexto (context)

2.718 ms (média)

1.89 ms a 14.44 ms (4.12 ms ETag Hit)

~500x mais rápido

Precisão Top-1 (Benchmark Real)

25.0% (1/4 — viciado em INDEX.md)

100.0% (4/4 Top-1 e 4/4 Hit@3)

4x mais preciso

Economia de Tokens por Chamada

0 (envia arquivos inteiros)

10.926 a 16.597 tokens poupados/query

~82% a 88% economia


Related MCP server: OpenCodeHub MCP Server

2. Arquitetura em 7 Camadas

flowchart LR
    A["Worktree / Multi-Repo"] --> B["1. AdmissionFirewall (4KB Magic-Byte Sniffer)"]
    B --> C["2. CodeStateMachine + PolyglotExtractor (CAS SHA-256)"]
    C --> D["3. Sharded SQLite + FTS5 BM25F (32MB WAL Cap)"]
    C --> E["4. TypedArray CSR Graph + PPR-HD (Hub Dampening)"]
    D --> F["5. Submodular L0-L3 Slicer + Persistent ETag Delta"]
    E --> F
    F --> G["6. MultiRepoFederator + Contract Drift Detector"]
    G --> H["7. CLI / MCP Server (10 Tools) / Web Workbench :7788"]

Subsistema Core

Engenharia Aplicada

AdmissionFirewall (src/core/firewall.ts)

Inspeciona os primeiros 4.096 bytes de cada arquivo candidato e bloqueia na largada PDFs (%PDF-), ZIP/Office (PK\x03\x04), binários PE/ELF (MZ), SQLite, bytes nulos (0x00) e bundles minificados (> 1.400 chars/linha). Independe da existência de .git.

CodeStateMachine & PolyglotExtractor (src/parser/)

Scanner léxico de estados (Code, LineComment, BlockComment, SingleQuote, DoubleQuote, TemplateQuote) imune a chaves {} dentro de strings/comentários, com suporte a tipos de retorno inline e assinaturas multi-linha em TypeScript/JS, Go, Python, Prisma/SQL e Markdown.

Camada tree-sitter opcional (src/parser/treesitter.ts)

Com o pacote opcional @vscode/tree-sitter-wasm (WASM, sem binário nativo nem node-gyp), Python e Go passam a ser lidos pela árvore sintática e entram Java, C#, C/C++, Rust, Ruby, PHP, Bash e PowerShell, com membros qualificados (Classe.metodo), visibilidade, docs e imports de módulo (com.acme.Invoice, crate::db, App\Models) resolvidos para arquivos. Sem o pacote, ou com KVX_TREE_SITTER=0, o motor segue com os extratores próprios; index_health/kvx status --json dizem qual camada está ativa e por quê. TS/JS continuam no scanner próprio.

RepositoryShard (src/storage/shard.ts)

1 banco SQLite nativo (node:sqlite) isolado por repositório com trava física de WAL em 32 MB (PRAGMA journal_size_limit = 33554432), FTS5 (BM25F) e cache Content-Addressable (cas_extractions) por hash SHA-256.

CsrGraph + PPR-HD (src/graph/csr.ts)

Grafo Compressed Sparse Row (CSR) em Uint32Array e Float32Array com Personalized PageRank + Hub Dampening, executando em < 2 ms sem alocações na heap.

SubmodularPacker (src/packer/packer.ts)

Fatiamento cirúrgico em 4 níveis de fidelidade (L3_FOCAL corpo completo, L2_CONTRACT assinatura tipada, L1_SKELETON esqueleto e L0_DELTA deduplicação persistente cross-process por ETag).

MultiRepoFederator (src/federation/federator.ts)

Conecta rotas HTTP (expose <-> consume), símbolos exportados e modelos Prisma/SQL entre múltiplos repositórios simultâneos.


3. Instalação Zero-Dependency (30 Segundos)

  • Requisitos: Node.js >= 22.13.0 (recomendado Node.js 24+, usa node:sqlite e --experimental-strip-types nativos do Node). O núcleo não precisa de npm install; rodar npm install só acrescenta a camada tree-sitter opcional (mais 10 linguagens).

  • Sistemas Operacionais: Windows (kvx.cmd), Linux, macOS e WSL (./kvx ou npm link).

git clone https://github.com/Kaxcav/kaxcav-vortex.git
cd kaxcav-vortex
npm link

# Validar suíte de testes completa (~1s)
npm test

4. Guia Rápido de CLI (kvx)

# 1. Inicializar e registrar um repositório no Kaxcav Vortex
kvx init C:\caminho\do\meu-repo

# 2. Gerenciar múltiplos repositórios federados
kvx repo add C:\caminho\repo-backend
kvx repo add C:\caminho\repo-frontend
kvx repo list

# 3. Gerar pacote de contexto cirúrgico com orçamento de tokens (L0-L3)
kvx context --index C:\caminho\repo-backend --task "Fluxo de autenticacao JWT e permissoes" --token-budget 1800 --fidelity graded

# 4. Reutilizar ETag do turno anterior para colapsar símbolos inalterados em L0_DELTA
kvx context --index C:\caminho\repo-backend --task "Fluxo de autenticacao JWT e permissoes" --delta-from kvx-a1b2c3d4e5f60718

# 5. Inspecionar o esqueleto estrutural (L1 Outline) de um arquivo gastando ~40 tokens
kvx outline --index C:\caminho\repo-backend src/services/auth.ts

# 6. Ler apenas o código de uma função/classe específica sem carregar o arquivo inteiro
kvx symbol --index C:\caminho\repo-backend AuthService

# 7. Calcular Raio de Explosão (Blast Radius) e suítes de teste afetadas antes de commitar
kvx blast-radius --index C:\caminho\repo-backend AuthService
kvx affected --index C:\caminho\repo-backend -- src/services/auth.ts

# 8. Detectar quebras de assinatura (Contract Drift) nos arquivos recém-editados
kvx diff-impact --index C:\caminho\repo-backend --minutes 60

# 9. Descobrir contratos e rotas conectadas entre múltiplos repositórios
kvx federate --repos "C:\caminho\repo-backend,C:\caminho\repo-frontend"

5. Web Workbench UI (kvx dashboard)

Suba a estação visual de engenharia para inspecionar os shards, testar o empacotador L0–L3, navegar pelo grafo CSR interativo em Canvas e auditar Contract Drifts:

kvx dashboard --port 7788

Abra http://127.0.0.1:7788 no navegador. Você pode adicionar novos repositórios diretamente pelo campo + Repo na barra superior.


6. Integração MCP (Claude Code, Kimi Code, Cursor, Windsurf, Antigravity)

Adicione no seu mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "kaxcav-vortex": {
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "--no-warnings",
        "/caminho/para/kaxcav-vortex/src/cli/main.ts",
        "serve",
        "--mcp"
      ]
    }
  }
}

Para agentes que só devem ler código (por exemplo, o agy sem interface), registre também o servidor só de leitura:

"kaxcav-vortex-ro": {
  "command": "node",
  "args": ["--experimental-strip-types", "--no-warnings", "/caminho/para/kaxcav-vortex/src/cli/main.ts", "serve", "--mcp", "--read-only"]
}

No agy, agy mcp add kaxcav-vortex-ro -- node --experimental-strip-types --no-warnings <main.ts> serve --mcp --read-only e uma regra só em ~/.gemini/antigravity-cli/settings.json: mcp(kaxcav-vortex-ro/*) (verificado em 08/11/2026). Nenhuma nexus_* fica exposta.

Ferramentas MCP (13; 10 no servidor só de leitura)

  1. context: pacote de contexto ranqueado por PPR-HD + BM25F com fatiamento L0–L3 e suporte a if_none_match / delta_from.

  2. file_outline: esqueleto do arquivo com o intervalo real de cada símbolo; escopo = topo (padrão: módulo + membros de classe), exportado ou tudo. Caminho absoluto ou relativo; se o arquivo não estiver indexado, diz por quê e sugere parecidos.

  3. read_symbol: só o trecho do símbolo; aceita nome, Classe.metodo, caminho#nome e path. Sem resultado, devolve o motivo, nomes parecidos e ocorrências via busca textual.

  4. call_graph: chamadores diretos (callers) e funções chamadas (callees).

  5. diff_impact: Contract Drift de símbolos exportados (sem locais e sem testes) alterados na janela.

  6. blast_radius: impacto direto, transitivo, testes afetados e impactos cruzados entre repositórios.

  7. affected: seleção determinística de testes impactados por arquivos alterados.

  8. search / search_symbols: busca híbrida; responde com via (indice / busca_textual / nenhum) e o motivo quando não acha.

  9. index_health: shards, WAL, idade do índice por arquivo (file para um arquivo só) e tokens economizados.

  10. nexus_ingest_vault, nexus_query_sheet, nexus_audit_dlp (só no servidor completo).

.kvxignore

Caminhos que nenhuma ferramenta pode indexar nem ler, inclusive as nexus_*: um .kvxignore na raiz do repo (sintaxe do .gitignore) e um global em ~/.kvx/kvxignore (aceita caminhos absolutos). A recusa cita o arquivo, a linha e a regra.


Licença

Distribuído sob a licença MIT.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search code by meaning, explore codebase structure, store and query knowledge with temporal facts, and read source code through a set of MCP tools.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides code intelligence for AI coding agents by indexing repositories into a hybrid knowledge graph, enabling agents to query dependencies, impact, and context through 28 MCP tools.
      4
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to perform hybrid semantic and lexical code search across multiple repositories, retrieve symbol definitions and call hierarchies, and manage repository relations through MCP tools.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to query code structure efficiently through 16 MCP tools, including symbol lookup, full-text search, dependency analysis, and refactor planning, powered by tree-sitter parsing and index-backed code intelligence.
      3
      MIT