TurboVault

Grafo de conhecimento compatível com Markdown e Obsidian.

Documentação

TurboVault

O SDK definitivo em Rust e o servidor MCP de alta performance para vaults Markdown no formato Obsidian (.ofm) e .md padrão.

TurboVault é um kit de ferramentas de dupla finalidade projetado tanto para desenvolvedores quanto para usuários. Ele fornece um SDK Rust robusto e modular para construir aplicações que consomem diretórios markdown, e um servidor MCP completo que funciona prontamente com Claude e outros agentes de IA.

Duas Formas de Usar o TurboVault

1. Como SDK Rust (Para Desenvolvedores)

Construa suas próprias aplicações, mecanismos de busca ou servidores MCP personalizados usando nossos crates modulares. O TurboVault cuida do trabalho pesado de analisar arquivos .md e .ofm, construir grafos de conhecimento e gerenciar ambientes multi-vault.

Arquitetura Modular: Use apenas o que precisar (Parser, Graph, Search, etc.).
Alta Performance: Operações abaixo de 100ms para a maioria das tarefas.
Extensível: Construa facilmente seus próprios servidores MCP especializados sobre nossa lógica central.
Padrões SOTA: Suporte completo a Markdown no formato Obsidian (wikilinks, embeds, callouts).

2. Como Servidor MCP Pronto para Uso (Para Usuários)

Transforme seu vault do Obsidian em um sistema de conhecimento inteligente imediatamente. Conecte o TurboVault ao Claude Desktop ou a qualquer cliente compatível com MCP para obter 74 ferramentas especializadas para suas notas.

Zero Codificação Necessária: Instale o binário e aponte-o para seu vault.
74 Ferramentas Especializadas: Busca, análise de links, gravações atômicas com Git, consultas SQL em frontmatter, verificações de saúde e muito mais.
Suporte Multi-Vault: Alterne entre notas pessoais e de trabalho perfeitamente em tempo de execução.

Crates Principais (O SDK)

TurboVault é um sistema modular composto por crates especializados. Você pode depender de componentes individuais para construir suas próprias ferramentas:

Crate	Finalidade	Docs
turbovault-core	Modelos principais, gerenciamento MultiVault e tipos
turbovault-parser	Parser de alta velocidade para .md e .ofm
turbovault-graph	Análise de grafo de links e descoberta de relacionamentos
turbovault-vault	Gerenciamento de vault, I/O de arquivos e gravações atômicas
turbovault-tools	74 implementações de ferramentas MCP
turbovault-plugin-api	Fachada estável, contrato de provedor e hooks limitados para plugins compilados
turbovault-sql	Consultas SQL em frontmatter (GlueSQL)
turbovault-batch	Lotes de operações validados com falha rápida
turbovault-export	Exportação e relatórios (JSON/CSV/MD)
turbovault	Binário principal do servidor MCP / orquestrador do SDK

Por que TurboVault?

Diferente de leitores de notas básicos, o TurboVault entende a estrutura de conhecimento do seu vault:

Busca de texto completo em todas as notas com ranqueamento BM25
Análise de grafo de links para descobrir relacionamentos, hubs, órfãos e ciclos
Inteligência de vault com pontuação de saúde e recomendações automatizadas
Lotes de operações validados para menos idas e voltas e execução com falha rápida
Suporte multi-vault com troca de contexto instantânea
Adição de vault em tempo de execução — nenhum vault necessário na inicialização, adicione-os conforme necessário

Desenvolvido com TurboMCP

TurboVault é construído sobre o TurboMCP, um framework Rust para construir servidores MCP de nível de produção. O TurboMCP fornece:

Definições de ferramentas type-safe — Implementação de ferramentas MCP orientada por macros
Tratamento padronizado de requisição/resposta — Formato de envelope consistente
Abstração de transporte — HTTP, WebSocket, TCP, sockets Unix (recursos configuráveis)
Suporte a middleware — Logging, métricas, tratamento de erros
Streaming zero-copy — Tratamento eficiente de payloads grandes

Isso significa que o TurboVault obtém confiabilidade e extensibilidade testadas em batalha prontas para uso. Quer adicionar ferramentas personalizadas? As macros ergonômicas do TurboMCP tornam isso simples.

Início Rápido

Instalação

Do crates.io

# Minimal install (7.0 MB, STDIO only - perfect for Claude Desktop)
cargo install turbovault

# With HTTP server (~8.2 MB)
cargo install turbovault --features http

# With all cross-platform transports (~8.8 MB)
# Includes: STDIO, HTTP, WebSocket, TCP (Unix sockets only on Unix/macOS/Linux)
cargo install turbovault --features full

# With SQL frontmatter queries (adds GlueSQL-powered query_frontmatter_sql tool)
cargo install turbovault --features sql

# Binary installed to: ~/.cargo/bin/turbovault

Do código-fonte:

git clone https://github.com/epistates/turbovault.git
cd turbovault
make release
# Binary: ./target/release/turbovault

Opção 1: Vault Estático (Recomendado para Vault Único)

turbovault --vault /path/to/your/vault --profile production

Em seguida, adicione ao ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--vault", "/path/to/your/vault", "--profile", "production"]
    }
  }
}

Opção 2: Adição de Vault em Tempo de Execução (Recomendado para Múltiplos Vaults)

Inicie o servidor sem um vault:

turbovault --profile production

Em seguida, adicione vaults dinamicamente:

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--profile", "production"]
    }
  }
}

Uma vez conectado ao Claude:

You: "Add my vault at ~/Documents/Notes"
Claude: [Calls add_vault("personal", "~/Documents/Notes")]

You: "Search for machine learning notes"
Claude: [Uses search() across the indexed vault]

You: "What are my most important notes?"
Claude: [Uses get_hub_notes() to find key concepts]

Gravações Atômicas com Git

Para vaults já gerenciados pelo Git, habilite o backend transacional na configuração YAML do TurboVault:

vaults:
  - name: personal
    path: ~/Documents/Notes
    is_default: true
    write_backend: git
    git:
      include_ignored: false
      require_commit_message: false

Inicie com turbovault --config ~/.turbovault/config.yaml. Cada mutação é então um commit Git. Lotes de múltiplas operações constroem uma árvore isolada e avançam o branch com compare-and-swap, de modo que um caminho obsoleto aborta o lote inteiro e processos TurboVault concorrentes não podem intercalar commit/materialização. O backend também se recusa a sobrescrever caminhos tocados sujos ou não rastreados e se recusa a redefinir um índice contendo alterações em staged.

O Que o Claude Pode Fazer?

Busca e Descoberta

You: "Find all notes about async Rust and show how they connect"
Claude: search() -> recommend_related() -> get_related_notes() -> explain relationships

Inteligência de Vault

You: "What's the health of my vault? Any issues I should fix?"
Claude: quick_health_check() -> full_health_analysis() -> get_broken_links() -> generate fixes

Navegação no Grafo de Conhecimento

You: "What are my most important notes? Which ones are isolated?"
Claude: get_hub_notes() -> get_isolated_clusters() -> suggest connections

Criação Estruturada de Notas

You: "Create a project note for the TurboVault launch with status tracking"
Claude: list_templates() -> create_from_template() -> write auto-formatted note

Operações de Conteúdo em Lote

You: "Move my 'MLOps' note to 'AI/Operations' and identify links to update"
Claude: get_backlinks() -> move_note() -> edit_note() for each affected reference

Sugestões de Links

You: "Based on my vault, what notes should I link this to?"
Claude: suggest_links() -> get_link_strength() -> recommend cross-references

74 Ferramentas MCP Organizadas por Categoria

Operações de Arquivo e Lote (8)

read_note — Obtém o conteúdo da nota com hash para detecção de conflitos
write_note — Cria/sobrescreve notas (cria diretórios automaticamente)
edit_note — Edições cirúrgicas via blocos SEARCH/REPLACE
delete_note — Exclusão segura com rastreamento de links
move_note — Renomeia/realoca uma nota; vaults com Git reescrevem atomicamente wikilinks de entrada
move_file — Move/renomeia arquivos que não são notas (ex.: anexos, imagens)
get_notes_info — Metadados para múltiplas notas em uma única chamada
batch_execute — Um único commit tudo-ou-nada com write_backend: git; direto permanece sequencial

Git Fanout (4)

begin_fanout — Abre um worktree isolado para gravações paralelas de agentes
commit_fanout — Mescla um fanout ativo de volta ao vault base
abandon_fanout — Descarta um fanout sem alterar o vault base
list_orphan_fanouts — Diagnostica worktrees deixados por sessões interrompidas

Metadados e Tags (3)

update_frontmatter — Aplica patch em campos de frontmatter (merge ou replace)
get_metadata_value — Extrai valores de frontmatter (suporte a notação de ponto)
manage_tags — Adiciona, remove ou lista tags de notas

Análise de Links (6)

get_backlinks — Todas as notas que linkam PARA esta nota
get_forward_links — Todas as notas para as quais esta nota linka
get_related_notes — Travessia de grafo multi-hop (encontra conexões não óbvias)
get_hub_notes — Top 10 notas mais conectadas (conceitos-chave)
get_dead_end_notes — Notas com links de entrada, mas sem links de saída
get_isolated_clusters — Subgrafos desconectados no seu vault

Métricas de Grafo e Sugestões (3)

suggest_links — Sugestões de links com IA para uma nota
get_link_strength — Força de conexão entre notas (0.0–1.0)
get_centrality_ranking — Métricas de centralidade de grafo (betweenness, closeness, eigenvector)

Busca (8)

search — Busca ranqueada por BM25 em todas as notas (<500ms em 100k notas)
advanced_search — Busca com filtros de tag, frontmatter, caminho e limite
search_by_frontmatter — Encontra notas por par chave-valor de frontmatter
recommend_related — Recomendações com ML baseadas em similaridade de conteúdo
find_notes_from_template — Encontra todas as notas que usam um template específico
query_metadata — Consultas de padrão em frontmatter
inspect_frontmatter — Inspeção de schema para consultas SQL (recurso: sql)
query_frontmatter_sql — SQL arbitrário contra frontmatter via GlueSQL (recurso: sql)

Semântica e Similaridade (5)

semantic_search — Busca semântica TF-IDF com pontuações de similaridade e termos compartilhados
find_similar_notes — Notas com conteúdo similar a uma determinada nota
find_duplicates — Detecção de quase-duplicatas (filtro SimHash + verificação TF-IDF)
compare_notes — Pontuação de similaridade, vocabulário compartilhado, diff e recomendação de merge
diff_notes — Diff unificado entre duas notas

Saúde e Qualidade do Vault (10)

quick_health_check — Pontuação de saúde rápida de 0-100 (<100ms)
full_health_analysis — Auditoria abrangente do vault com recomendações
get_broken_links — Todos os links apontando para notas inexistentes
detect_cycles — Cadeias de referência circular (às vezes intencionais)
explain_vault — Visão geral holística substituindo 5+ chamadas separadas
evaluate_note_quality — Pontuação de qualidade por nota com recomendações de melhoria
vault_quality_report — Avaliação de qualidade em todo o vault (piores N notas)
find_stale_notes — Notas não modificadas dentro de um limite de dias
analyze_note_grounding — Primitivas de fundamentação para uma nota (afirmações, citações, flag de não citado) para alimentar um juiz LLM externo
find_ungrounded_notes — Encontra notas com risco de alucinação que fazem afirmações sem citar fonte

Formato de Conhecimento Aberto (4)

okf_validate — Valida o vault como um bundle OKF v0.1 (conformidade + vocabulário de conceito type); utilizável como gate de CI/pré-publicação
generate_index — Gera/atualiza arquivos index.md para divulgação progressiva (idempotente)
append_log_entry — Acrescenta uma entrada datada ao histórico de atualizações log.md de um diretório (§7)
visualize — Renderiza o grafo de conceitos como um arquivo HTML compartilhável e autocontido (grafo dirigido por força + notas renderizadas + backlinks)

Templates e OFM (6)

list_templates — Descobre templates disponíveis
get_template — Detalhes do template e campos obrigatórios
create_from_template — Renderiza e grava notas com template
get_ofm_syntax_guide — Referência focada do Obsidian Flavored Markdown
get_ofm_quick_ref — Folha de consulta rápida de OFM
get_ofm_examples — Veja todos os recursos do Obsidian Flavored Markdown

Ciclo de Vida do Vault (8)

create_vault — Cria programaticamente um novo vault
add_vault — Registra e inicializa automaticamente um vault em tempo de execução
remove_vault — Cancela o registro do vault (seguro, não exclui arquivos)
list_vaults — Todos os vaults registrados com status
get_vault_config — Inspeciona as configurações do vault
set_active_vault — Alterna o contexto entre múltiplos vaults
get_active_vault — Vault ativo atual
get_vault_context — Meta-ferramenta: uma única chamada retorna status do vault, ferramentas disponíveis, guia OFM

Auditoria e Histórico (5)

audit_log — Log de alterações cronológico com IDs de operação para rollback
audit_stats — Visão geral da auditoria: detalhamento de operações + uso de disco do snapshot
diff_note_version — Diff de uma nota contra uma versão auditada anterior
rollback_preview — Pré-visualiza o que um rollback alteraria (somente leitura)
rollback_note — Desfaz uma alteração por ID de operação (atômico, auditado)

Exportação (4)

export_health_report — Exporta a saúde do vault como JSON/CSV
export_broken_links — Exporta links quebrados com sugestões de correção
export_vault_stats — Exportação de estatísticas e métricas
export_analysis_report — Trilha de auditoria completa

Fluxos de Trabalho do Mundo Real

Inicializar Sem um Vault

# Server starts with NO vault required
response = client.call("get_vault_context")
# Returns: "No vault registered. Call add_vault() to get started."

response = client.call("add_vault", {
    "name": "personal",
    "path": "~/Documents/Obsidian"
})
# Auto-initializes: scans files, builds link graph, indexes for search

Fluxo de Trabalho Multi-Vault

# Add multiple vaults
client.call("add_vault", {"name": "work", "path": "/work/notes"})
client.call("add_vault", {"name": "personal", "path": "~/notes"})

# Switch context instantly
client.call("set_active_vault", {"name": "work"})
search_results = client.call("search", {"query": "Q4 goals"})

client.call("set_active_vault", {"name": "personal"})
recommendations = client.call("recommend_related", {"path": "AI/ML.md"})

Manutenção e Reparo do Vault

# Quick diagnostic
health = client.call("quick_health_check")
if health["data"]["score"] < 60:
    # Deep analysis if needed
    full_analysis = client.call("full_health_analysis")

# Find and fix issues
broken = client.call("get_broken_links")
# Process broken links...

# Atomic bulk repair
client.call("batch_execute", {
    "operations": [
        {"type": "DeleteNote", "path": "old/deprecated.md"},
        {"type": "MoveNote", "from": "old/notes.md", "to": "new/notes.md"},
        # ... more operations
    ]
})

# Verify improvement
client.call("explain_vault")  # Holistic view

Descoberta de Conteúdo

# Find what matters
hubs = client.call("get_hub_notes")  # Top concepts
orphans = client.call("get_dead_end_notes")  # Incomplete topics

# Deep search
results = client.call("search", {"query": "machine learning"})

# Explore relationships
related = client.call("get_related_notes", {
    "path": "AI/ML.md",
    "max_hops": 3
})

# Get suggestions
suggestions = client.call("suggest_links", {"path": "AI/ML.md"})

Perfil de Performance

Operação	Tempo	Observações
`read_note`	<10ms	Instantâneo com cache
`get_backlinks`, `get_forward_links`	<50ms	Consulta de grafo
`write_note`	<50ms	Inclui atualização do grafo
`search` (10 mil notas)	<100ms	Tantivy BM25
`quick_health_check`	<100ms	Pontuação heurística
`full_health_analysis`	1–5s	Exaustivo, use com moderação
`explain_vault`	1–5s	Agrega 5+ análises
Inicialização do vault	100ms–5s	Depende do tamanho do vault

Insight principal: Operações rápidas (<100ms) para tarefas comuns, operações mais lentas (1–5s) para análise exaustiva. Claude usa fallbacks inteligentes.

Perfis de Configuração

Perfil	Caso de Uso
`development`	Desenvolvimento local com logging detalhado
`production`	Produção com auditoria de segurança e logging otimizado
`readonly`	Acesso somente leitura para exploração segura
`high-performance`	Vaults grandes (10 mil+ notas) com cache agressivo

Visibilidade de Ferramentas

O TurboVault pode reduzir o contexto de tools/list aplicando regras de visibilidade do TurboMCP a partir de ~/.turbovault/config.yaml ou --config:

tool_visibility:
  hidden:
    - full_health_analysis
    - explain_vault
  disabled:
    - delete_note

Use hidden para ferramentas avançadas que devem permanecer acionáveis pelo nome exato, disabled para ferramentas que devem falhar de forma fechada, e allowed quando você quiser uma allowlist explícita. Overrides equivalentes via env/CLI estão disponíveis através de TURBOVAULT_HIDDEN_TOOLS, TURBOVAULT_DISABLED_TOOLS, TURBOVAULT_ALLOWED_TOOLS, e --hidden-tools, --disabled-tools, --allowed-tools.

Implementação do SDK e do Servidor

O TurboVault é projetado para dois públicos principais: desenvolvedores que constroem sobre o Rust SDK e usuários que buscam um servidor MCP autônomo.

Como Servidor MCP Autônomo

A maneira mais rápida de começar é usando o binário pré-compilado. Ele é totalmente autossuficiente e otimizado para desempenho:

Otimização em tempo de link (LTO) para velocidade máxima
Transports configuráveis (STDIO, HTTP, WebSocket, TCP)
Zero dependências externas (basta apontar para o seu vault)

# Build the optimized binary
cargo build --release --features full

# Run it
./target/release/turbovault --vault /path/to/vault --profile production

Como Rust SDK (Biblioteca)

O núcleo do TurboVault é uma coleção de crates modulares. Use-os para construir seus próprios mecanismos de busca, ferramentas de gestão de conhecimento, ou até mesmo seus próprios servidores MCP especializados.

// Use in your own Rust projects
use turbovault_core::MultiVaultManager;
use turbovault_vault::VaultManager;
use turbovault_tools::SearchEngine;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Initialize the MultiVault manager
    let manager = MultiVaultManager::new();
    
    // 2. Add and initialize a vault (scans files, builds graph)
    manager.add_vault("notes", "/home/user/notes").await?;
    
    // 3. Perform high-level operations
    let vault = manager.get_vault("notes")?;
    let results = vault.search("machine learning")?;
    
    // 4. Use these components to build your own custom MCP server
    // or integrate into existing Rust applications.
    Ok(())
}

Cada crate é publicado no crates.io, então você pode depender de componentes individuais ou da stack completa.

Arquitetura

Construído como um workspace Rust modular:

turbovault-core        — Core types, MultiVaultManager, configuration
turbovault-parser      — OFM (Obsidian Flavored Markdown) parsing
turbovault-graph       — Link graph analysis with petgraph
turbovault-vault       — Vault operations, file I/O, atomic writes
turbovault-batch       — Validated sequential batch operations
turbovault-export      — JSON/CSV/Markdown export
turbovault-sql         — SQL frontmatter queries (GlueSQL, feature-gated)
turbovault-tools       — 74 MCP tool implementations
turbovault-plugin-api  — Curated plugin facade, provider contract, event hooks
turbovault (binary)    — CLI and MCP server entry point

Todos os crates são publicados em crates.io para uso público.

Suporte a Obsidian Flavored Markdown (OFM)

O TurboVault entende completamente a sintaxe do Obsidian:

Wikilinks: [[note]], [[note|alias]], [[note#section]], [[note#^block]]
Embeds: ![[image.png]], ![[note]], ![[note#section]]
Tags: #tag, #parent/child/tag
Tarefas: - [ ] Task, - [x] Done
Callouts: > [!type] Title
Frontmatter: Metadados YAML com parsing automático
Cabeçalhos: Extração de estrutura hierárquica

Segurança

Proteção contra path traversal — Sem acesso fora dos limites do vault
Desserialização type-safe — O sistema de tipos do Rust previne injeção
Escritas atômicas — Arquivo temporário → rename atômico (nunca corrompe em falha)
Detecção de conflitos baseada em hash — edit_note detecta modificações concorrentes
Limites de tamanho de arquivo — Padrão de 5MB por arquivo (configurável)
Sem execução de shell — Zero risco de injeção de comandos
Auditoria de segurança — Logs detalhados em modo de produção

Requisitos do Sistema

Rust: 1.90.0 ou posterior
SO: Linux, macOS, Windows
Memória: 100MB base + ~80MB por 10 mil notas
Disco: Insignificante (índice em memória)

Compilando a partir do Código Fonte

git clone https://github.com/epistates/turbovault.git
cd turbovault

# Development build
cargo build

# Production build (optimized)
cargo build --release

# Run tests
cargo test --all

Ou use o Makefile:

make build       # Debug build
make release     # Production build
make test        # Run tests
make clean       # Clean build artifacts

Documentação

Docs

Exemplos

Exemplo 1: Organização Orientada por Busca

You: "What topics do I have the most notes on?"
Claude:
  1. get_hub_notes() -> [AI, Project Management, Rust, Python]
  2. For each hub:
     - get_related_notes() -> related topics
     - get_backlinks() -> importance/connectivity
  3. Report: "Your core topics are AI (23 notes) and Rust (18 notes)"

Exemplo 2: Melhoria da Saúde do Vault

You: "My vault feels disorganized. Help me improve it."
Claude:
  1. quick_health_check() -> Health: 42/100
  2. full_health_analysis() -> Issues: 12 broken links, 8 orphaned notes
  3. get_broken_links() -> List of specific broken links
  4. suggest_links() -> AI-powered link recommendations
  5. Apply fixes individually, or use batch_execute() after reviewing its fail-fast semantics
  6. explain_vault() -> New health: 78/100

Exemplo 3: Criação de Conteúdo Baseada em Templates

You: "Create project notes for Q4 initiatives"
Claude:
  1. list_templates() -> "project", "task", "meeting"
  2. create_from_template("project", {
       "title": "Q4 Planning",
       "status": "In Progress",
       "deadline": "2024-12-31"
     })
  3. Creates structured note with auto-formatting
  4. Returns path for follow-up edits

Benchmarks

M1 MacBook Pro, 10 mil notas, build de produção:

Leitura de arquivo: <10ms
Escrita de arquivo: <20ms
Busca simples: <50ms
Análise de grafo: <200ms
Inicialização do vault: ~500ms
Uso de memória: ~80MB

Roadmap

Monitoramento de vault em tempo real (framework VaultWatcher pronto)
Resolução de links entre vaults
Suporte a vault criptografado
Locking colaborativo
Transport WebSocket (além do stdio do MCP)

Contribuindo

Contribuições são bem-vindas! Por favor, garanta:

Todos os testes passam: cargo test --all
Código formatado: cargo fmt --all
Sem avisos do clippy: cargo clippy --all -- -D warnings

Licença

Licença MIT - Veja LICENSE para detalhes