vault-cortex

Servidor MCP para vaults do Obsidian — busca, memória e acesso completo ao vault sem plugins para qualquer agente de IA.

GitHub

Experimente este MCPPatrocinado

Documentação

Vault Cortex é um servidor MCP autônomo que oferece 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 precisar do 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 o 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 dos 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	Escrever de volta no Obsidian

Todas 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 resolve 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 os 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 reordenamento 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, e depois concluir, repriorizar ou mover 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. Escritas 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 usando o 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.

Configuração manual (sem necessidade de Node.js)

# 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 do seu 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) e 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 pergunta a URL pública e o nome do cofre, captura o token do Sync para você e gera o token MCP; a configuração do HTTPS fica por sua conta.

	Railway	Render	Autogerenciado
			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á administra 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 no modo de configuração: abrir a URL dele 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 detalha o fluxo completo.

Autogerenciado: 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 orienta sobre 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, e então 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 usando o 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.

Configuração manual (sem necessidade de Node.js)

# 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

Deixou OBSIDIAN_AUTH_TOKEN vazio? Assim que o contêiner estiver no ar, abra <PUBLIC_URL>/setup no navegador e entre — configure o HTTPS primeiro, pois a página envia sua senha do Obsidian para o servidor (passo a passo completo →).

Conecte seu cliente MCP

Configuração	URL do servidor
Local	`http://localhost:8000/mcp`
Remoto (um clique)	`https://<host>/mcp` — `<host>` é o domínio que o Render ou Railway mostra na página do serviço
Remoto (autogerenciado)	`<PUBLIC_URL>/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 a partir daí. Clientes sem OAuth (MCP Inspector, scripts) enviam o token diretamente como um 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 para limitar ao diretório atual apenas.

Claude Desktop (URLs http exigem a ponte mcp-remote)

Um servidor remoto com uma URL https publicamente acessível é adicionado diretamente no diálogo "Add custom connector" do Claude Desktop — sem edição de arquivos. Qualquer URL http — incluindo localhost — é rejeitada por esse diálogo, então registre-a em claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config abre o arquivo) por meio da ponte stdio mcp-remote:

{
  "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 — os conectores dele são buscados no lado do servidor e nunca alcançam localhost.

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

Consulte Autenticação para ambos os métodos e durações de token.

Como Funciona

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

Seu cofre continua sendo a fonte da verdade — o servidor lê e escreve 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 todos os dispositivos: edite uma nota no celular e ela fica 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 contra 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 Reciprocal Rank Fusion, e então o reordenador refina o resultado fundido:

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

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

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

Memória

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

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

Somente acréscimo — 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, correspondidas por palavra-chave e por significado, das mais antigas para as mais recentes. 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.

A camada inteira é 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 → Memory para o pipeline de recuperação, modelo de indexação, inicialização automática e comportamento de opt-out, 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 significantes de emoji ou campos inline, organizados sob cabeçalhos 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 pistas do quadro, a sintaxe de datas e qual cabeçalho é a pista 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 pista Kanban. Cada resultado carrega o caminho da nota, número da linha e o cabeçalho mais próximo quando a tarefa está sob um (a pista em um quadro Kanban) — sem leituras de acompanhamento 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 cabeçalho 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 cabeçalhos e reordenar dentro de uma pista em uma única chamada
Concluir — marcar uma tarefa como concluída detecta automaticamente a pista 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 maneira 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 significantes de emoji ou Dataview campos inline, o servidor lê ambos e escreve no formato para o qual seu plugin Tasks está configurado — lido das configurações do plugin quando seu cofre sincroniza .obsidian/, com significantes de emoji como padrão caso contrário

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

Arquivos

Suas notas incorporam capturas de tela, diagramas de arquitetura de referência e links para canvases e arquivos de dados — mas para um agente lendo markdown, ![[diagram.png]] é apenas texto. Vault Cortex trata arquivos como parte do cofre em vez de bagunça 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 arquivo no quadro aparecem no grafo de links — backlinks e links de saída funcionam como links nota-a-nota. A fonte JSON exata está a uma flag de distância quando fidelidade total importa
PDFs — texto é extraído com hierarquia de cabeçalhos, blocos de código e hiperlinks preservados; conteúdo de PDF é pesquisável em texto completo junto com suas notas. Defina raw: true para renderizar páginas como imagens, 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 em intervalos 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 → Files para o pipeline de imagem e modelo de despacho.

Ferramentas

Categoria	Ferramenta	Descrição
CRUD do Cofre	`vault_read_note`	Ler uma nota — corpo completo, propriedades, esboço ou uma seção
	`vault_write_note`	Criar uma nota (falha se já existir; defina `overwrite` para substituir)
	`vault_patch_note`	Edição direcionada por cabeçalho (anexar, prefixar, substituir com guarda `include_children`, inserir)
	`vault_replace_in_note`	Localizar e substituir texto em uma nota (primeira correspondência ou `replace_all_occurrences`)
	`vault_delete_span`	Excluir um bloco de linhas por âncoras curtas, sem re-citação completa
	`vault_replace_span`	Substituir um bloco de linhas por âncoras curtas com novo conteúdo
	`vault_insert_at_anchor`	Inserir conteúdo antes ou depois de uma linha identificada por uma âncora curta
	`vault_list_notes`	Listar notas com filtro opcional de glob/pasta
	`vault_delete_note`	Excluir uma nota, respeitando a configuração de lixeira do cofre (caminhos protegidos aplicados)
	`vault_move_note`	Mover ou renomear uma nota, reescrevendo links em todo o cofre
Pesquisa	`vault_search`	Pesquisa híbrida com filtros de tag/pasta/propriedade/data
	`vault_search_by_tag`	Encontrar notas por tag (correspondência exata ou de prefixo)
	`vault_search_by_folder`	Navegar por notas em uma pasta com metadados
	`vault_recent_notes`	Notas modificadas ou criadas recentemente
	`vault_list_tags`	Todas as tags com contagens de uso
Tarefas	`vault_list_tasks`	Índice de tarefas em todo o cofre com profundidade de subtarefas — ciente de Kanban, filtros de data/prioridade/cabeçalho
	`vault_create_task`	Criar uma tarefa formatada corretamente — datas, prioridade, recorrência, on_completion, subtarefas, block_id
	`vault_update_task`	Editar qualquer campo de tarefa em uma chamada — concluir uma tarefa recorrente cria sua próxima ocorrência
Memória	`vault_get_memory`	Ler memória estruturada (arquivo, seção ou tudo)
	`vault_update_memory`	Anexar uma entrada datada a uma seção de memória
	`vault_delete_memory`	Remover uma entrada de memória específica por data
	`vault_list_memory_files`	Descobrir arquivos de memória, suas seções e a política de entrada de cada arquivo
	`vault_memory_recall`	Recuperação híbrida em granularidade de entrada de um tópico em arquivos de memória, das mais antigas para as mais recentes
Propriedades	`vault_list_property_keys`	Todas as chaves de propriedade com valores de exemplo
	`vault_list_property_values`	Valores distintos para uma chave de propriedade
	`vault_search_by_property`	Encontrar notas por chave-valor de propriedade
	`vault_update_properties`	Adicionar ou atualizar propriedades sem tocar no corpo
Links	`vault_get_backlinks`	Notas que vinculam a um caminho dado
	`vault_get_outgoing_links`	Links de uma nota dada
	`vault_find_orphans`	Notas sem links de entrada
Arquivos	`vault_read_file`	Ler um arquivo não-markdown — imagens entregues como imagens, canvases como esboços legíveis
	`vault_list_files`	Navegar pelos arquivos não-markdown do cofre com tamanhos e contagens por extensão
Notas Diárias	`vault_get_daily_note`	A nota diária de hoje (ou de qualquer data)

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 pesquisa, o grafo de links e a camada de memória no momento da invocação, então monta os resultados com instruções guiadas — para que a sessão comece fundamentada no estado real do seu cofre, não em suposições.

Prompt	Argumentos	O que faz
`vault-orientation`	—	Levanta estatísticas do cofre, distribuição de pastas, taxas de adoção de propriedades (sinaliza baixa adoção), órfãos, contagem de links quebrados, tags, notas recentes e a camada de memória — com sugestões contextuais de ferramentas
`memory-review`	`file?`, `max_chars?`	Visão geral estrutural (chamadas de escopo, contagens de entrada de seção) + conteúdo datado como linha do tempo. Reflexão guiada: narrativa de evolução, adequação de escopo, lacunas de preenchimento e análise de cobertura — somente acréscimo por padrão, poda proposta apenas para arquivos `entry-policy: living`. Oculto quando `MEMORY_ENABLED=false`, `READONLY_MODE=true` ou `DISABLED_TOOLS` inclui `vault_update_memory`.
`daily-review`	`date?`, `max_chars?`	Reconcilia um dia — nota diária, status de tarefas em todo o cofre (vencidas/atrasadas, agendadas), notas modificadas, links de saída (detecção de links quebrados) e backlinks — revela o que aconteceu, o que está aberto e o que precisa de acompanhamento

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

Suporte ao cliente: Prompts funcionam no Claude Desktop (Chat e Cowork — via menu + sob seu conector), Claude Code (comandos de barra) e OpenCode. Suporte em outros clientes (Cursor, Windsurf) varia — consulte a matriz de clientes MCP para o mais recente.

Propriedades

Vault Cortex indexa cada propriedade em suas notas, mas cinco recebem tratamento promovido — colunas dedicadas para filtragem rápida e campos de nível superior em todo resultado de pesquisa e descoberta:

Propriedade	O que você pode fazer
`title`	Nome de exibição em resultados de pesquisa; recorre ao nome do arquivo quando ausente
`tags`	Pesquisar e filtrar por tag, incluindo hierarquias pai-filho (`project` corresponde a `project/vault-cortex`)
`type`	Filtrar por tipo de nota — `meeting`, `person`, `session-log` ou qualquer valor que seu cofre use
`created`	Ordenar por data de criação e ver quando cada nota foi criada junto com cada resultado de pesquisa
`related`	Filtrar notas que referenciam cruzadamente um link específico — revela conexões invisíveis sem uma consulta de grafo

Todas as outras propriedades ainda são 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 em todo o seu cofre.

Estas são convenções, não requisitos — Vault Cortex funciona com qualquer esquema de propriedade. Propriedades promovidas oferecem filtragem mais rica e resultados mais limpos prontamente. Callouts de destaque recebem o mesmo tratamento. Quando o primeiro conteúdo do corpo de uma nota é um callout do Obsidian (> [!type]) — seja logo após o frontmatter ou logo após o título — ele é indexado e exibido junto a cada resultado de descoberta (em vault_search, peça com include_leading_callout). Isso torna as notas autodescritivas: um agente que examina os resultados pode ver para que serve cada nota antes de decidir qual ler. Os modelos de memória usam callouts > [!info] Scope of this file para isso, e qualquer nota no seu cofre 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ê define substitui todo o padrão derivado. 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.

Variável	Obrigatória?	Padrão	Descrição
`MCP_AUTH_TOKEN`	Sim	—	Token Bearer para autenticação (também a chave de assinatura JWT)
`VAULT_PATH`	Somente local	—	Caminho no host para o seu cofre (origem do bind mount; remoto usa um volume nomeado). Não deve conter `*`, `?` ou `[` — rejeitado na inicialização.
`PUBLIC_URL`	Somente remoto	—	URL pública para metadados de descoberta OAuth. Preenchida automaticamente no Render e Railway (a partir de `RENDER_EXTERNAL_URL` ou `RAILWAY_PUBLIC_DOMAIN`) quando deixada vazia
`OBSIDIAN_AUTH_TOKEN`	—	—	Token de autenticação do Obsidian Sync. Deixe vazio para entrar pela página `/setup` após a implantação; ou o `get-sync-token` da CLI captura para você
`VAULT_NAME`	Somente remoto	—	Nome exato do seu cofre do Obsidian (sensível a maiúsculas/minúsculas)
`VAULT_PASSWORD`	Somente remoto	—	Senha de criptografia de ponta a ponta, se o seu cofre tiver uma. Deixe vazia caso contrário.
`STORAGE_ROOT`	—	—	Um diretório para tudo que precisa persistir — o cofre, o índice de busca e o estado do Obsidian Sync — para plataformas de hospedagem de contêineres que permitem um único volume persistente (Railway, Render). Monte o volume lá e defina isso para o mesmo caminho. Não deve conter `*`, `?` ou `[` — rejeitado na inicialização.
`EMBEDDING_ENABLED`	—	`true`	Defina `false` para desativar o pipeline de embeddings — pula download do modelo, tabelas vetoriais, passadas de embeddings e busca híbrida. A busca volta para correspondência de palavras-chave FTS5.
`RERANK_MODE`	—	`blended`	Modo de reordenação por cross-encoder: `blended` aplica mistura de pontuação ciente de posição após fusão RRF (~200ms de latência adicional), `none` pula a reordenação. Só tem efeito quando `EMBEDDING_ENABLED` é verdadeiro.
`MEMORY_ENABLED`	—	`true`	Defina `false` para desativar completamente a camada de memória — oculta ferramentas de memória, pula bootstrap, omite memória dos metadados do servidor. `MEMORY_DIR` ainda fornece os padrões para `PROTECTED_PATHS` e `ORPHAN_EXCLUDE_FOLDERS` quando `false`.
`FILE_TOOLS_ENABLED`	—	`true`	Defina `false` para ocultar ferramentas de arquivo (`vault_read_file`, `vault_list_files`) — útil para implantações remotas onde o Obsidian Sync tem sincronização de anexos desativada.
`READONLY_MODE`	—	`false`	Defina `true` para ocultar toda ferramenta que altera o cofre e pular a criação automática da pasta de memória — clientes conectados podem ler e buscar, mas nunca editar.
`DISABLED_TOOLS`	—	—	Oculte ferramentas individuais por nome, separadas por vírgula (ex.: `vault_delete_note,vault_move_note`). Os nomes correspondem à coluna Ferramenta na tabela de ferramentas. Apenas subtrativo — não pode reativar uma ferramenta que outra configuração oculta. Um nome de ferramenta desconhecido interrompe o servidor na inicialização, então erros de digitação aparecem imediatamente.
`MEMORY_DIR`	—	`About Me`	Pasta do cofre para arquivos de memória estruturados
`PROTECTED_PATHS`	—	`MEMORY_DIR`, pasta de notas diárias	Pastas que `vault_delete_note` e `vault_move_note` se recusam a tocar. A pasta padrão de notas diárias é lida de `DAILY_NOTES_FOLDER` ou `.obsidian/daily-notes.json` (padrão `Daily Notes`). Substitui o padrão completamente quando definida.
`ORPHAN_EXCLUDE_FOLDERS`	—	`DAILY_NOTES_FOLDER, Templates, MEMORY_DIR`	Pastas excluídas da detecção de órfãos. A parte de notas diárias do padrão vem apenas de `DAILY_NOTES_FOLDER` — esta não lê `daily-notes.json`.
`DAILY_NOTES_FOLDER`	—	da configuração do cofre	Define a pasta onde suas notas diárias ficam. Quando não definida, lida da `.obsidian/daily-notes.json` do cofre, com fallback para `Daily Notes`. Veja Notas diárias.
`DAILY_NOTES_FORMAT`	—	da configuração do cofre	Define o formato do nome de arquivo das notas diárias — mesmos tokens da configuração de formato de data de notas diárias do Obsidian. Quando não definido, lido da `.obsidian/daily-notes.json` do cofre, com fallback para `YYYY-MM-DD`. Veja Notas diárias.
`TZ`	—	`UTC`	Fuso horário IANA para timestamps e resolução de notas diárias
`SERVICE_DOCUMENTATION_URL`	—	URL do repositório GitHub	URL retornada nos metadados de descoberta OAuth
`LOG_LEVEL`	—	`info`	Verbosidade de registro: `debug`, `info`, `warn`, `error`
`LOG_DIR`	—	`/data/logs` (remoto), `$STORAGE_ROOT/data/logs` (volume único), `none` (local)	Diretório para arquivos de log que sobrevivem à recriação do contêiner. O log do próprio contêiner (o que `docker logs` mostra) é sempre gravado, mas o Docker o descarta sempre que o contêiner é recriado — em atualizações de imagem ou mudanças de configuração. Arquivos com data no nome sob `LOG_DIR` vivem no volume de dados e sobrevivem. `none` mantém apenas o log do contêiner.
`LOG_RETENTION_DAYS`	—	`90`	Dias para manter arquivos de log antes da limpeza automática na inicialização; só se aplica quando `LOG_DIR` é um caminho
`WINDOWS_MODE`	—	`false`	No Windows? Defina `true`. Alterna o observador de arquivos para polling e movimentações de notas para gravações baseadas em renomeação, para que um cofre em uma unidade `C:` funcione com o Docker Desktop. Seguro deixar ativado em qualquer configuração Windows; desnecessário em macOS/Linux/WSL2.
`MAX_FILE_BYTES`	—	`52428800` (50 MiB)	Tamanho máximo de arquivo que `vault_read_file` lerá (em bytes). Arquivos que excedem isso são rejeitados antes da leitura. Aumente para cofres com arquivos individuais muito grandes.
`MAX_IMAGE_OUTPUT_BYTES`	—	`49152` (48 KiB)	Orçamento de bytes para imagens entregues por `vault_read_file`, em bytes binários antes da codificação base64. Imagens que excedem isso são reduzidas e recompactadas para caber. Dimensionado para o limite mais restrito de clientes MCP mainstream; aumente para clientes que aceitam respostas maiores.
`MAX_PDF_RENDER_PAGES`	—	`5`	Máximo de páginas de PDF para renderizar como imagens quando `raw: true` está definido em `vault_read_file`. O orçamento de bytes por página é `MAX_IMAGE_OUTPUT_BYTES` dividido uniformemente entre as páginas renderizadas — menos páginas significa maior qualidade em cada uma.
`TRASH_RETENTION_DAYS`	Somente local	`30`	Dias que uma nota excluída sob a configuração padrão "Mover para a lixeira do sistema" do Obsidian permanece em `.trash/` antes que o servidor a limpe. Defina `none` para manter essas notas para sempre. Apenas notas que o próprio servidor moveu para lá são limpas. Com o Obsidian Sync, exclusões são permanentes no servidor e recuperáveis pelo histórico de versões do Sync.
`TRUST_PROXY_HOPS`	—	`0`	Número de saltos de proxy reverso confiáveis usados para derivar o IP do cliente de `X-Forwarded-For` (limitação de taxa OAuth, logs de requisição). Defina `1` quando exatamente um proxy que você controla fica na frente do servidor (Caddy, nginx, Cloudflare Tunnel, API Gateway). Com `0`, cabeçalhos de encaminhamento injetados são ignorados.
`TRUST_FORWARDED_HOPS`	—	`0`	Quantas entradas `for=` finais no cabeçalho RFC 7239 `Forwarded` pertencem a proxies que você controla. `0` ignora o cabeçalho; `1` quando o proxy na frente o escreve (ex.: AWS API Gateway); `2` quando um CDN fica na frente desse proxy e é o único caminho para alcançá-lo.

Veja templates/memory/ para exemplos de arquivos de memória e a filosofia de design de entradas datadas.

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 do nome de arquivo configurados no Obsidian, lidos da .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 pela sincronização de 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 de configuração do cofre, por dispositivo. Detalhes: a 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 — mesmos tokens da configuração de 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 fallback para 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 de 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 nunca poderia encontrar 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 de 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 gravação 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 no-clobber) para fechar a janela TOCTOU em movimentações de notas.
Mutex por arquivo — chamadas MCP concorrentes serializam ou falham rapidamente por arquivo. Movimentações bloqueiam a origem, o destino e cada origem de backlink como uma unidade.
Traversal de caminho bloqueado — resolveSafePath() resolve e 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, em conformidade com o 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 "Mover para a lixeira do sistema" ou em "Mover para a lixeira do Obsidian", uma nota excluída é movida para .trash/ dentro do cofre em vez de ser removida (um contêiner não tem lixeira do sistema; .trash/ é o fallback do próprio 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, não 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.
Endurecimento do contêiner — usuário não-root, init PID 1, sem gerenciadores de pacotes na imagem de runtime, 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 de mecanismo 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: requisições são validadas em duas camadas independentes (autorizador Lambda do API Gateway + middleware Express). Segundo 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:

Método	Usado por	Formato do token
OAuth 2.1	Claude Desktop, Claude Code, claude.ai, qualquer cliente OAuth	JWT (HS256, 6h)
Bearer estático	Claude Code, MCP Inspector, curl	`MCP_AUTH_TOKEN` bruto

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:

Seu cliente registra automaticamente e recebe um client ID e um secret.
Digite seu MCP_AUTH_TOKEN na página de consentimento do navegador para aprovar o acesso.
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 na sua máquina. Implantações remotas rodam em um VPS ou em uma plataforma de contêiner 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 caderno de IA cujo verdadeiro lar é o banco de dados do fornecedor: aqui o host é uma conveniência, não um guardião.

Caminho	O quê	Guia
Local	Seu cofre na sua máquina — grátis, sem nuvem	`deploy/local/`
Remoto · um clique	Render ou Railway — um volume persistente, sem servidor para gerenciar	`deploy/render/` · `deploy/railway/`
Remoto · auto-hospedado	VPS + Obsidian Sync — acesso de qualquer dispositivo	`deploy/remote/`
Remoto · AWS (SST)	Implantação de referência IaC — infraestrutura automatizada, autenticação com defesa em profundidade	`DEPLOY.md`

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

Todo caminho executa 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 AWS de referência custa cerca de US$ 17–29/mês no total.

Implantação em um clique

Botões e pré-requisitos estão em Quick Start → Remote. Cada guia explica a implantação, onde encontrar sua URL e token, como atualizar e como excluir: deploy/render/ (do Blueprint render.yaml 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. Executa 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 todas as ferramentas e prompts 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 má configuração. Veja SECURITY.md para a cobertura relevante à 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: skill obsidian-vault

O servidor MCP funciona sozinho com qualquer cliente. Para agentes que suportam skills (Claude Code, Cursor, Windsurf, Cline e 70+ outros), a skill 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 skill →

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êiner 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 reclassificação 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 do npm público no momento da construção; a licença MIT aqui não o cobre, e usá-lo requer uma assinatura ativa do Obsidian Sync. A imagem :latest (local) não contém componentes proprietários.