vault-vector

Busca semântica e escrita nas suas notas markdown, expostas ao Claude como MCP server. Roda inteiro na sua máquina: os embeddings saem do Ollama e o índice é um arquivo SQLite local. Funciona com o Obsidian fechado.

vault-vector init

Se você já tem notas, o init encontra seus vaults do Obsidian, checa o Ollama, escreve a configuração, indexa e mostra como conectar ao Claude Code e ao Claude Desktop.

Se você ainda não tem nenhuma, ele cria o vault com a estrutura que a busca sabe aproveitar: pasta de diário com data no nome, MOC por seção, títulos como fronteira de trecho. O que sai disso é uma pasta de markdown comum, que você pode abrir no Obsidian depois ou deixar só para o Claude escrever e consultar.

O que faz

Busca híbrida. Similaridade vetorial e busca literal (FTS5) fundidas por Reciprocal Rank Fusion. Funciona tanto para pergunta conceitual ("como decidi o particionamento das VLANs") quanto para identificador exato (hostname, IP, código de erro), já que os dois lados cobrem falhas diferentes um do outro.

Escrita com histórico. Sete ferramentas MCP: editar trecho, acrescentar, criar nota, mover, apagar, listar, reindexar. Toda gravação copia a versão anterior para _historico/ antes de escrever, e mover uma nota reescreve os wikilinks que apontavam para ela.

Descrição automática do vault. O servidor lê o próprio índice e monta para o modelo a descrição da estrutura: seções, subpastas, convenções de diário e de índice. Como nada disso fica embutido no código, o modelo consegue navegar um vault que nunca viu sem que você precise escrever instruções para ele.

Sinalização de incerteza. Foi a parte que levou mais trabalho e está explicada na seção seguinte.

Uso sem vault prévio. Não pressupõe que você já tenha notas nem que use Obsidian. Para quem quer apenas uma memória persistente onde o Claude escreve e consulta, o init monta isso em um comando.

Related MCP server: mcp-apple-notes

Quando o vault não tem a resposta

Um sistema de busca por similaridade sempre devolve os top_k trechos mais parecidos. Quando a pergunta não tem resposta no corpus, ele devolve os menos distantes com a mesma aparência de acerto, e o modelo de linguagem que lê esses trechos responde a partir deles.

O caso que expôs isso aqui foi uma pergunta de culinária contra um vault de infraestrutura e desenvolvimento: ela tirou o maior score da sessão, acima de perguntas cuja resposta estava no vault. Uma palavra da pergunta tinha homônimo no corpus, e os dois rankers concordaram com força. O score do RRF mede concordância entre rankers, e concordância não separa o caso em que os dois acertaram do caso em que os dois erraram junto.

Piso de similaridade não resolveu

A primeira correção foi cortar resultados abaixo de um limiar de cosseno. Medindo as duas populações:

As duas se sobrepõem em quase toda a extensão, então qualquer corte único ou deixa passar ruído ou recusa pergunta boa. Com o piso em 0,55, três de cinco perguntas legítimas verificáveis foram recusadas, uma delas com a nota correta em primeiro lugar.

Faixas de confiança

O resultado sai sempre, classificado em três faixas, com a incerteza anexada a ele:

Medido em 8 perguntas legítimas com vocabulário trocado contra 8 perguntas fora do domínio:

As duas pontas ficam limpas: nenhuma resposta correta desencorajada e nenhum ruído entregue sem ressalva. A faixa média concentra 69% dos casos com acerto perto de 50%, o que dá a medida de quanta informação a similaridade de vetor não carrega e justifica em número a etapa seguinte, um reranker cross-encoder que lê pergunta e trecho juntos.

Os números acima são do vault onde o projeto nasceu e mudam com o idioma, o assunto e o tamanho do corpus. Dois comandos refazem a medição no seu:

vault-vector calibrar          # mede as duas populações no seu vault
vault-vector testar-confianca  # matriz de confusão das faixas

Decisões de projeto

Requisitos

• Python 3.11+

• Ollama com um modelo de embedding (ollama pull bge-m3)

• Notas em markdown, ou nenhuma, já que o init cria o vault

Testado no Windows. O código é portátil, mas os scripts de serviço (.ps1) são específicos do Windows.

Comandos

vault-vector init                 instala do zero
vault-vector index                incremental; --force reindexa tudo
vault-vector search "termo"       busca pela linha de comando
vault-vector stats                total, pendências, seções
vault-vector doctor               checa Ollama, índice, busca e escrita
vault-vector calibrar             mede as faixas de confiança no seu vault
vault-vector testar-confianca     matriz de confusão das faixas
vault-vector serve --http         um processo servindo todos os clientes MCP
python selftest.py                ~60 checagens, não precisa do Ollama

Limites conhecidos

• Indexa só .md. PDF, imagem, anexo e .canvas ficam de fora.

• Sem reranking. As faixas cobrem o caso grosseiro. O caso fino, em que a similaridade é alta e o trecho mesmo assim não responde, depende de um cross-encoder, que custa torch ou llama.cpp separado.

• O top_k completa o resultado até o limite pedido, então as últimas posições podem vir com score muito baixo.

• Reindexação em lote pelo MCP pode estourar o tempo limite do cliente. Para lote, use o CLI.

Licença

MIT.