kx indexa documentação, código, configuração e notas num SQLite local e serve busca híbrida — semântica + BM25, fundidas por RRF, com impulso de recência e deduplicação. Sem cloud, sem API key, sem telemetria.
$ kx search "circuit-open" --top 4 [0.0399] .vault/decisions/2026-08-resiliencia.md [vault|ambas] Decisão: abrir o circuito após 5 falhas em 30s… --- [0.0382] docs/runbooks/circuit-open.md [docs|ambas] Quando o alerta circuit-open disparar, verifique… --- [0.0322] docs/resiliencia/visao-geral.md [docs|ambas] Retry, timeout e circuit breaker trabalham juntos… --- [0.0210] src/resilience/CircuitBreakerConfig.ts [code|lexical] export const STATE_OPEN = 'circuit-open'; 4 resultado(s) encontrado(s).
01 · O problema
Antes de escrever uma linha, o agente precisa saber como o projeto decide, nomeia e resolve as coisas. As saídas de sempre falham de jeitos previsíveis.
Busca textual devolve a linha exata, mas não sabe que “disjuntor”, “retry com backoff” e “circuit breaker” falam da mesma decisão espalhada em cinco arquivos.
→ várias listagens e leituras integrais até montar o quadroDespejar a documentação no arquivo de contexto cobra tokens em toda sessão. A Anthropic recomenda CLAUDE.md com menos de 200 linhas.
→ contexto extenso aumenta o consumo de reasoning tokens em até 20%Embeddings acham o conceito, mas tropeçam no que um dev mais procura: nomes de configuração, mensagens de erro, símbolos exatos.
→ em índice real de 75 mil chunks,circuit-open estava em 20 chunks e fora até do top-50 vetorial
02 · A resposta
O kx roda a via vetorial (sqlite-vec) e a via lexical (FTS5/BM25) sobre o mesmo índice e funde as duas por posição, com Reciprocal Rank Fusion. O conceito vem do vetor. O identificador exato vem do BM25. O agente recebe os dois.
Tudo roda na sua máquina: o modelo de embedding (all-MiniLM-L6-v2, ~23 MB) é baixado uma vez e depois o kx funciona 100% offline.
Números do README do projeto, medidos num corpus sintético de stress com o pipeline real. Variam com Node.js, sistema operacional e tamanho do índice.
03 · Anatomia de uma busca
Role e acompanhe o que acontece entre a pergunta do agente e os chunks que ele recebe. As fórmulas são as do kx; o projeto e os arquivos são fictícios.
A consulta vira duas coisas ao mesmo tempo: um embedding de 384 dimensões e uma expressão MATCH com cada termo entre aspas.
score = 1/(60 + rankvet) + 1/(60 + rankbm25)
RRF funde por posição, não por valor: distância de cosseno e BM25 têm escalas incomensuráveis. A recência é multiplicativa e limitada — desempata a favor do recente, mas nunca promove um resultado irrelevante só por ser novo.
Pesos por fonte no .kx.json · recência desligável por projeto
04 · Como funciona
Um binário compartilhado, uma base SQLite por projeto. O MCP server lê e escreve; o CLI só lê. WAL mode permite os dois ao mesmo tempo.
Markdown, TS/Java/SQL, YAML/JSON e notas do .vault/.
chokidar · reindex <10s
Nenhum chunk passa do orçamento seguro do modelo.
EMBED_SAFE_TOKENS = 440
Transformers.js in-process, sem servidor externo.
MiniLM-L6-v2 · 384d · FTS5
Fácil de copiar, mover e apagar. Nada compartilhado entre projetos.
~/.kx/data/{projeto}.sqlite
Tool nativa no agente; terminal para você, sem chamar LLM.
kx mcp · kx search
Claude Code, Codex, Cursor ou qualquer cliente MCP.
search → chunks relevantes
05 · Garantias
Cada projeto aponta para o próprio .sqlite pela .kx.json. Uma denylist global impede que paths sensíveis entrem no índice.
indexing.deny: [".vault/private/**", "**/.env*"]
Depois do download único do modelo, nada sai da máquina. Sem cloud, sem API key, sem telemetria.
embeddings in-process · ~23 MB
O Chokidar detecta o arquivo salvo e reindexa só o que mudou. No macOS, sobe sozinho via launchd.
kx watch · incremental <10s
Notas pessoais, reuniões e decisões ficam no .vault/ do projeto e entram na busca. Repo Git é da equipe; o vault é seu.
--type vault
Com mcp.projectId, toda tool exige UUID e raiz do projeto. Divergência falha antes de abrir o SQLite.
KX_PROJECT_MISMATCH
Páginas publicadas pelo agente são registradas no vault e vinculadas à atividade em que o trabalho aconteceu.
.vault/ARTEFATOS.md
06 · Tools MCP
O que o agente vê quando o kx está ativo. A busca é o centro; atividades e artefatos dão memória de trabalho ao projeto.
O índice e a busca híbrida.
searchBusca híbrida em docs, código, config e vault. Filtros por tipo e top-K.ingestIndexa um arquivo ou diretório específico.reindexReindexação completa ou incremental.statusDocumentos, chunks e distribuição por tipo.Atividades em Markdown no vault.
megabrain_addCria uma atividade e sincroniza o índice de atividades.megabrain_updateRegistra avanço, bloqueio ou conclusão no log.megabrain_statusPainel das últimas atividades e onde cada uma parou.megabrain_getConteúdo completo de uma atividade.Links vinculados ao trabalho que os gerou.
megabrain_artifact_addRegistra ou versiona um artefato publicado.megabrain_artifactsLista links, versão atual e atividade de origem.megabrain_artifact_linkVincula um artefato já registrado a uma atividade.Com mcp.projectId configurado, todas exigem expected_project_id e expected_project_root.
07 · Configuração
config.toml no Codex) registra o kx com raiz explícita.Instalação e requisitos (Node.js 22+) no README do repositório.
{
"mcpServers": {
"kx": {
"command": "kx",
"args": ["mcp", "--strict-project-root",
"--project-root", "/caminho/absoluto/do/projeto"]
}
}
}
[mcp_servers.kx] command = "kx" args = ["mcp", "--strict-project-root", "--project-root", "/caminho/absoluto/do/projeto"] cwd = "/caminho/absoluto/do/projeto"
{
"project": "projeto-a",
"index": "~/.kx/data/projeto-a.sqlite",
"mcp": { "projectId": "<uuid-exclusivo-do-projeto>" },
"indexing": {
"deny": [".vault/private/**", "**/.env*", "**/*.key"]
}
}
# busca $ kx search "como a autenticação é validada" $ kx search "SecurityConfig" --type code --top 3 $ kx search "decisão de cache" --type vault --json # índice $ kx index # incremental $ kx index --full # do zero $ kx status $ kx watch
08 · Quando usar
Recuperar alguns chunks relevantes costuma evitar listagens, buscas amplas e leituras integrais. O ganho depende da qualidade do índice e da consulta — e há casos em que outra ferramenta é melhor.
É open source, roda na sua máquina e cresce com quem usa. A estrela ajuda outras pessoas a encontrarem o projeto.