Vault Cortex

Vault Cortex é um servidor MCP autônomo que dá a qualquer agente de IA busca híbrida, gerenciamento de tarefas, memória estruturada e acesso de leitura/escrita ao seu cofre do Obsidian. Sem plugins, sem Obsidian em execução, sem ponte separada. Um contêiner Docker, sua pasta do cofre, um conjunto completo de ferramentas + prompts guiados. Execute-o em um servidor remoto com Obsidian Sync, e o mesmo cofre fica acessível pelo seu celular, claude.ai ou qualquer cliente MCP remoto, protegido com OAuth 2.1. Implante com um clique ou hospede você mesmo; de qualquer forma, o cofre é sempre seu.

Conteúdo — O que você obtém · Início Rápido · Como Funciona · Busca Híbrida · Memória · Tarefas · Arquivos · Ferramentas · Prompts · Propriedades · Configuração · Notas Diárias · Integridade de Dados · Autenticação · Implantação · Implantação com Um Clique · Implantações da Comunidade

O que você obtém

Buscar no cofre	Raciocinar sobre notas	Gravar de volta no Obsidian

As três demonstrações rodam no Claude mobile. O cofre está em um servidor remoto, não no celular.

• Acesso remoto — funciona do seu celular, de um servidor remoto ou de qualquer cliente MCP via OAuth 2.1. Um clique no Render ou Railway leva você até lá sem servidor para gerenciar; um VPS também funciona.
• Sem plugins — o Obsidian não precisa estar em execução. O servidor trabalha diretamente com arquivos .md no disco. A sincronização headless mantém o cofre atualizado.
• Busca híbrida — correspondência de palavras-chave FTS5 + similaridade semântica vetorial via fusão RRF, refinada por reclassificação cross-encoder para consultas com alta intenção. Palavras-chave permanecem precisas em termos exatos e jargões; vetores encontram notas mesmo quando suas palavras diferem das do cofre.
• Memória estruturada — entradas datadas e somente de acréscimo acumulam-se em uma camada de conhecimento pessoal, inicializada automaticamente para personalização de IA. A recuperação por tópico responde "o que eu penso sobre X?" com a visão atual e o histórico datado por trás dela — evolução incluída.
• Tarefas — consultas e atualizações de tarefas com suporte a Kanban: triagem por status, datas ou prioridade, depois conclua, repriorize ou mova tarefas entre colunas em uma única chamada. Concluir uma tarefa recorrente gera sua próxima ocorrência. Analisa tanto os formatos de emoji do plugin Tasks quanto os de campo inline do Dataview.
• Grafo de links — backlinks, links de saída e detecção de órfãos em todo o cofre
• Arquivos — leia também os arquivos não-Markdown do cofre: imagens chegam como imagens reais (reduzidas para caber quando necessário), PDFs como texto estruturado ou páginas renderizadas, canvases como esboços legíveis, arquivos de dados como texto
• Nativo do Obsidian — entende frontmatter, wikilinks, tags, cabeçalhos e notas diárias
• Fluxos guiados — prompts integrados para saúde do cofre, revisão de memória e reconciliação diária — montados a partir de dados ao vivo do cofre a cada vez

Testado em uma viagem de 15 dias pela Europa. Mais de 30 sessões pelo celular, 216 chamadas de ferramentas, zero necessidade de laptop. Gravações em uma sessão ficaram imediatamente disponíveis na seguinte, entre cidades e dias.

Início Rápido

Local (2 minutos — Docker + sua pasta do cofre)

Pré-requisitos: Docker (ou um runtime compatível com Docker, ex.: OrbStack, Colima, Podman), Node.js >= 22.12 (apenas para a CLI — o servidor em si roda no Docker) e um cofre do Obsidian (ou qualquer pasta de arquivos .md).

npx vault-cortex@latest init

É isso — a CLI pergunta o caminho do seu cofre, gera o token de autenticação e os arquivos de configuração, inicia o servidor e imprime os detalhes de conexão para o seu cliente MCP (referência da CLI →).

Configurou com a CLI? Ela gerencia o servidor daqui em diante — configure, upgrade, start, restart, logs, down (referência da CLI →).

Configurou com Compose? Continue com Compose também para atualizações (docker compose pull && docker compose up -d) — a CLI e o Compose gerenciam o contêiner de forma independente.

# 1. Get the quickstart files
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/.env.example

# 2. Configure
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN (openssl rand -hex 32) and VAULT_PATH

# 3. Start
docker compose up

Guia local completo → (inclui configuração para Windows)

Remoto (acesso de qualquer lugar)

Seu cofre em um servidor, mantido atualizado pelo Obsidian Sync, acessível pelo celular, claude.ai ou qualquer cliente MCP. As opções de um clique pedem o nome do seu cofre e o fuso horário (além da senha do cofre, se ele for criptografado), depois cuidam de HTTPS, reinicializações, um token MCP gerado e armazenamento persistente. Após a implantação, uma página de configuração orienta você a entrar no Obsidian Sync pelo navegador. No seu próprio servidor, a CLI pede a URL pública e o nome do cofre, captura o token do Sync para você e gera o token MCP; o HTTPS fica por sua conta.

	Railway	Render	Auto-hospedado
			Configuração via CLI →
Conta	Railway no plano Hobby ou superior — o volume de 5 GB está incluído	Render com cartão cadastrado	Um VPS com Docker
Custo	Medido por uso: tipicamente US$ 20–30/mês para um cofre pessoal — um pouco abaixo do Render para um cofre tranquilo, um pouco acima para um movimentado	Fixo: cerca de US$ 26/mês para a instância Standard (2 GB) e disco de 5 GB, cobrado por segundo	O que seu VPS custar
Escolha se	Você quer o início mais fácil — o template já deixa você em um projeto configurado	Uma conta previsível importa mais que o acabamento da configuração	Você já roda um servidor ou quer controle total
Guia	Guia Railway →	Guia Render →	Guia remoto →

Todos os três precisam de uma assinatura do Obsidian Sync. Seja qual for sua escolha, o servidor é substituível e seu cofre não — ele permanece em Markdown simples no Obsidian Sync e nos seus dispositivos; o contêiner guarda apenas uma cópia.

A página de configuração. Implante sem um token do Obsidian Sync e o servidor inicia em modo de configuração: abrir sua URL no navegador leva a uma página de login em /setup. Insira suas credenciais da conta Obsidian uma vez (com suporte a dois fatores) — você entra diretamente no Obsidian; o servidor guarda apenas o token do Sync desse login, reinicia e baixa seu cofre.

A página de login, protegida pelo seu token MCP. Cada guia de implantação percorre o fluxo completo.

Auto-hospedado: seu próprio VPS

A CLI do Vault Cortex configura o mesmo contêiner em qualquer máquina Linux que você administre — você gerencia o servidor, a imagem e as atualizações. Você precisa de Node.js >= 22.12 para a própria CLI; o servidor roda no Docker.

# On your VPS:
npx vault-cortex@latest init --mode remote

É isso — a CLI percorre a URL pública, o token do Obsidian Sync (ela pode executar get-sync-token para você), o nome do cofre, a senha do cofre para um cofre criptografado e a configuração de autenticação, depois inicia o servidor (referência da CLI →).

Configurou com a CLI? Ela gerencia o servidor daqui em diante — configure, upgrade, start, restart, logs, down (referência da CLI →).

Configurou com Compose? Continue com Compose também para atualizações (docker compose pull && docker compose up -d) — a CLI e o Compose gerenciam o contêiner de forma independente.

# On your VPS:
mkdir -p /opt/vault-cortex && cd /opt/vault-cortex
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/.env.example
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN, PUBLIC_URL, VAULT_NAME (OBSIDIAN_AUTH_TOKEN optional — /setup handles it)
docker compose up -d

Conecte seu cliente MCP

Adicione a URL do servidor em qualquer cliente MCP — Claude Code, Claude Desktop, Cursor, OpenCode ou qualquer outro. Clientes OAuth abrem uma página de consentimento no seu navegador — aprove com seu token, e o cliente cuida da renovação do token daí em diante. Clientes sem OAuth (MCP Inspector, scripts) enviam o token diretamente como cabeçalho Authorization: Bearer.

Claude Code:

claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp   # local (or <PUBLIC_URL>/mcp)

--scope user registra o servidor para todos os projetos; omita-o para limitar o escopo apenas ao diretório atual.

{
  "mcpServers": {
    "vault-cortex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization: Bearer <your MCP_AUTH_TOKEN>"
      ]
    }
  }
}

claude.ai (web e mobile) conecta-se apenas à configuração remota — seus conectores são buscados no lado do servidor e nunca podem alcançar o localhost.

"Servidor MCP remoto" refere-se ao tipo de conexão (HTTP) — na configuração local, o servidor ainda é executado inteiramente na sua máquina.

Consulte Autenticação para ambos os métodos e tempos de vida dos tokens.

Como Funciona

Tudo é executado em um único contêiner Docker, trabalhando diretamente com os arquivos .md no disco:

• Seu cofre permanece a fonte da verdade — o servidor lê e grava os mesmos arquivos Markdown simples que seus aplicativos Obsidian usam.
• A busca é dado derivado — um observador de arquivos mantém o índice (palavras-chave + vetores) atualizado conforme as notas mudam, e ele pode ser reconstruído a partir das suas notas a qualquer momento.
• A imagem remota adiciona um loop de sincronização — um serviço Obsidian Sync integrado mantém o cofre do contêiner atualizado com cada dispositivo: edite uma nota no seu celular e ela estará pesquisável momentos depois; um agente escreve uma nota e ela aparece no Obsidian.

graph LR
    subgraph container ["One Docker container"]
        Sync["sync service<br/>(remote image)"]
        Vault[("/vault<br/>.md files — source of truth")]
        Index[("search index<br/>keywords + vectors")]
        Server["MCP server"]
        Sync <-->|read/write| Vault
        Vault -->|file watcher| Index
        Server <-->|read/write| Vault
        Server -->|query| Index
    end
    Obsidian["Your Obsidian apps<br/>(phone, laptop)"] <-->|Obsidian Sync| Sync
    Client["Any MCP client<br/>(Claude, Cursor, claude.ai)"] -->|OAuth 2.1 / Bearer| Server

Consulte ARCHITECTURE.md para o design completo, diagramas de fluxo de autenticação e detalhamento de componentes.

Busca Híbrida

A busca por palavras-chave sozinha falha quando seu vocabulário não corresponde ao do cofre — "aspirações" não encontrará uma nota sobre "metas", "colegas" não trará à tona seu arquivo de "referências". Em testes com um cofre real, 30% das consultas em linguagem natural retornaram zero ou resultados tangenciais apenas com palavras-chave. A busca híbrida eliminou essas falhas no mesmo teste.

A busca híbrida funde as classificações de palavras-chave e vetores via Fusão de Classificação Recíproca, e então o reclassificador refina o resultado fundido:

• Palavras-chave (FTS5) permanecem precisas em termos exatos, jargões e valores de propriedades
• Vetores (sqlite-vec) preenchem a lacuna de vocabulário combinando por significado
• Reclassificador (cross-encoder) refina a ordenação pontuando cada par consulta-documento em conjunto — resgata consultas com alta intenção onde palavras-chave e vetores ambos falham

Todos os modelos são executados localmente (~45MB no total, sem API externa). Defina EMBEDDING_ENABLED=false para busca apenas por palavras-chave, ou RERANK_MODE=none para pular a reclassificação e obter menor latência.

Consulte ARCHITECTURE.md → Busca Híbrida para detalhes do modelo, pesos de mistura e o detalhamento completo do pipeline.

Memória

Uma camada de memória que só cresce só é útil se os agentes puderem recuperar as entradas certas sem ler tudo de volta a cada vez. Quando você tem centenas de entradas datadas em vários arquivos — preferências, princípios, estilo de comunicação, compromissos em andamento — leituras de arquivos inteiros enterram o sinal em material irrelevante. O sistema de memória é projetado para recuperação direcionada.

A camada é uma pasta de arquivos Markdown simples (padrão: About Me/) contendo entradas datadas sob títulos de tópicos — criada automaticamente com modelos iniciais na primeira execução, crescida por agentes por meio de vault_update_memory. Três propriedades fazem funcionar:

• Somente anexação — entradas nunca são sobrescritas; correções chegam como novas entradas datadas. A camada se torna uma base de conhecimento pessoal que captura seu estado atual e a evolução por trás dele
• Recuperação por tópico — vault_memory_recall recupera todas as entradas relevantes em todos os arquivos de memória de uma vez, combinadas por palavra-chave e por significado, das mais antigas primeiro. Pergunte "o que eu penso sobre X?" e obtenha a visão atual mais o histórico datado de como ela se desenvolveu — sem precisar ler arquivos inteiros ou adivinhar qual arquivo contém o quê
• Cresce sem degradar — limitar resultados (limit) descarta as entradas menos relevantes, nunca uma fatia da linha do tempo. Uma camada de memória com 500 entradas atende a uma consulta direcionada tão bem quanto uma com 50

Arquivos que descrevem o que é atual em vez do que foi verdadeiro (rotinas, compromissos ativos) podem declarar entry-policy: living no frontmatter — suas entradas expiradas são podáveis em vez de preservadas, mantendo a imagem do estado atual precisa.

Toda a camada é opcional — defina MEMORY_ENABLED=false para ocultar as ferramentas de memória e pular a criação automática da pasta completamente.

Consulte ARCHITECTURE.md → Memória para o pipeline de recuperação, modelo de indexação, inicialização automática e comportamento de exclusão, e templates/memory para o formato de arquivo, convenção de política de entrada e modelos iniciais.

Tarefas

Os metadados de tarefas vivem em markdown simples — espalhados por arquivos, codificados em indicadores de emoji ou campos inline, organizados sob títulos de Kanban. Um agente respondendo "o que está atrasado?" precisaria analisar cada arquivo e entender seu formato escolhido; concluir uma tarefa em um quadro Kanban significa conhecer a estrutura de faixas do quadro, a sintaxe de datas e qual título é a faixa de concluído.

A camada de tarefas lida com isso para que os agentes não precisem:

• Encontrar — filtrar por status, seis campos de data (vencimento, agendada, início, criação, conclusão, cancelamento), prioridade, pasta ou faixa Kanban. Cada resultado carrega o caminho da nota, número da linha e o título mais próximo quando a tarefa está sob um (a faixa em um quadro Kanban) — sem leituras adicionais para localizar uma tarefa
• Criar — adicionar uma tarefa formatada corretamente em uma única chamada: descrição, prioridade, datas, recorrência, ação "Ao concluir", block_id e subitens de checklist, colocados sob um título no topo, na base ou em um slot de cartão exato, ou aninhados sob uma tarefa pai
• Atualizar — concluir, repriorizar, editar o texto, definir ou limpar datas, recorrência e a ação "Ao concluir", adicionar itens de checklist, mover tarefas entre títulos e reordenar dentro de uma faixa em uma única chamada
• Concluir — marcar uma tarefa como concluída detecta automaticamente a faixa de concluído e carimba a data de conclusão, respeitando a configuração "Definir data de conclusão" do plugin; reverter remove a data. A conclusão também executa os comportamentos próprios do plugin Tasks:
  • uma tarefa recorrente gera sua próxima ocorrência, com datas avançadas da forma que o plugin as calcula
  • uma tarefa configurada para excluir "Ao concluir" desaparece da nota
• Ambos os formatos — seja qual for o formato que você usa, plugin Tasks indicadores de emoji ou Dataview campos inline, o servidor lê ambos e grava no formato para o qual seu plugin Tasks está configurado — lido das configurações do plugin quando seu cofre sincroniza .obsidian/, com indicadores de emoji como padrão caso contrário

Consulte ARCHITECTURE.md → Tarefas para o modelo de indexação, ordenação em cascata de datas e detecção de faixas Kanban.

Arquivos

Suas notas incorporam capturas de tela, diagramas de arquitetura de referência e vinculam canvases e arquivos de dados — mas para um agente lendo markdown, ![[diagram.png]] é apenas texto. Vault Cortex trata os arquivos como parte do cofre em vez de desordem ao redor dele — vinculados, dimensionados e legíveis, cada um na forma que um agente pode usar:

• Imagens — a imagem em si, não o nome do arquivo. Capturas de tela e diagramas são reduzidos e recompactados no lado do servidor quando excedem o que os clientes MCP aceitam, então até uma sessão de celular pode olhar um diagrama de arquitetura de 5MB
• Canvases — um quadro Canvas chega como um esboço legível: seus grupos, o conteúdo de cada cartão em ordem de leitura e as conexões entre eles. O conteúdo do Canvas é pesquisável em texto completo, e referências de arquivos no quadro aparecem no grafo de links — backlinks e links de saída funcionam como links nota-a-nota. O JSON exato está a uma flag de distância quando fidelidade total importa
• PDFs — o texto é extraído com hierarquia de títulos, blocos de código e hiperlinks preservados; o conteúdo do PDF é pesquisável em texto completo junto com suas notas. Defina raw: true para renderizar páginas como imagens em vez disso, mostrando layout, diagramas e tabelas que a extração de texto não pode preservar — PDFs escaneados e somente imagem funcionam neste modo
• Arquivos de texto e dados — TXT, SVG, JSON, XML, CSV, YAML, logs e arquivos Bases retornam exatamente como escritos; os primeiros 100 KB de conteúdo são pesquisáveis em texto completo. Arquivos de dados grandes e logs podem ser lidos um intervalo de linhas por vez, com cada página informando onde você está e quanto do arquivo resta
• Navegar — listar os arquivos de qualquer pasta visível com contagens por extensão e tamanhos de arquivo; arquivos aos quais uma nota vincula relatam seu tamanho no grafo de links também

Defina FILE_TOOLS_ENABLED=false para ocultar as ferramentas de arquivo — útil quando seu cofre remoto sincroniza sem anexos.

Consulte ARCHITECTURE.md → Arquivos para o pipeline de imagens e o modelo de despacho.

Ferramentas

Prompts

Ferramentas são orientadas por modelo — o assistente as chama. Prompts são fluxos de trabalho que você aciona. Cada um consulta o índice de busca, o grafo de links e a camada de memória no momento da invocação e, em seguida, monta os resultados com instruções guiadas — para que a sessão comece ancorada no estado real do seu vault, não em suposições.

Os prompts se adaptam à sua configuração (MEMORY_DIR, configurações de notas diárias) e funcionam em qualquer vault imediatamente. Passe max_chars para limitar o conteúdo incorporado se o seu cliente tiver limites de payload.

Suporte ao cliente: Os prompts funcionam no Claude Desktop (Chat e Cowork — via menu + no seu conector), Claude Code (comandos de barra) e OpenCode. O suporte em outros clientes (Cursor, Windsurf) varia — consulte a matriz de clientes MCP para as informações mais recentes.

Propriedades

O Vault Cortex indexa todas as propriedades nas suas notas, mas cinco recebem tratamento promovido — colunas dedicadas para filtragem rápida e campos de nível superior em todos os resultados de busca e descoberta:

Todas as outras propriedades continuam totalmente consultáveis — use vault_search com filters.properties para consultas combinadas de texto + metadados, ou vault_search_by_property para buscas somente de metadados. vault_list_property_keys e vault_list_property_values descobrem quais propriedades existem no seu vault.

Estas são convenções, não requisitos — o Vault Cortex funciona com qualquer esquema de propriedades. Propriedades promovidas oferecem filtragem mais rica e resultados mais limpos imediatamente.

Callouts principais recebem o mesmo tratamento. Quando o primeiro conteúdo do corpo de uma nota é um callout do Obsidian (> [!type]) — logo após o frontmatter ou logo após o título — ele é indexado e exibido junto com cada resultado de descoberta (em vault_search, peça com include_leading_callout). Isso torna as notas autodescritivas: um agente que examina resultados pode ver para que cada nota serve antes de decidir qual ler. Os modelos de memória usam callouts > [!info] Scope of this file para isso, e qualquer nota no seu vault pode usar o mesmo padrão.

Configuração

Todas as configurações são variáveis de ambiente com padrões sensatos. Alguns padrões derivam de outras configurações — a coluna Padrão mostra cada derivação, e um valor que você definir substitui o padrão derivado inteiro. Implantações remotas também encaminham as próprias configurações do Obsidian Sync — DEVICE_NAME, SYNC_MODE, CONFLICT_STRATEGY, SYNC_CONFIGS, SYNC_EXCLUDED_FOLDERS, SYNC_FILE_TYPES — documentadas na tabela de configuração do guia remoto.

Notas diárias

vault_get_daily_note e o prompt de revisão diária encontram suas notas diárias usando a pasta e o formato de data no nome do arquivo configurados no Obsidian, lidos do .obsidian/daily-notes.json do seu cofre:

• Modo local lê o arquivo diretamente do seu cofre montado por bind — nada para configurar.
• Modo remoto o recebe através da sincronização da configuração do cofre do Obsidian Sync. O servidor o puxa por padrão (a configuração SYNC_CONFIGS em .env), mas você provavelmente precisará ativar o lado de envio: Configurações do Obsidian → Sync → Sincronização da configuração do cofre, por dispositivo. Detalhes: seção Notas diárias do guia remoto.

Quando o arquivo não está disponível — ou se você usa o plugin Periodic Notes, cujas configurações ele não reflete — defina os valores você mesmo:

• DAILY_NOTES_FOLDER — qualquer caminho relativo ao cofre: Journal, Planner/Daily
• DAILY_NOTES_FORMAT — os mesmos tokens do formato de data do Obsidian: YYYY-MM-DD-dddd, YYYY/MM/DD, MMM D, YYYY, …

Você pode definir um ou ambos — um valor definido sempre vence o arquivo de configuração. Sem nenhuma das fontes, o servidor usa como fallback Daily Notes e YYYY-MM-DD.

Nota: Alguns tokens de formato de data não são suportados — ordinais (Do, Mo, DDDo, wo), dd (dia da semana com 2 letras), d (número do dia da semana), e, k/kk, e os formatos localizados (L–LLLL, LT, LTS). O servidor não consegue reproduzir os nomes de arquivo que o Obsidian cria com esses tokens, então ele nunca encontraria as notas. Se seu formato usar algum deles, vault_get_daily_note retorna um erro claro — mude o formato no Obsidian ou defina DAILY_NOTES_FORMAT para uma alternativa suportada.

Integridade dos dados

O Vault Cortex escreve em notas pessoais — a camada de segurança de arquivos é construída para prevenir corrupção, não apenas erros.

• Escritas atômicas — cada escrita de arquivo é preparada em um arquivo temporário e depois renomeada. Leitores nunca veem uma nota parcial ou de 0 bytes. Criações exclusivas usam link() (POSIX sem sobrescrita) para fechar a janela TOCTOU em movimentações de notas.
• Mutex por arquivo — chamadas de ferramentas MCP concorrentes serializam ou falham rapidamente por arquivo. Movimentações bloqueiam a origem, o destino e cada fonte de backlink como uma unidade.
• Traversal de caminho bloqueado — resolveSafePath() resolve e depois verifica o prefixo de cada caminho. A exclusão de caminhos protegidos é recusada após a normalização. Nomes de arquivos de memória rejeitam separadores no limite.
• Caminhos ocultos são proibidos — arquivos e pastas que começam com um ponto (.obsidian/, .trash/) nunca aparecem em listagens ou buscas, e qualquer chamada de ferramenta que os alvo diretamente é rejeitada, correspondendo ao Obsidian. Configurações de plugins e suas chaves de API ficam fora de alcance.
• Exclusões respeitam a configuração de lixeira do Obsidian — com "Arquivos excluídos" no padrão do Obsidian "Mover para a lixeira do sistema" ou em "Mover para a lixeira do Obsidian", uma nota excluída vai para .trash/ dentro do cofre em vez de ser removida (um contêiner não tem lixeira do sistema; .trash/ é o fallback próprio do Obsidian para isso). "Excluir permanentemente" remove a nota de vez.
• Implantações com Obsidian Sync excluem permanentemente — a exclusão sincroniza para todos os dispositivos, e a recuperação é o histórico de versões do Sync, em vez de uma pasta de lixeira.
• Lixeira limitada com varredura de retenção — notas que o servidor move para .trash/ sob a configuração padrão do sistema são limpas após TRASH_RETENTION_DAYS (padrão de 30 dias; none as mantém para sempre). A varredura remove apenas arquivos que registrou — notas que o próprio Obsidian enviou para a lixeira e exclusões "Mover para a lixeira do Obsidian" nunca são tocadas.
• Prevenção de injeção — consultas de busca são parametrizadas e sanitizadas com FTS5; o conteúdo do prompt é envolvido em marcadores de dados XML com escape de tags de fechamento para prevenir injeção por quebra de tags.
• Hardening do contêiner — usuário não-root, init PID 1, sem gerenciadores de pacotes na imagem de runtime, imagem base com digest fixado, desligamento gracioso.
• Modo somente leitura — READONLY_MODE=true oculta toda ferramenta que edita o cofre, então um cliente conectado pode ler e buscar, mas nunca alterar uma nota.

Veja ARCHITECTURE.md → Data Integrity para detalhes dos mecanismos e SECURITY.md → Runtime Hardening para como cada parte do servidor é endurecida.

Autenticação

Para um servidor com acesso de leitura/escrita a notas pessoais, autenticação não é opcional. O Vault Cortex implementa a especificação completa OAuth 2.1, incluindo PKCE e rotação de refresh tokens. A implantação AWS (SST) adiciona defesa em profundidade: as requisições são validadas em duas camadas independentes (autorizador Lambda do API Gateway + middleware Express). De acordo com a análise de segurança MCP da BlueRock de 2026, apenas 8,5% dos servidores MCP implementam OAuth; 41% não têm autenticação alguma.

Dois métodos:

O método segue do seu cliente — OAuth quando ele suporta, o token bruto em um cabeçalho caso contrário (Conecte seu cliente MCP mostra ambos).

OAuth usa registro dinâmico de clientes — sem necessidade de Client ID ou Secret manual:

1. Seu cliente se registra automaticamente e recebe um client ID e um secret.
2. Digite seu MCP_AUTH_TOKEN na página de consentimento do navegador para aprovar o acesso.
3. Seu cliente inclui o secret emitido em requisições de token subsequentes automaticamente.

Refresh tokens têm expiração deslizante de 60 dias. Access tokens são vinculados à URL do seu servidor, então um token emitido para uma implantação nunca é aceito por outra. Rotacionar MCP_AUTH_TOKEN encerra todas as sessões — cada cliente reautoriza pela página de consentimento.

Veja ARCHITECTURE.md → Auth para o diagrama completo do fluxo.

Opções de implantação

Execuções locais rodam na sua máquina. Implantações remotas rodam em um VPS ou em uma plataforma de contêineres hospedada — seu cofre fica acessível mesmo quando seu laptop está fechado.

Qualquer caminho que você escolher, o servidor é substituível e seu cofre não é. Suas notas são arquivos Markdown simples, sincronizados pelo Obsidian para todos os seus dispositivos; o contêiner guarda uma cópia e um índice que pode reconstruir do zero. Desligue o VPS, exclua o serviço Render ou Railway, troque de host — os mesmos arquivos ainda estão na sua máquina e no Obsidian Sync, legíveis por qualquer coisa. Essa é a diferença de um bloco de notas de IA cujo verdadeiro lar é o banco de dados do fornecedor: aqui o host é uma conveniência, não um guardião.

O caminho AWS inclui workflows de CI/CD construídos para este repositório — quem fizer fork precisa configurar suas próprias credenciais e estágio antes de implantar.

Cada caminho roda a mesma imagem, ghcr.io/aliasunder/vault-cortex — :latest é apenas o servidor MCP (local), :remote agrupa o Obsidian Sync no mesmo contêiner sob supervisão do s6-overlay (um clique, auto-hospedado e AWS). Um contêiner significa que qualquer runtime OCI funciona: docker run, Podman, nerdctl — Docker Compose é opcional.

Também no Docker Hub: as mesmas imagens são espelhadas em aliasunder/vault-cortex. GHCR é a fonte primária; as tags do Hub são idênticas.

Custo: Uma configuração remota precisa de um VPS ou um plano de plataforma hospedada, além de US$ 4/mês para o Obsidian Sync. Uma instância de 2 GiB lida bem com busca semântica para um cofre típico; 4 GiB adiciona margem para busca concorrente e cofres maiores. Pule a busca semântica completamente para reduzir ainda mais. Somente local é grátis. A implantação de referência AWS custa cerca de US$ 17–29/mês tudo incluído.

Implantação em um clique

Botões e pré-requisitos estão em Quick Start → Remote. Cada guia percorre a implantação, onde encontrar sua URL e token, como atualizar e como excluir: deploy/render/ (do render.yaml Blueprint na raiz do repositório) · deploy/railway/ (de um template publicado).

Implantações da comunidade

Templates de implantação construídos e mantidos pela comunidade — não testados aqui, e podem ficar desatualizados em relação aos lançamentos.

• vault-cortex-aca — template Bicep para Azure Container Apps por @flytzen. Roda a imagem :remote atrás do ingress do Container Apps com HTTPS gerenciado gratuito; o armazenamento é deliberadamente efêmero, com o Obsidian Sync como fonte da verdade.

Construiu uma implantação para outra plataforma? Abra um PR para adicioná-la aqui.

Desenvolvimento

# Run locally with hot reload
PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp

# Tests
npm test

# Full check suite
npm run prettier:check && npm run lint && npm run markdownlint && npm run knip && npm test && npm run build

npm test inclui testes de integração que iniciam um servidor real e chamam cada ferramenta e prompt via HTTP — verificando a aplicação de autenticação, superfícies de ferramentas controladas por configuração, integridade de mutações de escrita (cada escrita é lida de volta) e rejeição de inicialização em configuração incorreta. Veja SECURITY.md para a cobertura relevante de segurança.

MCP Inspector — interface de navegador interativa para testar ferramentas:

# Start server (terminal 1), then:
npx @modelcontextprotocol/inspector
# Enter http://localhost:8000/mcp as URL, local-dev-token as Bearer token

Veja CONTRIBUTING.md para a configuração completa de desenvolvimento.

Companheiro: habilidade obsidian-vault

O servidor MCP funciona sozinho com qualquer cliente. Para agentes que suportam habilidades (Claude Code, Cursor, Windsurf, Cline e 70+ outros), a habilidade obsidian-vault adiciona conhecimento mais profundo do Markdown com sabor Obsidian — convenções de frontmatter, sintaxe de callouts e formatos específicos de plugins como Dataview, Tasks e Kanban.

npx skills add aliasunder/agent-skills --skill obsidian-vault

Fonte da habilidade →

Roadmap

Trabalho planejado, o que está sendo explorado e não-objetivos explícitos estão em ROADMAP.md.

Agradecimentos

A sincronização do Obsidian é alimentada por obsidian-headless — abordagem de contêinerização inspirada no obsidian-headless-sync-docker do @Belphemur. O scaffolding de supervisão s6-overlay da imagem :remote foi absorvido do fork mantido daquele projeto e agora vive neste repositório.

O pipeline de busca híbrida se baseia em padrões do qmd do @tobi — fusão RRF com bônus de classificação, mistura de pontuação ciente de posição para reranking com cross-encoder, controle por hash de conteúdo e chunking ciente de cabeçalhos.

Contribuindo

Veja CONTRIBUTING.md para configuração de desenvolvimento, convenções de código e diretrizes de PR.

Licença

MIT A imagem :remote inclui obsidian-headless (o CLI ob), que é proprietário — seu package.json declara "license": "UNLICENSED" (© Dynalist Inc. / Obsidian). Ele é instalado a partir do npm público no momento da compilação; a licença MIT aqui não o cobre, e seu uso requer uma assinatura ativa do Obsidian Sync. A imagem :latest (local) não contém componentes proprietários.

Segurança

Reporte vulnerabilidades de forma privada — consulte SECURITY.md.