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 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. Implante em um VPS 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.

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

O que você obtém

Busque no cofre	Raciocine sobre as notas	Grave 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. Implante em um VPS com Obsidian Sync para acesso de qualquer lugar.
• 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 reordenação cross-encoder para consultas com alta intenção. As palavras-chave permanecem precisas em termos exatos e jargões; os 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 reconhecimento de Kanban: triagem por status, datas ou prioridade, e depois conclua, repriorize ou mova tarefas entre colunas em uma única chamada. Analisa tanto os emojis do plugin Tasks quanto os formatos de campos 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 de trabalho 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 >= 20.12 (apenas para a CLI — o servidor em si roda no Docker) e um cofre Obsidian (ou qualquer pasta de arquivos .md).

npx vault-cortex@latest init

É só 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 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. Obtenha os arquivos de início rápido

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

Edite o .env — defina MCP_AUTH_TOKEN (openssl rand -hex 32) e VAULT_PATH

3. Inicie

docker compose up

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

Remoto (acesso de qualquer lugar — Docker + Obsidian Sync)

Pré-requisitos: um VPS com Docker (ou um runtime compatível com Docker), uma assinatura do Obsidian Sync e Node.js >= 20.12 (apenas para a CLI — o servidor em si roda no Docker).

No seu VPS:

npx vault-cortex@latest init --mode remote

É só isso — a CLI orienta sobre a URL pública, o token do Obsidian Sync (ela pode executar o get-sync-token por você) e a configuração de autenticação, e então inicia o servidor (referência da CLI →).

No seu 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

Edite o .env — defina MCP_AUTH_TOKEN, PUBLIC_URL, OBSIDIAN_AUTH_TOKEN, VAULT_NAME

docker compose up -d

Guia remoto completo →

Conecte seu cliente MCP

Configuração	URL do servidor
Local	http://localhost:8000/mcp
Remoto	<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 (ou <PUBLIC_URL>/mcp)

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

Claude Desktop (localhost exige a ponte mcp-remote)

A caixa de diálogo "Adicionar conector personalizado" só aceita URLs https. Com um PUBLIC_URL https, adicione-o diretamente na caixa de diálogo do conector; para um servidor localhost, registre-o em claude_desktop_config.json através da ponte stdio mcp-remote:

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

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 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 cada dispositivo: edite uma nota no seu celular e ela fica pesquisável momentos depois; um agente escreve uma nota e ela aparece no Obsidian.

graph LR subgraph container ["Um contêiner Docker"] Sync["serviço de sincronização
(imagem remota)"] Vault[("/vault
.md files — fonte da verdade")] Index[("índice de busca
palavras-chave + vetores")] Server["servidor MCP"] Sync <-->|leitura/escrita| Vault Vault -->|observador de arquivos| Index Server <-->|leitura/escrita| Vault Server -->|consulta| Index end Obsidian["Seus aplicativos Obsidian
(celular, laptop)"] <-->|Obsidian Sync| Sync Client["Qualquer cliente MCP
(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 — os vetores preenchem a lacuna de vocabulário, e o reordenador resgata consultas com alta intenção onde nenhum dos dois sinais é forte por conta própria.

A busca híbrida combina três sinais de classificação via Fusão de Classificação Recíproca:

• Palavras-chave (FTS5) permanecem precisas em termos exatos, jargões e valores de propriedades
• Vetores (sqlite-vec) preenchem a lacuna de vocabulário ao corresponder pelo 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 falham

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 a reordenação 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 despejar tudo no contexto. Quando você tem centenas de entradas datadas em vários arquivos — preferências, princípios, estilo de comunicação, compromissos em andamento — ler arquivos inteiros desperdiça contexto com material irrelevante e enterra o sinal. O sistema de memória é projetado para recuperação direcionada: os agentes acumulam conhecimento ao longo do tempo e recuperam exatamente o que é relevante para a tarefa em questão.

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

• Somente de acréscimo — as 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, com correspondência por palavras-chave e semântica, 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 os resultados (max_results) 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 por completo.

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 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 colunas do quadro, a sintaxe de datas e qual cabeçalho é a coluna de concluídas.

A camada de tarefas cuida disso para que os agentes não precisem:

• Encontrar — filtre por status, seis campos de data (vencimento, agendamento, início, criação, conclusão, cancelamento), prioridade, pasta ou coluna Kanban. Cada resultado traz sua coluna, caminho da nota, título e número da linha — sem necessidade de leituras adicionais para localizar uma tarefa
• Atualizar — conclua, reprioritize e mova tarefas entre colunas Kanban em uma única chamada. Marcar uma tarefa como concluída detecta automaticamente a coluna de conclusão e registra a data de finalização; reverter remove a data. As três alterações podem ocorrer de uma só vez
• Ambos os formatos — independentemente do formato usado, indicadores de emoji do plugin Tasks ou campos inline do Dataview, o servidor lê ambos e grava no formato configurado para o seu plugin Tasks

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

Arquivos

Suas notas incorporam capturas de tela, referenciam diagramas de arquitetura e vinculam canvases e arquivos de dados — mas para um agente que lê markdown, ![[diagram.png]] é apenas texto. vault-cortex trata os arquivos como parte do vault, e não como ruído ao redor dele — vinculados, dimensionados e legíveis, cada um na forma que um agente pode realmente usar:

• Imagens — a imagem em si, não o nome do arquivo. Capturas de tela e diagramas são reduzidos e recompactados no servidor quando excedem o que os clientes MCP aceitam, então até uma sessão no celular pode visualizar 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 as referências a arquivos no quadro aparecem no grafo de links — backlinks e links de saída funcionam como links entre notas. A fonte JSON exata 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, mostrando layout, diagramas e tabelas que a extração de texto não consegue 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 por faixa de linhas, com cada página informando onde você está e quanto do arquivo resta
• Navegar — liste os arquivos de qualquer pasta visível com contagens por extensão e tamanhos de arquivo; arquivos aos quais uma nota vincula também reportam seu tamanho no grafo de links

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

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

Ferramentas

Categoria	Ferramenta	Descrição
CRUD do Vault	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 título (anexar, prefixar, substituir com guarda include_children, inserir)
vault_replace_in_note	Localizar e substituir texto em uma nota (primeira ocorrência ou replace_all_occurrences)
vault_delete_span	Excluir um bloco de linhas por âncoras curtas, sem re-citação completa
vault_list_notes	Listar notas com filtro opcional de glob/pasta
vault_delete_note	Excluir uma nota (caminhos protegidos são aplicados)
vault_move_note	Mover ou renomear uma nota, reescrevendo links em todo o vault
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 por 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 vault — ciente de Kanban, 6 campos de data, prioridade, escopo por pasta/título
vault_update_task	Alterações de status, prioridade e coluna em uma chamada — detecta automaticamente colunas de conclusão em quadros Kanban
Memória	vault_get_memory	Ler memória estruturada (arquivo, seção ou tudo)
vault_update_memory	Adicionar 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 granular por entrada de um tópico em arquivos de memória, do mais antigo ao mais recente
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 determinado caminho
vault_get_outgoing_links	Links de uma determinada nota
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 vault com tamanhos e contagens por extensão
Notas Diárias	vault_get_daily_note	Nota diária de hoje (ou de qualquer data)

Prompts

As 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 e então monta os resultados com instruções guiadas — para que a sessão comece fundamentada no estado real do seu vault, não em suposições.

Prompt	Argumentos	O que faz
vault-orientation	—	Levanta estatísticas do vault, 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 entradas por 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 anexação por padrão, poda proposta apenas para arquivos com 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 vault (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

Os prompts se adaptam à sua configuração (MEMORY_DIR, configurações de notas diárias) e funcionam com qualquer vault prontamente. 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 + sob 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 em 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:

Propriedade	O que você pode fazer
title	Nome de exibição nos resultados de busca; usa o nome do arquivo como fallback quando ausente
tags	Buscar 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 vault use
created	Ordenar por data de criação e ver quando cada nota foi criada junto a cada resultado de busca
related	Filtrar por notas que referenciam 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 apenas de metadados. vault_list_property_keys e vault_list_property_values descobrem quais propriedades existem em todo o seu vault.

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

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 a todos os resultados 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 vault pode usar o mesmo padrão.

Configuração

Todas as configurações são variáveis de ambiente com padrões sensatos. Implantações remotas têm configurações adicionais não incluídas abaixo (SYNC_CONFIGS, SYNC_MODE, …) — consulte a tabela de configuração do guia remoto.

Variável	Obrigatório?	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 do host para o seu vault (fonte do bind mount; remoto usa um volume nomeado)
PUBLIC_URL	Somente remoto	—	URL pública para metadados de descoberta OAuth
OBSIDIAN_AUTH_TOKEN	Somente remoto	—	Token de autenticação do Obsidian Sync — o get-sync-token da CLI captura isso para você
VAULT_NAME	Somente remoto	—	Nome exato do seu vault do Obsidian Sync (sensível a maiúsculas/minúsculas)
EMBEDDING_ENABLED	—	true	Defina false para desativar o pipeline de embeddings — pula download do modelo, tabelas de vetores, passos de embedding e busca híbrida. A busca volta a usar correspondência de palavras-chave FTS5.
RERANK_MODE	—	blended	Modo de reclassificação com cross-encoder: blended aplica mistura de pontuação ciente da posição após fusão RRF (~200ms de latência adicional), none pula a reclassificação. Só tem efeito quando EMBEDDING_ENABLED é true.
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 é ignorado 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 vault e pular a criação automática da pasta de memória — clientes conectados podem ler e pesquisar, mas nunca editar.
DISABLED_TOOLS	—	—	Oculta ferramentas individuais por nome, separadas por vírgula (ex.: vault_delete_note,vault_move_note). Os nomes correspondem à coluna Nome 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 vault para arquivos de memória estruturados
PROTECTED_PATHS	—	MEMORY_DIR, DAILY_NOTES_FOLDER	Pastas que vault_delete_note se recusa a tocar
ORPHAN_EXCLUDE_FOLDERS	—	DAILY_NOTES_FOLDER, Templates, MEMORY_DIR	Pastas excluídas da detecção de órfãos
DAILY_NOTES_FOLDER	—	da configuração do vault	Define a pasta onde suas notas diárias ficam. Quando não definido, lê de .obsidian/daily-notes.json do vault, com fallback para Daily Notes. Veja Notas diárias.
DAILY_NOTES_FORMAT	—	da configuração do vault	Define o formato do nome de arquivo da nota diária — mesmos tokens da configuração de formato de data de nota diária do Obsidian. Quando não definido, lê de .obsidian/daily-notes.json do vault, 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	Nível de verbosidade do log: debug, info, warn, error
LOG_DIR	—	/data/logs (remoto), não definido (local)	Diretório para arquivos de log persistentes. Quando definido, os logs são gravados em arquivos com data nesse diretório, além do stdout. Não definido significa apenas stdout.
LOG_RETENTION_DAYS	—	30	Dias para manter arquivos de log antes da limpeza automática na inicialização
WINDOWS_MODE	—	false	Está 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 vault na unidade C: funcione através do Docker Desktop. Pode 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 vaults 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 comuns; 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 é definido em vault_read_file. O orçamento de bytes por página é MAX_IMAGE_OUTPUT_BYTES dividido igualmente entre as páginas renderizadas — menos páginas significa maior qualidade em cada uma.

• Padrões inteligentes — definir MEMORY_DIR ou DAILY_NOTES_FOLDER atualiza automaticamente os padrões para PROTECTED_PATHS e ORPHAN_EXCLUDE_FOLDERS; quando DAILY_NOTES_FOLDER não está definido, Daily Notes preenche seu lugar. Uma pasta de notas diárias configurada apenas em daily-notes.json não é detectada — adicione-a a PROTECTED_PATHS você mesmo. Você só define esses explicitamente para uma lista totalmente personalizada.
• MEMORY_ENABLED=false desativa completamente a camada de memória — as ferramentas de memória ficam ocultas e a pasta de memória não é criada automaticamente.
• FILE_TOOLS_ENABLED=false oculta completamente as ferramentas de arquivo — útil quando o Obsidian Sync tem sincronização de anexos desativada e não há arquivos no disco.
• READONLY_MODE=true oculta toda ferramenta de escrita no vault e pula a criação automática da pasta de memória — clientes conectados podem ler e pesquisar, mas nunca editar.
• DISABLED_TOOLS oculta exatamente as ferramentas que você nomeia — para controle mais fino do que os interruptores acima, ex.: mantenha gravações ativas, mas remova vault_delete_note e vault_move_note. Referências cruzadas baseadas em disponibilidade nas descrições de ferramentas e prompts se ajustam automaticamente.

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 do .obsidian/daily-notes.json do seu vault:

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

Quando o arquivo não está disponível — ou você usa o plugin Periodic Notes, cujas configurações ele não reflete — defina DAILY_NOTES_FOLDER (qualquer caminho relativo ao vault: Journal, Planner/Daily) e DAILY_NOTES_FORMAT (mesmos tokens da configuração de formato de data do Obsidian: YYYY-MM-DD-dddd, YYYY/MM/DD, …). Você pode definir um ou ambos — um valor definido sempre vence o arquivo de configuração. Sem nenhuma das fontes, o servidor recorre a Daily Notes e YYYY-MM-DD.

Integridade de Dados

O Vault Cortex grava em notas pessoais — a camada de segurança de arquivos foi criada para prevenir corrupção, não apenas erros.

• Gravações 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 sem sobrescrita) para fechar a janela TOCTOU em movimentações de notas.
• Mutex por arquivo — chamadas concorrentes de ferramentas MCP serializam ou falham rapidamente por arquivo. Movimentações bloqueiam a origem, o destino e todas as fontes de backlinks 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, em conformidade com o Obsidian. Configurações de plugins e suas chaves de API ficam fora de alcance.
• Prevenção de injeção — consultas de busca são parametrizadas e sanitizadas com FTS5; o conteúdo de prompts é envolvido em marcadores de dados XML com escape de tags de fechamento para prevenir injeção por quebra de tags.
• Endurecimento de contêiner — usuário não-root, init PID 1, sem gerenciadores de pacotes na imagem de runtime, base com digest fixado, desligamento gracioso.

Veja ARCHITECTURE.md → Data Integrity para detalhes de mecanismos e SECURITY.md → Runtime Hardening para o inventário completo da superfície de ataque.

Autenticação

Para um servidor com acesso de leitura/gravação a notas pessoais, a 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:

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

OAuth usa registro dinâmico de clientes — sem necessidade de Client ID/Secret. Uma página de consentimento abre no seu navegador; insira seu MCP_AUTH_TOKEN para aprovar. Refresh tokens têm expiração deslizante de 60 dias (usuários diários nunca reautenticam).

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

Opções de Implantação

Local roda na sua máquina. Implantações remotas rodam em um VPS — seu vault fica acessível mesmo quando seu laptop está fechado.

Caminho	O quê	Guia
Local	Seu vault na sua máquina — gratuito, sem nuvem	deploy/local/
Remoto	VPS + Obsidian Sync — acesso de qualquer dispositivo	deploy/remote/
AWS (SST)	Implantação de referência IaC — infraestrutura automatizada, autenticação em profundidade	DEPLOY.md

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

Os três caminhos rodam 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 (remoto e AWS). Um único 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 e US$ 4/mês para o Obsidian Sync. Uma instância de 2 GiB lida bem com busca semântica para um vault típico; 4 GiB adiciona margem para busca concorrente e vaults maiores. Pule a busca semântica completamente para reduzir ainda mais. Somente local é gratuito. A implantação de referência AWS custa ~US$ 17–29/mês no total.

Implantações da comunidade

Modelos de implantação criados e mantidos pela comunidade — não testados aqui, e podem ficar desatualizados em relação aos lançamentos.

• vault-cortex-aca — modelo 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.

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

Desenvolvimento

Rode localmente com hot reload

PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp

Testes

npm test

Suíte completa de verificação

npm run prettier:check && npm run lint && 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 gravação (cada gravação é 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 interativa no navegador para testar ferramentas:

Inicie o servidor (terminal 1), depois:

npx @modelcontextprotocol/inspector

Insira http://localhost:8000/mcp como URL, local-dev-token como token Bearer

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 mais de 70 outros), a skill obsidian-vault adiciona conhecimento mais profundo de markdown no estilo 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

Fase	O quê	Status
1	CRUD de vault, busca de texto completo (FTS5), camada de memória, OAuth 2.1	Completa
2a	Busca híbrida — FTS5 + vetorial + fusão RRF, chunking ciente de cabeçalhos	Completa
2b	Reranker — reranking com cross-encoder, mistura de pontuações ciente de posição	Completa
3a	Camada de tarefas — índice de tarefas do vault, consultas estruturadas e atualizações de tarefas em uma chamada (formatos emoji do plugin Tasks + Dataview)	Completa
3b	Recall de memória — recuperação granular por entrada na história datada da camada de memória	Completa
3c	Consultas de grafo — travessia multi-salto no grafo de wikilinks existente do vault (caminhos, vizinhanças)	Explorando

Agradecimentos

A sincronização do Obsidian é alimentada por obsidian-headless — abordagem de conteinerizaçã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ções 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 construção; a licença MIT aqui não o cobre, e usá-lo exige uma assinatura ativa do Obsidian Sync. A imagem :latest (local) não contém componentes proprietários.

Segurança

Reporte vulnerabilidades de forma privada — veja SECURITY.md.