Obsidian MCP + recuperação híbrida: referência de 2026

Obsidian não é um aplicativo de anotações. É um corpus markdown em texto simples, com prioridade local e estruturado em grafo, que vira um reservatório de contexto para IA quando você adiciona infraestrutura de recuperação. 16.894 arquivos. 49.746 chunks. Consultas em 23 ms. Zero chamadas API. Um arquivo SQLite de 83 MB. Este guia cobre o sistema completo: da arquitetura do cofre à recuperação híbrida, da integração com MCP aos fluxos de trabalho operacionais.

Principais conclusões

Engenharia de contexto, não anotações. O valor de um vault do Obsidian para IA não está nas próprias notas, mas na camada de recuperação que as torna consultáveis. Um vault com 16.000 arquivos sem recuperação é um banco de dados apenas para escrita. Um vault com 200 arquivos, busca hybrid e integração com MCP é uma base de conhecimento para IA. A infraestrutura de recuperação é o produto. As notas são a matéria-prima.

A recuperação hybrid supera a busca puramente por palavras-chave ou puramente semântica. O BM25 encontra identificadores exatos e nomes de funções. A busca vetorial encontra sinônimos e correspondências conceituais em terminologias diferentes. A Reciprocal Rank Fusion (RRF) combina ambas sem exigir calibração de pontuação. Nenhum método isolado cobre os dois modos de falha. Pesquisas sobre o ranking de passagens do MS MARCO confirmam o padrão: a recuperação hybrid supera de forma consistente cada método usado isoladamente.³ O aprofundamento sobre o recuperador hybrid aborda a matemática do RRF, exemplos práticos com números reais, análise dos modos de falha e uma calculadora interativa de fusão.

O MCP oferece às ferramentas de IA acesso direto ao vault. Os servidores do Model Context Protocol (MCP) expõem o recuperador como uma ferramenta que Claude Code, Codex CLI, Cursor e outras ferramentas de IA podem chamar diretamente. O agente consulta o vault, recebe resultados ranqueados com atribuição da fonte e usa o contexto sem carregar arquivos inteiros. O servidor MCP é uma camada fina em torno do mecanismo de recuperação.

Local-first significa custos zero de API e privacidade total. Toda a stack é executada em uma única máquina: SQLite para armazenamento, Model2Vec para embeddings, FTS5 para busca por palavras-chave, sqlite-vec para KNN vetorial. Sem serviços em nuvem, chamadas de API ou dependência de rede. Notas pessoais nunca saem da máquina. A re-incorporação completa dos 49.746 chunks custaria aproximadamente US$ 0,30 pelos preços de API da OpenAI, mas os custos reais são latência, exposição da privacidade e dependência de rede para um sistema que deveria funcionar offline.⁴

A indexação incremental mantém o sistema atualizado em menos de 10 segundos. A comparação do horário de modificação dos arquivos detecta alterações. Apenas arquivos modificados passam novamente por chunking e geração de embeddings. Uma reindexação completa leva cerca de quatro minutos em hardware Apple M-series. Atualizações incrementais nas edições de um dia típico são executadas em menos de dez segundos. O sistema se mantém atualizado sem intervenção manual.

A arquitetura escala de 200 a mais de 20.000 notas. O mesmo design de três camadas (entrada, recuperação, integração) funciona em qualquer tamanho de vault. Comece com busca apenas por BM25 em um vault pequeno. Adicione busca vetorial quando colisões de palavras-chave se tornarem um problema. Adicione fusão RRF quando precisar de correspondências exatas e semânticas. Cada camada é útil de forma independente e pode ser removida de forma independente.

Como usar este guia

Este guia aborda o sistema completo. Seu ponto de partida depende de onde você está:

As seções marcadas como Contrato incluem detalhes de implementação, blocos de configuração e modos de falha. As seções marcadas como Narrativa se concentram em conceitos, decisões de arquitetura e no raciocínio por trás das escolhas de design. As seções marcadas como Receita apresentam fluxos de trabalho passo a passo.

Por que usar o Obsidian para infraestrutura de IA

A tese deste guia: os vaults do Obsidian são o melhor substrato para bases de conhecimento pessoais de IA porque são local-first, em texto simples, estruturados como grafos, e o usuário controla cada camada da stack.

O que o Obsidian oferece à IA que as alternativas não oferecem

Arquivos markdown em texto simples. Cada nota é um arquivo .md no seu sistema de arquivos. Sem formato proprietário, exportação de banco de dados ou API necessário para ler o conteúdo. Qualquer ferramenta que lê arquivos pode ler seu vault. grep, ripgrep, o pathlib do Python, SQLite FTS5 — todos funcionam diretamente nos arquivos de origem. Ao criar um sistema de recuperação, você está indexando arquivos, não respostas de API. O índice está sempre consistente com a origem porque a origem é o sistema de arquivos.

Arquitetura local-first. O vault fica na sua máquina. Sem servidor, dependência de sincronização em nuvem, limites de taxa de API ou termos de serviço que regulem como você processa seu próprio conteúdo. Você pode gerar embeddings, indexar, dividir em chunks e pesquisar suas notas sem qualquer serviço externo. Isso importa para a infraestrutura de IA porque o pipeline de recuperação é executado na velocidade permitida pelo seu disco, não na velocidade de resposta de um endpoint de API. Também importa para a privacidade: notas pessoais que contêm credenciais, dados de saúde, informações financeiras e reflexões privadas nunca saem da sua máquina.

Estrutura de grafo por meio de wiki-links. A sintaxe [[wiki-link]] do Obsidian cria um grafo direcionado entre notas. Uma nota sobre a implementação de OAuth se vincula a notas sobre rotação de tokens, gerenciamento de sessões e segurança de API. A estrutura de grafo codifica relações entre conceitos selecionadas por humanos. Embeddings vetoriais capturam similaridade semântica, mas wiki-links capturam conexões intencionais que o autor fez enquanto refletia sobre o tema. O grafo é um sinal que os embeddings não conseguem replicar.

Ecossistema de plugins. O Obsidian tem mais de 2.500 plugins da comunidade (a contagem ultrapassou 2.500 em março de 2026, acima de mais de 1.800 em meados de 2025). O Dataview consulta seu vault como um banco de dados. O Templater gera notas a partir de templates com lógica de JavaScript. A integração com Git sincroniza seu vault com um repositório. O Linter impõe consistência de formatação. O plugin nativo Bases (introduzido na v1.9.10) adiciona visualizações semelhantes a bancos de dados — tabelas, galerias, calendários e quadros kanban — sobre arquivos do vault, usando propriedades de frontmatter como campos e salvas como arquivos .base.¹⁵ Esses plugins adicionam estrutura ao vault sem alterar o formato subjacente de texto simples. O sistema de recuperação indexa a saída desses plugins, não os plugins em si.

Mais de 5 milhões de usuários. O Obsidian tem uma grande comunidade ativa que produz templates, fluxos de trabalho, plugins e documentação. Quando você encontra um problema de organização do vault ou configuração de plugin, alguém provavelmente já documentou uma solução. A comunidade também produz ferramentas adjacentes ao Obsidian: servidores MCP, scripts de indexação, pipelines de publicação e wrappers de API.

O que apenas um sistema de arquivos não oferece

Um diretório de arquivos markdown tem a vantagem do texto simples, mas não tem três coisas que o Obsidian adiciona:

1. Links bidirecionais. O Obsidian rastreia backlinks automaticamente. Quando você cria um link da Nota A para a Nota B, a Nota B mostra que a Nota A faz referência a ela. O painel de grafo visualiza agrupamentos de conexões. Essa percepção bidirecional é metadado que um sistema de arquivos bruto não fornece.

2. Visualização ao vivo com renderização de plugins. Consultas do Dataview, diagramas Mermaid e blocos de callout são renderizados em tempo real. A experiência de escrita é mais rica do que em um editor de texto, enquanto o formato de armazenamento permanece em texto simples. Você escreve e organiza em um ambiente rico; o sistema de recuperação indexa o markdown bruto.

3. Infraestrutura da comunidade. Descoberta de plugins, marketplace de temas, serviço de sincronização (opcional), serviço de publicação (opcional) e um ecossistema de documentação. Você pode reproduzir qualquer recurso individual com ferramentas independentes, mas o Obsidian os reúne em um fluxo de trabalho coeso.

O que o Obsidian NÃO faz (e o que você cria)

O Obsidian não inclui infraestrutura de recuperação. Ele tem busca básica (texto completo, nome de arquivo, tag), mas não tem pipeline de embeddings, busca vetorial, ranking por fusão, servidor MCP, filtragem de credenciais, estratégia de chunking ou hooks de integração para ferramentas externas de IA. Este guia aborda a infraestrutura que você cria sobre o Obsidian. O vault é o substrato. O pipeline de recuperação, o servidor MCP e os hooks de integração são a infraestrutura.

A arquitetura descrita aqui é markdown-first, não exclusiva do Obsidian. Se você usa Logseq, Foam, Dendron ou um diretório simples de arquivos markdown, o pipeline de recuperação funciona de forma idêntica. O chunker lê arquivos .md. O embedder processa strings de texto. O indexador grava no SQLite. Nenhum desses componentes depende de recursos específicos do Obsidian. A contribuição do Obsidian é o ambiente de escrita e organização que produz os arquivos markdown indexados pelo recuperador.

Configuração do Obsidian MCP

Model Context Protocol (MCP) é a interface padrão que dá ao Claude Code, Codex CLI, Cursor e outras ferramentas de IA acesso direto a um vault do Obsidian. Esta seção conecta um vault a uma ferramenta de IA em cinco minutos. Você instalará o Obsidian, criará um vault, instalará um servidor MCP e executará sua primeira consulta. O início rápido usa um servidor MCP da comunidade para resultados imediatos. As seções posteriores abordam a criação de um pipeline de recuperação personalizado para uso em produção.

Pré-requisitos

• macOS, Linux ou Windows
• Node.js 18+ (para o servidor MCP)
• Obsidian 1.12+ (para a integração com CLI; 1.13.7 é a versão pública atual para desktop – as versões estável e beta convergiram, a linha 1.13 saiu do Catalyst em 30 de julho de 2026; versões anteriores funcionam em configurações somente com MCP)
• Claude Code, Codex CLI ou Cursor instalado

Etapa 1: criar um vault

Baixe o Obsidian em obsidian.md e crie um novo vault. Escolha um local de que você se lembrará — o servidor MCP precisa do caminho absoluto.

# Example vault location
~/Documents/knowledge-base/

Adicione algumas notas para dar algo com que o recuperador possa trabalhar. Mesmo 10 a 20 notas já bastam para ver resultados. Cada nota deve ser um arquivo .md com um título significativo e pelo menos um parágrafo de conteúdo.

Etapa 2: instalar um servidor MCP

Vários servidores MCP da comunidade fornecem acesso imediato ao vault. O ecossistema cresceu significativamente entre 2025 e 2026. Um destaque é o MCPVault (npm @bitbonsai/mcpvault, repositório bitbonsai/mcpvault), agora na v0.15.0 (verificado no npm em 14 de agosto de 2026) — um projeto separado de MarkusPfundstein/mcp-obsidian abaixo, não uma renomeação dele. A v0.11.0 (março de 2026) adicionou list_all_tags para analisar frontmatter e hashtags com contagens, melhorou o tratamento de pastas com pontos e incluiu suporte a .base/.canvas. Vale adotar a sequência de três patches lançados no mesmo dia, em 23 de julho de 2026: a v0.12.3 adiciona uma ferramenta wiki_link que resolve as formas [[Document Name]], [[Name|Display]], [[Name\|Display]] com escape de tabela e #fragment, retornando o conteúdo da nota junto com o caminho resolvido e alternativas ambíguas — a primitiva de recuperação que permite que um agente siga o próprio grafo de links do vault, em vez de pesquisá-lo novamente — e exclui .trash/ de todas as ferramentas por meio do filtro de caminhos padrão; a v0.12.4 estende wiki_link a links com caminho qualificado, como [[folder/Note]]; a v0.12.2 impede que patch_note corrompa inserções que contêm padrões de substituição $ e normaliza caminhos que carregam acidentalmente o prefixo do vault. Dois avisos de severidade média (GHSA-9c83-rr99-vfwj e GHSA-j99q-93c9-h869) foram divulgados contra a lista de negação de diretórios restritos do filtro de caminhos; ambos foram corrigidos bem antes da linha 0.12, nas versões 0.11.4 e 0.11.5, portanto qualquer versão 0.12.x está livre deles.¹³

Mudança de abril de 2026 — Obsidian CLI como ponte preferida: o Obsidian 1.12.0 introduziu o CLI de primeira classe, e o instalador público 1.12.7 (23 de março de 2026) incluiu o binário independente + TUI + melhorias no arquivo de socket que facilitaram a instalação e a execução de fluxos de trabalho no terminal.¹⁶ A linha 1.13 chegou ao canal público como 1.13.4 em 30 de julho de 2026 — uma versão de configurações/imagens/segurança de URI, sem novos recursos de IA ou automação além da superfície do CLI 1.12.x (veja a linha do changelog para saber o que ela altera).²⁵²⁶ As ferramentas da comunidade estão migrando ativamente do plugin Local REST API (que alimentava mcp-obsidian) para a integração baseada em CLI, pois ela é mais rápida e estável. O repositório MarkusPfundstein/mcp-obsidian continua mantido — commits até maio de 2026 adicionaram ferramentas como search_by_tag e get_frontmatter — embora não publique releases com tags (instale a partir de um commit fixado). Ele continua baseado em Local REST API; para novas configurações, a ponte CLI costuma ser mais rápida e estável, portanto prefira-a ou as alternativas mais novas da comunidade listadas abaixo.²⁰ Consulte a seção “Obsidian CLI para fluxos de trabalho com IA” mais adiante neste guia para ver a configuração recomendada.

Para o início rápido, a opção mais simples é um servidor baseado em arquivos que lê arquivos .md diretamente. Atenção à colisão de nomes no npm: o servidor baseado em arquivos é o npm obsidian-mcp (StevenStavrakis); o npm obsidian-mcp-server é o servidor da cyanheads, baseado em REST-API, que precisa do plugin Local REST API e de uma chave API — uma confusão comum que deixa leitores com um servidor que não consegue iniciar:

npm install -g obsidian-mcp

Etapa 3: configurar sua ferramenta de IA

Claude Code — registre o servidor com claude mcp add (Claude Code armazena servidores MCP em ~/.claude.json no escopo do usuário ou em .mcp.json de um projeto — não em ~/.claude/settings.json, que ignora silenciosamente um bloco mcpServers):

# User scope (all your projects)
claude mcp add obsidian -s user -- npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/your/vault

# Or project scope, shared with the repo (writes .mcp.json)
claude mcp add obsidian -s project -- npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/your/vault

Codex CLI — adicione a ~/.codex/config.toml:

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/your/vault"]

Cursor — adicione a .cursor/mcp.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/your/vault"]
    }
  }
}

Etapa 4: executar sua primeira consulta

Abra sua ferramenta de IA e faça uma pergunta que as notas do seu vault possam responder:

Search my Obsidian vault for notes about [topic you wrote about]

A ferramenta de IA chama o servidor MCP, que pesquisa seu vault e retorna conteúdo correspondente. Você deve ver resultados com caminhos de arquivo e trechos relevantes.

O que Claude pode fazer depois de conectado

Os nomes exatos das ferramentas variam conforme o servidor, mas a superfície principal de recursos é consistente entre as implementações:

Na prática: Claude responde a perguntas com base nas suas notas e atribuição de fontes, traz decisões anteriores e material de referência para sessões de programação e explora a estrutura do vault sem carregar arquivos inteiros no contexto. Alguns servidores da comunidade também expõem operações de escrita (criação, acréscimo, gerenciamento de tags e frontmatter); o servidor personalizado criado mais adiante neste guia é deliberadamente somente leitura, com a criação de notas feita por hooks.

Aprofundamentos: Arquitetura do servidor MCP para o design de ferramentas e permissões, Integração com Claude Code para hooks e o padrão de ponte, Integração com Codex CLI e Cursor e outras ferramentas para outros agentes.

O que você acabou de criar

Você conectou uma base de conhecimento local a uma ferramenta de IA por meio de um protocolo padrão. O servidor MCP lê os arquivos do seu vault, realiza uma pesquisa básica e retorna resultados. Esta é a versão mínima viável.

O que este início rápido NÃO oferece: - Recuperação hybrid (pesquisa BM25 + vetorial + fusão RRF) - Pesquisa semântica baseada em embeddings - Filtragem de credenciais - Indexação incremental - Injeção automática de contexto baseada em hooks

O restante deste guia aborda a criação de cada um desses recursos. O início rápido comprova o conceito. O pipeline completo oferece recuperação com qualidade de produção.

Obsidian CLI para fluxos de trabalho de AI

O Obsidian 1.12 (fevereiro de 2026) introduziu uma interface de linha de comando integrada que abre uma nova superfície de integração para fluxos de trabalho de AI; ela continua atual até a versão 1.13.7 (a linha 1.13 chegou ao canal público em 30 de julho de 2026; não houve novos recursos do CLI desde então).¹⁶²⁵²⁶ O CLI funciona como um controle remoto para a GUI do Obsidian — o Obsidian precisa estar em execução (ou será iniciado automaticamente no primeiro comando). Ative-o em Settings > General > Command line interface.

Por que o CLI importa para a infraestrutura de AI

O CLI oferece acesso programático a operações nativas do Obsidian que antes exigiam a GUI ou APIs de plugins. Para fluxos de trabalho de AI, os principais recursos são:

• Pesquisa em scripts e hooks. obsidian search "query" e obsidian search:context "query" executam pesquisas no vault a partir de qualquer script de shell, hook ou pipeline de automação. A variante search:context retorna linhas correspondentes com o contexto ao redor, o que é útil para inserir resultados em prompts de AI.
• Automação de notas diárias. obsidian daily abre ou cria a nota diária de hoje. Combinado com scripts de shell, isso permite fluxos de briefing diário automatizados — um hook pode acrescentar resumos gerados por AI à nota diária.
• Criação de notas baseada em templates. obsidian template list e obsidian template create geram notas a partir de templates do Templater ou do núcleo, permitindo que agentes de AI criem entradas estruturadas no vault sem escrever diretamente em arquivos markdown.
• Gerenciamento de propriedades. obsidian property set e obsidian property get leem e gravam propriedades de frontmatter, permitindo atualizações de metadados por scripts sem analisar YAML.
• Controle de plugins. obsidian plugin enable/disable/list gerencia plugins programaticamente, o que é útil para alternar plugins de indexação durante operações em lote.
• Gerenciamento de tarefas. obsidian task list/add/complete oferece acesso estruturado a tarefas, útil para agentes de AI que gerenciam itens de trabalho no vault.

CLI vs MCP para acesso de AI

Os servidores CLI e MCP têm funções diferentes e são complementares, não concorrentes:

Recomendação: Use o CLI para automação de entrada (criação de notas, gerenciamento de propriedades, execução de pesquisa nativa do Obsidian) e o MCP para recuperação (pesquisa hybrid com embeddings). Um hook UserPromptSubmit pode chamar obsidian search:context como uma pré-verificação rápida antes de executar a recuperação hybrid mais pesada (eventos de hook com escopo de ferramenta não podem injetar conteúdo — seu stdout nunca chega ao modelo).

Exemplo: hook de entrada com CLI

#!/bin/bash
# Hook: append today's signals to daily note via CLI
DATE=$(date +%Y-%m-%d)
SUMMARY="$1"
obsidian daily  # ensure daily note exists
obsidian file append "Daily Notes/${DATE}.md" "## AI Summary\n${SUMMARY}"

Plugins de agentes do Obsidian

Uma categoria crescente de plugins do Obsidian incorpora agentes de programação com AI diretamente na UI do vault, oferecendo uma alternativa à configuração de servidor MCP externo. Esses plugins executam o agente de AI na barra lateral do Obsidian, em vez de se conectarem a partir de uma ferramenta externa.

Claudian

Claudian incorpora o Claude Code como colaborador de AI no vault. O diretório do vault torna-se o diretório de trabalho do Claude, concedendo a ele recursos agênticos completos: leitura/gravação de arquivos, pesquisa, comandos Bash e fluxos de trabalho em várias etapas.¹⁷

Principais recursos para a infraestrutura de AI: - Prompts com reconhecimento de contexto. Anexa automaticamente a nota em foco, oferece suporte a menções de arquivo @notename, exclusão baseada em tags e seleção do editor como contexto. - Suporte a visão. Analise imagens por arrastar e soltar, colar ou caminho de arquivo — útil para processar capturas de tela e diagramas armazenados no vault. - Comandos de barra. Crie templates de prompt reutilizáveis acionados por /command, permitindo operações padronizadas no vault. - Modos de permissão. Modos YOLO (aprovação automática), Safe (aprovar cada ação) e Plan (somente planejamento), com uma lista de bloqueio de segurança e confinamento ao vault.

Agent Client

Agent Client reúne Claude Code, Codex CLI e Gemini CLI em uma barra lateral unificada do Obsidian por meio do Agent Client Protocol (ACP).¹⁸

Principais recursos: - Alternância entre vários agentes. Converse com Claude Code, Codex ou Gemini CLI no mesmo painel, alternando entre agentes conforme necessário. - Menções a notas. Use @notename para incluir o conteúdo de notas nos prompts, de forma semelhante ao Claudian, mas sem depender de um agente específico. - Execução de shell. Execute comandos de terminal inline no chat — scripts de build, comandos git ou qualquer operação de terminal sem sair da conversa. - Aprovação de ações. Controle detalhado sobre leituras de arquivos, edições e execuções de comandos.

Quando usar plugins de agentes vs MCP externo

Recomendação: Use plugins de agentes para fluxos de trabalho centrados no vault (escrever, organizar e resumir notas). Use servidores MCP externos para fluxos de desenvolvimento em que o agente de AI precisa do pipeline completo de recuperação e de acesso a codebases fora do vault. As duas abordagens podem coexistir — execute o Claudian dentro do Obsidian para trabalhar com notas e o Claude Code com MCP externamente para desenvolvimento.

Estrutura de decisão: Obsidian vs alternativas

Nem todo caso de uso precisa do Obsidian. Esta seção mapeia quando o Obsidian é o substrato certo, quando é exagero e quando outra opção se encaixa melhor.

Árvore de decisão

START: What is your primary content type?
│
├─ Structured data (tables, records, schemas)
│  → Use a database. SQLite, PostgreSQL, or a spreadsheet.
│  → Obsidian is for prose, not tabular data.
│
├─ Ephemeral context (current project, temporary notes)
│  → Use CLAUDE.md / AGENTS.md in the project repo.
│  → These travel with the code and reset per project.
│
├─ Team wiki (shared documentation, onboarding)
│  → Evaluate Notion, Confluence, or a shared git repo.
│  → Obsidian vaults are personal-first. Team sync is possible
│    but not native.
│
└─ Growing personal knowledge corpus
   │
   ├─ < 50 notes
   │  → A folder of markdown files + grep is sufficient.
   │  → Obsidian adds value mainly through the link graph,
   │    which needs density to be useful.
   │
   ├─ 50 - 500 notes
   │  → Obsidian adds value. Wiki-links create a navigable graph.
   │  → BM25-only search (FTS5) is sufficient at this scale.
   │  → Skip vector search and RRF until keyword collisions appear.
   │
   ├─ 500 - 5,000 notes
   │  → Full hybrid retrieval becomes valuable. Keyword collisions
   │    increase. Semantic search catches queries that BM25 misses.
   │  → Add vector search + RRF fusion at this scale.
   │
   └─ 5,000+ notes
      → Full pipeline is essential. BM25-only returns too much noise.
      → Credential filtering becomes critical (more notes = more
        accidentally pasted secrets).
      → Incremental indexing matters (full reindex takes minutes).
      → MCP integration pays dividends on every AI interaction.

Matriz de comparação

Quando Obsidian é exagero

• Contexto de um único projeto. Se a AI só precisa de contexto sobre o codebase atual, coloque isso em CLAUDE.md, AGENTS.md ou na documentação em nível de projeto. Esses arquivos acompanham o repositório e são carregados automaticamente.
• Dados estruturados. Se o conteúdo é composto por tabelas, registros ou schemas, use um banco de dados. As notas do Obsidian são orientadas a prosa. Dataview consegue consultar campos de frontmatter, mas um banco de dados real lida melhor com consultas estruturadas.
• Pesquisa temporária. Se as notas serão descartadas depois que o projeto acabar, uma pasta de rascunho com arquivos markdown é mais simples. Não crie infraestrutura de retrieval para conteúdo efêmero.

Quando Obsidian é a escolha certa

• Conhecimento acumulado ao longo de meses ou anos. O valor se acumula conforme o corpus cresce. Um vault com 200 notas consultado diariamente por seis meses entrega mais valor do que um vault com 5.000 notas consultado uma única vez.
• Vários domínios em um único corpus. Um vault com notas sobre programação, arquitetura, segurança, design e projetos pessoais se beneficia de retrieval entre domínios que um CLAUDE.md específico de projeto não consegue oferecer.
• Conteúdo sensível à privacidade. Local-first significa que o pipeline de retrieval nunca envia conteúdo para serviços externos. O vault contém tudo o que você coloca nele, inclusive conteúdo que você não enviaria para um serviço de cloud.

Modelo mental: três camadas

O sistema tem três camadas que operam de forma independente, mas se potencializam quando combinadas. Cada camada tem uma preocupação diferente e um modo de falha diferente.

┌─────────────────────────────────────────────────────┐
│                 INTEGRATION LAYER                     │
│  MCP servers, hooks, skills, context injection        │
│  Concern: delivering context to AI tools              │
│  Failure: wrong context, too much context, stale      │
└──────────────────────┬──────────────────────────────┘
                       │ query + ranked results
┌──────────────────────┴──────────────────────────────┐
│                  RETRIEVAL LAYER                      │
│  BM25, vector KNN, RRF fusion, token budget           │
│  Concern: finding the right content for any query     │
│  Failure: wrong ranking, missed results, slow queries │
└──────────────────────┬──────────────────────────────┘
                       │ chunked, embedded, indexed
┌──────────────────────┴──────────────────────────────┐
│                   INTAKE LAYER                        │
│  Note creation, signal triage, vault organization     │
│  Concern: what enters the vault and how it's stored   │
│  Failure: noise, duplicates, missing structure        │
└─────────────────────────────────────────────────────┘

Intake determina o que entra no vault. Sem curadoria, o vault acumula ruído: screenshots de tweets, artigos copiados e colados sem anotação, ideias pela metade sem contexto. A camada de intake é responsável pelo controle de qualidade no ponto de entrada. Um pipeline de pontuação, uma convenção de tags ou um processo de revisão manual — qualquer mecanismo que garanta que o vault contenha conteúdo que vale recuperar.

Retrieval torna o vault consultável. Este é o motor: dividir notas em unidades de busca com chunking, transformar chunks em embeddings no espaço vetorial, indexar para busca por palavras-chave e busca semântica, combinar resultados com RRF. A camada de retrieval transforma uma pasta de arquivos em uma knowledge base consultável. Sem essa camada, o vault pode ser navegado por exploração manual e busca básica, mas não fica programaticamente acessível para ferramentas de AI.

Integração conecta a camada de retrieval às ferramentas de AI. Um servidor MCP expõe retrieval como uma ferramenta chamável. Hooks injetam contexto automaticamente. Skills capturam novo conhecimento de volta no vault. A camada de integração é a interface entre a knowledge base e os agentes de AI que a consomem.

As camadas são desacopladas por design. O pipeline de pontuação de intake não sabe nada sobre embeddings. O retriever não sabe nada sobre regras de roteamento de sinais. O servidor MCP não sabe nada sobre como as notas foram criadas. Esse desacoplamento permite que você melhore qualquer camada de forma independente. Substitua o modelo de embeddings sem alterar o pipeline de intake. Adicione uma nova capacidade MCP sem modificar o retriever. Altere as heurísticas de pontuação de sinais sem tocar no índice.

Arquitetura do vault para consumo por AI

Um vault otimizado para recuperação por AI segue convenções diferentes de um vault otimizado para navegação pessoal. Esta seção aborda a estrutura de pastas, o schema das notas, as convenções de frontmatter e os padrões específicos que melhoram a qualidade da recuperação.

Estrutura de pastas

Use prefixos numéricos para pastas de nível superior para criar uma hierarquia organizacional previsível. Os números não indicam prioridade — eles agrupam domínios relacionados e tornam a estrutura fácil de escanear.

vault/
├── 00-inbox/              # Unsorted captures, pending triage
├── 01-projects/           # Active project notes
├── 02-areas/              # Ongoing areas of responsibility
├── 03-resources/          # Reference material by topic
│   ├── programming/
│   ├── security/
│   ├── ai-engineering/
│   ├── design/
│   └── devops/
├── 04-archive/            # Completed projects, old references
├── 05-signals/            # Scored signal intake
│   ├── ai-tooling/
│   ├── security/
│   ├── systems/
│   └── ...12 domain folders
├── 06-daily/              # Daily notes (if used)
├── 07-templates/          # Note templates (excluded from index)
├── 08-attachments/        # Images, PDFs (excluded from index)
├── .obsidian/             # Obsidian config (excluded from index)
└── .indexignore            # Paths to exclude from retrieval index

Pastas que devem ser indexadas: Tudo que contém prosa em markdown — projetos, áreas, recursos, sinais, notas diárias.

Pastas que devem ser excluídas da indexação: Templates (eles contêm variáveis de placeholder, não conteúdo), anexos (arquivos binários), configuração do Obsidian e qualquer pasta com conteúdo sensível que você não quer no índice de recuperação.

O arquivo .indexignore

Crie um arquivo .indexignore na raiz do vault para excluir caminhos explicitamente do índice de recuperação. A sintaxe corresponde à do .gitignore:

# Obsidian internal
.obsidian/

# Templates contain placeholders, not content
07-templates/

# Binary attachments
08-attachments/

# Personal health/medical notes
02-areas/health/

# Financial records
02-areas/finance/personal/

# Career documents (resumes, salary data)
02-areas/career/private/

O indexador lê esse arquivo antes de escanear e ignora completamente os caminhos correspondentes. Arquivos em caminhos excluídos nunca passam por chunking, nunca recebem embeddings e nunca aparecem nos resultados de busca.

Schema das notas

Toda nota deve ter frontmatter YAML. O recuperador usa campos de frontmatter para filtragem e enriquecimento de contexto:

---
title: "OAuth Token Rotation Patterns"
type: note           # note | signal | project | moc | daily
domain: security     # primary domain for routing
tags:
  - authentication
  - oauth
  - token-management
created: 2026-01-15
updated: 2026-02-28
source: ""           # URL if captured from external source
status: active       # active | archived | draft
---

Campos obrigatórios para recuperação:

• title — Usado na exibição dos resultados de busca e no contexto de heading para BM25
• type — Permite consultas filtradas por tipo (“mostre apenas MOCs” ou “apenas sinais”)
• tags — Indexado no contexto de heading do FTS5 com peso 0,3, fornecendo correspondências de palavra-chave mesmo quando o corpo usa terminologia diferente

Campos opcionais, mas valiosos:

• domain — Permite consultas com escopo por domínio (“busque apenas notas de segurança”)
• source — Atribuição para conteúdo capturado; o recuperador pode incluir URLs de origem nos resultados
• status — Permite excluir notas arquivadas ou em rascunho da busca ativa

Convenções de chunking

O recuperador divide o conteúdo em chunks nos limites de headings H2 (##). Isso significa que a estrutura das suas notas afeta diretamente a granularidade da recuperação:

Bom para recuperação:

## Token Rotation Strategy

The rotation interval depends on the threat model...

## Implementation with refresh_token

The OAuth 2.0 refresh token flow requires...

## Error Handling: Expired Tokens

When a token expires mid-request...

Três seções H2 produzem três chunks pesquisáveis de forma independente. Cada chunk tem contexto suficiente para que o embedding capture seu significado. Uma consulta sobre “expired token handling” corresponde especificamente ao terceiro chunk.

Ruim para recuperação:

# OAuth Notes

Token rotation depends on threat model. The OAuth 2.0 refresh
token flow requires storing the refresh token securely. When a
token expires mid-request, the client should retry after refresh.
The rotation interval is typically 15-30 minutes for access tokens
and 7-30 days for refresh tokens...

Uma seção longa sem headings H2 produz um único chunk grande. O embedding faz uma média entre todos os tópicos da seção. Uma consulta sobre qualquer subtópico corresponde igualmente à nota inteira.

Regra prática: Se uma seção cobre mais de um conceito, divida-a em subseções H2. O chunker cuida do resto.

O que não colocar nas notas

Conteúdo que degrada a qualidade da recuperação:

• Copiar e colar artigos inteiros sem anotação. O recuperador indexa as palavras-chave do artigo original, diluindo seu vault com conteúdo que você não escreveu. Em vez disso, adicione um resumo, extraia os pontos principais ou crie um link para a URL de origem.
• Screenshots sem descrição em texto. O recuperador indexa texto em markdown. Uma imagem sem alt text ou descrição ao redor fica invisível tanto para BM25 quanto para busca vetorial.
• Strings de credenciais. Chaves API, tokens, senhas, strings de conexão. Mesmo com filtragem de credenciais, a abordagem mais segura é nunca colar secrets nas notas. Em vez disso, referencie-os pelo nome (“o token Cloudflare API em ~/.env”).
• Conteúdo gerado automaticamente sem curadoria. Se uma ferramenta gera uma nota (transcrição de reunião, destaques do Readwise, importação de RSS), revise e anote antes que ela entre no vault permanente. Importações automáticas sem curadoria adicionam volume sem acrescentar valor recuperável.

Ecossistema de plugins para workflows de AI

Plugins do Obsidian que melhoram a qualidade do vault para recuperação por AI se dividem em três categorias: estruturais (impõem consistência), consulta (expõem metadados) e sync (mantêm o vault atualizado).

Plugins essenciais

Dataview. Consulta seu vault como um banco de dados usando campos de frontmatter. Crie índices dinâmicos: “todas as notas marcadas com security atualizadas nos últimos 30 dias” ou “todas as notas de projeto com status active.” O Dataview não ajuda diretamente na recuperação, mas ajuda você a identificar lacunas na cobertura do seu vault e encontrar notas que precisam ser atualizadas.

TABLE type, domain, updated
FROM "03-resources"
WHERE status = "active"
SORT updated DESC
LIMIT 20

Templater. Cria notas a partir de templates com campos dinâmicos. Garanta que toda nova nota comece com o frontmatter correto usando um template que preenche previamente os campos created, type e domain. Um frontmatter consistente melhora a filtragem de recuperação.

<%* /* New Resource Note Template */ %>
---
title: "<% tp.file.cursor() %>"
type: note
domain: <% tp.system.suggester(["programming", "security", "ai-engineering", "design", "devops"], ["programming", "security", "ai-engineering", "design", "devops"]) %>
tags: []
created: <% tp.date.now("YYYY-MM-DD") %>
updated: <% tp.date.now("YYYY-MM-DD") %>
source: ""
status: active
---

## Key Points

## Details

## References

Linter. Impõe regras de formatação em todo o vault. Uma hierarquia de títulos consistente (H1 para título, H2 para seções, H3 para subseções) garante que o chunker produza resultados previsíveis. Regras do Linter que importam para recuperação:

• Incremento de títulos: impor níveis de título sequenciais (sem pular de H1 para H3)
• Título YAML: corresponder ao nome do arquivo
• Espaços finais: remover (evita artefatos de tokenização do FTS5)
• Linhas em branco consecutivas: limitar a 1 (chunks mais limpos)

Git integration. Controle de versão para o seu vault. Acompanhe alterações ao longo do tempo, sincronize entre máquinas e recupere exclusões acidentais. O Git também fornece dados de mtime que o indexador usa para detecção incremental de alterações.

Plugins que ajudam a indexação

Smart Connections. Um plugin do Obsidian que oferece busca semântica com AI dentro do próprio Obsidian. O Smart Connections v4 cria embeddings locais por padrão — depois que seu vault é indexado, conexões semânticas e consultas funcionam totalmente offline, sem chamadas API.¹¹ v4.5.0 (5 de maio de 2026) torna as conexões de rodapé parte do Smart Connections Core, então toda instalação pode mostrar conexões de notas relacionadas no rodapé sem abrir um painel lateral. Versões recentes da v4 também adicionaram visualizações em grafo para listas de conexões, locais de dock configuráveis, melhor recuperação de block-embedding após execuções de indexação interrompidas e “Substrate”, um ambiente entre plugins que permite que Smart Connections, Smart Chat e Smart Composer compartilhem estado.²¹ Embora o sistema de recuperação deste guia seja externo ao Obsidian (executado como um pipeline Python), o Smart Connections é útil para explorar relações semânticas enquanto você escreve. Os dois sistemas indexam o mesmo conteúdo, mas atendem a casos de uso diferentes: Smart Connections para descoberta dentro do editor, o recuperador externo para integração com ferramentas de AI via MCP.

Plugins AI-native lançados em abril de 2026. Uma onda de novos plugins da comunidade mira diretamente o workflow Claude Code / Codex / Gemini-CLI:

Trate isso como uma área emergente — vários desses plugins provavelmente serão consolidados ou absorvidos pelo Smart Connections / núcleo do Obsidian nos próximos trimestres. Se você está escolhendo um hoje, VaultSearch e Hybrid Search MCP são os mais próximos, em filosofia, do recuperador externo deste guia.

Nota sobre Dataview: O Dataview (o plugin de consulta antigo do Obsidian) lançou a versão 0.5.70 pela última vez em abril de 2025 e está efetivamente parado desde então. Para novos trabalhos, o recurso integrado Bases do Obsidian (1.9+) é o sucessor implícito e o caminho recomendado.

Metadata Menu. Oferece edição estruturada de frontmatter com autocomplete para valores de campos. Reduz erros de digitação nos campos type, domain e tags. Metadados consistentes melhoram a precisão da filtragem de recuperação.

Plugins que prejudicam a indexação

Excalidraw. Armazena desenhos como JSON incorporado em arquivos markdown. O JSON é markdown sintaticamente válido, mas produz lixo quando dividido em chunks e incorporado. Exclua arquivos do Excalidraw do índice via .indexignore ou filtre por extensão de arquivo.

Kanban. Armazena o estado do quadro como markdown com formatação especial. O formato foi projetado para renderização de Kanban, não para recuperação de prosa. O chunker produz fragmentos de títulos de cartões e metadados que não geram bons embeddings. Exclua quadros Kanban do índice.

Calendar. Cria notas diárias com conteúdo mínimo (geralmente apenas um cabeçalho de data). Notas vazias ou quase vazias produzem chunks de baixa qualidade. Se você usa notas diárias, escreva conteúdo substancial nelas ou exclua a pasta de notas diárias do índice.

Configuração de plugins que importa

File recovery → Enabled. Protege contra exclusão acidental de notas. Não está diretamente relacionado à recuperação, mas é essencial para uma base de conhecimento da qual você depende.

Strict line breaks → Disabled. Quebras de linha padrão do Markdown (linha em branco dupla para parágrafo) produzem chunks mais limpos do que o modo strict do Obsidian (linha nova única para <br>).

Default new file location → Designated folder. Direcione novos arquivos para 00-inbox/ para que notas sem categoria não poluam pastas de domínio. A inbox é uma área de preparação; os arquivos passam para pastas de domínio após triagem.

Wiki-link format → Shortest path when possible. Alvos de link mais curtos são mais fáceis para o recuperador resolver ao indexar a estrutura de links.

Modelos de embeddings: escolha e configuração

O modelo de embeddings converte chunks de texto em vetores numéricos para busca semântica. A escolha do modelo determina a qualidade da recuperação, o tamanho do índice, a velocidade de geração dos embeddings e as dependências em runtime. Esta seção explica por que o potion-base-8M da Model2Vec é a escolha padrão e quando escolher alternativas.

Por que Model2Vec potion-base-8M

Modelo: minishlab/potion-base-8M Parâmetros: 7,6 milhões Dimensões: 256 Tamanho: ~30 MB Dependências: model2vec (somente numpy, sem PyTorch) Inferência: somente CPU, embeddings estáticos de palavras (sem camadas de atenção)

Model2Vec destila o conhecimento de um sentence transformer em embeddings estáticos de tokens. Em vez de executar camadas de atenção sobre a entrada (como BERT, MiniLM e outros modelos transformer fazem), Model2Vec produz vetores por meio de uma média ponderada de embeddings de tokens pré-computados.⁵ A consequência prática: a velocidade de geração dos embeddings é 50-500x maior que a de modelos baseados em transformers, porque não há computação sequencial.

Na página atual de resultados da Model2Vec, potion-base-8M atinge cerca de 92% da pontuação all-task do all-MiniLM-L6-v2 (51,32 vs 55,80), mantendo-se ordens de grandeza mais rápido.⁶ A diferença restante de qualidade é o trade-off pelas vantagens de velocidade e simplicidade. Para chunks curtos de markdown (em média 200-400 palavras em um vault típico), a diferença de qualidade é menos perceptível do que em documentos mais longos, porque os dois modelos convergem para representações semelhantes em textos curtos e focados.

Configuração

# embedder.py
DEFAULT_MODEL = "minishlab/potion-base-8M"
EMBEDDING_DIM = 256

class Model2VecEmbedder:
    def __init__(self, model_name=DEFAULT_MODEL):
        self._model_name = model_name
        self._model = None

    def _ensure_model(self):
        if self._model is not None:
            return
        _activate_venv()  # Add isolated venv to sys.path
        from model2vec import StaticModel
        self._model = StaticModel.from_pretrained(self._model_name)

    def embed_batch(self, texts):
        self._ensure_model()
        vecs = self._model.encode(texts)
        return [v.tolist() for v in vecs]

Carregamento lazy. O modelo é carregado no primeiro uso, não no momento da importação. Importar o módulo do embedder não tem custo quando o retriever opera no modo de fallback somente BM25 (por exemplo, quando a venv de embeddings não está instalada).

Ambiente virtual isolado. O modelo roda em uma venv dedicada (por exemplo, ~/.claude/venvs/memory/) para evitar conflitos de dependências com o restante da toolchain. A função _activate_venv() adiciona o site-packages da venv ao sys.path em runtime.

# Create isolated venv
python3 -m venv ~/.claude/venvs/memory
~/.claude/venvs/memory/bin/pip install model2vec

Processamento em lotes. O embedder processa textos em lotes de 64 para amortizar o overhead da Model2Vec. O indexador envia chunks para embed_batch() em vez de gerar o embedding de um chunk por vez.

Quando escolher alternativas

Escolha potion-base-32M quando você quiser melhor qualidade do que potion-base-8M sem sair da família de embeddings estáticos. Ele usa um vocabulário maior destilado de baai/bge-base-en-v1.5, alcançando uma pontuação all-task de 52,83 (cerca de 3% acima do potion-base-8M), mantendo a mesma saída de 256 dimensões e dependência somente de numpy.⁸ O arquivo do modelo 4x maior aumenta o uso de memória, mas a velocidade de geração de embeddings continua ordens de grandeza mais rápida que a de modelos transformer.

Escolha potion-retrieval-32M quando seu caso de uso principal for recuperação (que é o caso da busca no vault). Esta variante é ajustada a partir do potion-base-32M especificamente para tarefas de retrieval, com pontuação de 35,06 na tabela de benchmark de retrieval da Model2Vec contra 32,67 do potion-base-32M.⁸ O trade-off é que ele é otimizado para recuperação, não para qualidade de embeddings de uso geral.

Escolha potion-multilingual-128M quando seu vault contiver notas em vários idiomas. Lançado em maio de 2025, este modelo de 101 idiomas é o modelo de embeddings estáticos com melhor desempenho para tarefas multilíngues, gerando embeddings para qualquer texto em qualquer idioma e mantendo a mesma dependência somente de numpy dos outros modelos potion.¹² O arquivo maior do modelo (~500 MB) é o trade-off pela capacidade multilíngue. Use isso quando você tiver notas em japonês, chinês, alemão ou outros idiomas além do inglês junto com conteúdo em inglês.

Escolha all-MiniLM-L6-v2 quando a qualidade da recuperação for mais importante que a velocidade e você tiver PyTorch instalado. Os vetores de 384 dimensões aumentam o tamanho do banco de dados SQLite em ~50% em comparação com vetores de 256 dimensões. A velocidade de geração dos embeddings cai de <1 minuto para ~10 minutos em uma reindexação completa de 15.000 arquivos em hardware M-series.

Escolha nomic-embed-text-v1.5 quando você precisar da melhor qualidade possível de recuperação local e aceitar uma indexação mais lenta. Os vetores de 768 dimensões aproximadamente triplicam o tamanho do banco de dados. Requer PyTorch e uma CPU moderna ou GPU.

Escolha text-embedding-3-small quando latência de rede e privacidade forem trade-offs aceitáveis. O API produz os embeddings de maior qualidade, mas introduz uma dependência de cloud, custo por token (US$ 0,02/milhão de tokens) e envia seu conteúdo para os servidores da OpenAI.

Fique com potion-base-8M em todos os outros casos. A vantagem de velocidade é crítica para indexação iterativa (reindexar durante o desenvolvimento), a dependência somente de numpy evita a complexidade de instalação do PyTorch, e os vetores de 256 dimensões mantêm o banco de dados compacto.

Quantização e redução de dimensionalidade

Model2Vec v0.5.0+ oferece suporte ao carregamento de modelos com precisão e dimensões reduzidas.⁸ Isso é útil para deploy em hardware limitado ou para reduzir o tamanho do banco de dados sem trocar de modelo:

from model2vec import StaticModel

# Load with int8 quantization (25% of original size)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", quantize=True)

# Load with reduced dimensions (e.g., 128 instead of 256)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", dimensionality=128)

Modelos quantizados mantêm qualidade de recuperação quase idêntica com uma fração do uso de memória. A redução de dimensionalidade segue uma truncagem no estilo Matryoshka — as primeiras N dimensões carregam a maior parte das informações. Reduzir de 256 para 128 dimensões corta pela metade o armazenamento dos vetores, com perda mínima de qualidade para recuperação de textos curtos.

Model2Vec v0.8.x atualiza os internos de tokenizer/persistência, descontinua o suporte a Python 3.9 e atualiza os resultados publicados para as tabelas MTEB mais recentes. Fixe a versão ou teste model2vec antes de atualizar um indexador de produção, porque upgrades da biblioteca podem alterar caminhos de carregamento de modelos mesmo quando o nome do modelo de embeddings permanece igual.¹⁰

Fine-tuning para embeddings específicos do vault

Model2Vec v0.4.0+ oferece suporte ao treinamento de modelos de classificação personalizados sobre embeddings estáticos, v0.7.0 adiciona quantização de vocabulário e pooling configurável para destilação, e v0.8.x refatora o comportamento de tokenizer e persistência.¹⁰ Isso é relevante para vaults com vocabulário especializado (notas médicas, referências jurídicas, jargão específico de domínio), em que os modelos potion padrão podem não capturar nuances semânticas:

from model2vec import StaticModel
from model2vec.train import train_model

# Fine-tune on vault-specific data
model = StaticModel.from_pretrained("minishlab/potion-base-8M")
trained_model = train_model(model, train_texts, train_labels)
trained_model.save_pretrained("./vault-embeddings")

Para a maioria dos vaults, o potion-base-8M padrão produz qualidade de recuperação suficiente. Fine-tuning só vale a pena quando a recuperação deixa de encontrar de forma consistente conexões específicas do domínio que um modelo de uso geral não consegue capturar.

Rastreamento de hash do modelo

O indexador armazena um hash derivado do nome do modelo e do tamanho do vocabulário. Se você alterar o modelo de embeddings, o indexador detecta a incompatibilidade na próxima execução incremental e dispara automaticamente uma reindexação completa.

def _compute_model_hash(self):
    """Hash model name + vocab size for compatibility tracking."""
    key = f"{self._model_name}:{self._model.vocab_size}"
    return hashlib.sha256(key.encode()).hexdigest()[:16]

Isso evita misturar vetores de modelos diferentes no mesmo banco de dados, o que produziria pontuações sem sentido de cosine similarity.

Modos de falha

Falha no download do modelo. A primeira execução baixa o modelo do Hugging Face. Se o download falhar (problema de rede, firewall corporativo), o retriever usa fallback para o modo somente BM25. O modelo fica em cache local depois do primeiro download.

Incompatibilidade de dimensões. Se você trocar de modelo sem limpar o banco de dados, os vetores armazenados terão uma dimensão diferente dos novos embeddings. O indexador detecta isso por meio do hash do modelo e dispara uma reindexação completa. Se a verificação de hash falhar (modelo personalizado sem hash adequado), sqlite-vec gerará erro em consultas KNN com dimensões incompatíveis.

Pressão de memória em vaults grandes. Gerar embeddings para mais de 50.000 chunks em um único lote pode consumir muita memória. O indexador processa em lotes de 64 para limitar o pico de uso de memória. Se a memória ainda for um problema, reduza o tamanho do lote.

Pesquisa de texto completo com FTS5

A extensão FTS5 do SQLite oferece pesquisa de texto completo com ranqueamento BM25. FTS5 é o componente de pesquisa por palavra-chave do pipeline de recuperação hybrid. Esta seção aborda a configuração do FTS5, quando o BM25 se destaca e seus modos de falha específicos.

Tabela virtual FTS5

CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text,
    section,
    heading_context,
    content=chunks,
    content_rowid=id
);

Modo de sincronização de conteúdo. O parâmetro content=chunks informa ao FTS5 para referenciar a tabela chunks diretamente, em vez de armazenar uma cópia duplicada do texto. Isso reduz pela metade o requisito de armazenamento, mas significa que o FTS5 precisa ser sincronizado manualmente quando chunks são inseridos, atualizados ou excluídos.

Colunas. Três colunas são indexadas: - chunk_text — O conteúdo principal de cada chunk (peso BM25: 1,0) - section — O texto do cabeçalho H2 (peso BM25: 0,5) - heading_context — Título da nota, tags e metadados (peso BM25: 0,3)

Ranqueamento BM25

O BM25 ranqueia documentos por frequência de termos, frequência inversa de documentos e normalização do tamanho do documento. A função auxiliar bm25() no FTS5 aceita pesos por coluna:

SELECT
    c.id, c.file_path, c.section, c.chunk_text,
    bm25(chunks_fts, 1.0, 0.5, 0.3) AS score
FROM chunks_fts
JOIN chunks c ON chunks_fts.rowid = c.id
WHERE chunks_fts MATCH ?
ORDER BY score
LIMIT 30;

Os pesos das colunas (1,0, 0,5, 0,3) significam: - Uma correspondência de palavra-chave em chunk_text contribui mais para a pontuação - Uma correspondência em section (cabeçalho) contribui metade disso - Uma correspondência em heading_context (título, tags) contribui 30% disso

Esses pesos são ajustáveis. Se o seu vault tiver cabeçalhos descritivos que preveem fortemente a qualidade do conteúdo, aumente o peso de section. Se suas tags forem abrangentes e precisas, aumente o peso de heading_context.

Quando o BM25 vence

O BM25 se destaca em consultas que contêm identificadores exatos:

• Nomes de funções: _rrf_fuse, embed_batch, get_stale_files
• flags de CLI: --incremental, --vault, --model
• Chaves de configuração: bm25_weight, max_tokens, batch_size
• Mensagens de erro: SQLITE_LOCKED, ConnectionRefusedError
• Termos técnicos específicos: PostToolUse, PreToolUse, AGENTS.md

Para essas consultas, o BM25 encontra a correspondência exata imediatamente. A pesquisa vetorial retornaria conteúdo semanticamente relacionado, mas poderia ranquear a correspondência exata abaixo de uma discussão conceitual.

Quando o BM25 falha

O BM25 falha em consultas que usam terminologia diferente do conteúdo armazenado:

• Consulta: “como lidar com falhas de autenticação” → O vault contém notas sobre “recuperação de erro de login” e “tratamento de expiração de sessão”. O BM25 não encontra correspondência porque as palavras-chave são diferentes.
• Consulta: “qual é a melhor forma de gerenciar estado” → O vault contém notas sobre “padrões de Redux store” e “context providers”. O BM25 não encontra porque “gerenciamento de estado” é expresso por nomes de tecnologias específicas.

O BM25 também falha com colisão de palavras-chave em escala. Em um vault com 15.000 arquivos, uma pesquisa por “configuração” corresponde a centenas de notas porque quase toda nota de projeto menciona configuração. Os resultados estão tecnicamente corretos, mas são praticamente inúteis — o ranqueamento não consegue determinar qual nota de “configuração” é relevante para a consulta atual.

Tokenizer do FTS5

O FTS5 usa o tokenizer unicode61 por padrão, que lida com texto ASCII e Unicode. Para vaults com conteúdo CJK (chinês, japonês, coreano) significativo, considere o tokenizer trigram:

-- For CJK-heavy vaults
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id,
    tokenize='trigram'
);

O tokenizer padrão unicode61 divide o texto nos limites das palavras, o que funciona mal para idiomas sem espaços entre palavras. O tokenizer trigram divide a cada três caracteres, permitindo correspondência por substring ao custo do tamanho do índice (aproximadamente 3x maior).

Manutenção

O FTS5 exige sincronização explícita quando a tabela chunks subjacente muda:

# After inserting chunks
cursor.execute("""
    INSERT INTO chunks_fts(chunks_fts)
    VALUES('rebuild')
""")

O comando rebuild reconstrói o índice FTS5 a partir da tabela de conteúdo. Execute-o após inserções em massa (reindexação completa), mas não após atualizações incrementais individuais — para essas, use INSERT INTO chunks_fts(rowid, chunk_text, section, heading_context) para sincronizar linhas individuais.

Pesquisa vetorial com sqlite-vec

A extensão sqlite-vec traz a busca vetorial KNN (K-Nearest Neighbors) para o SQLite. Esta seção cobre a configuração do sqlite-vec, o pipeline de embedding da nota até o vetor pesquisável e os padrões específicos de consulta.

Tabela virtual sqlite-vec

CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

O módulo vec0 armazena vetores float de 256 dimensões como dados binários compactados. A coluna id mapeia 1:1 para a tabela chunks, permitindo joins entre resultados vetoriais e metadados de chunks.

Pipeline de embedding

O pipeline vai da nota até o vetor pesquisável:

Note (.md file)
  → Chunker: split at H2 boundaries
    → Chunks (30-2000 chars each)
      → Credential filter: scrub secrets
        → Embedder: Model2Vec encode
          → Vectors (256-dim float arrays)
            → sqlite-vec: store as packed binary
              → Ready for KNN queries

Serialização vetorial

O módulo struct do Python serializa vetores float para armazenamento no sqlite-vec:

import struct

def _serialize_vector(vec):
    """Pack float list into binary for sqlite-vec."""
    return struct.pack(f"{len(vec)}f", *vec)

def _deserialize_vector(blob, dim=256):
    """Unpack binary blob to float list."""
    return list(struct.unpack(f"{dim}f", blob))

Consulta KNN

Uma consulta de busca vetorial gera um embedding da consulta de entrada e depois encontra os K chunks mais próximos por distância de cosseno:

def _vector_search(self, query_text, limit=30):
    query_vec = self.embedder.embed_batch([query_text])[0]
    packed = _serialize_vector(query_vec)

    results = self.db.execute("""
        SELECT
            cv.id,
            cv.distance,
            c.file_path,
            c.section,
            c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
        ORDER BY distance
    """, [packed, limit]).fetchall()

    return results

O operador MATCH no sqlite-vec executa busca aproximada de vizinhos mais próximos. O parâmetro k controla quantos resultados retornar. A coluna distance contém a distância de cosseno (0 = idêntico, 2 = oposto).

Paginação KNN com restrições de distância

A partir do sqlite-vec v0.1.7, consultas KNN têm suporte a restrições WHERE distance < ?, permitindo paginação baseada em cursor em grandes conjuntos de resultados sem reescanear páginas anteriores.¹⁴ As versões estáveis posteriores v0.1.8 e v0.1.9 são releases de empacotamento e correções de bugs de DELETE, não releases com novo modelo de consulta, então a v0.1.7 continua sendo o limite de recurso para esse padrão de paginação.²³

No horizonte, a linha v0.1.10-alpha (31 de março a 18 de maio de 2026) é a primeira a levar o sqlite-vec além do KNN de força bruta: ela introduz tipos de índice de vizinho mais próximo aproximado — rescore, um índice experimental ivf (inverted-file) que não vem habilitado por padrão, e um índice DiskANN baseado em disco para cofres grandes demais para manter vetores residentes em memória.²³ Isso mudaria a história de escalabilidade para cofres muito grandes, mas a linha 0.1.10 ainda está em pré-release (alpha) — trate a indexação ANN como experimental e continue construindo sobre o caminho KNN de força bruta estável da v0.1.9 para cofres de produção até que uma versão estável 0.1.10 seja lançada.

def _paginated_vector_search(self, query_vec, page_size=20, max_distance=None):
    """Paginate through KNN results using distance constraints."""
    packed = _serialize_vector(query_vec)
    constraint = f"AND distance < {max_distance}" if max_distance else ""

    results = self.db.execute(f"""
        SELECT cv.id, cv.distance, c.file_path, c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
            {constraint}
        ORDER BY distance
    """, [packed, page_size]).fetchall()

    # Use last result's distance as cursor for next page
    next_cursor = results[-1][1] if results else None
    return results, next_cursor

Isso substitui o padrão anterior de buscar um k grande e fatiar no Python, reduzindo o uso de memória em consultas exploratórias sobre cofres grandes.

Suporte a DELETE em tabelas vec0

O sqlite-vec v0.1.7 adicionou suporte nativo a DELETE para tabelas virtuais vec0, e a v0.1.9 corrigiu um caminho de erro de DELETE envolvendo colunas de texto de metadados com mais de 12 caracteres.¹⁴²³ Antes, remover vetores exigia descartar e recriar a tabela. Agora, o caminho de remoção de arquivos do indexador pode excluir vetores diretamente:

# Before v0.1.7: required workaround (drop + recreate, or mark as inactive)
# After v0.1.7: direct DELETE works
db.execute("DELETE FROM chunk_vecs WHERE id = ?", [chunk_id])

Isso simplifica a reindexação incremental quando notas são excluídas ou movidas. O indexador não precisa mais manter uma tabela paralela de “IDs ativos” nem rebuilds em lote.

Quando a busca vetorial vence

A busca vetorial se destaca em consultas nas quais o conceito importa mais do que as palavras específicas:

• Consulta: “como lidar com falhas de autenticação” → Encontra notas sobre “recuperação de erro de login” (mesmo espaço semântico, palavras-chave diferentes)
• Consulta: “quais padrões existem para caching” → Encontra notas sobre “memoization”, “estratégias de Redis TTL” e “HTTP cache headers” (conceitos relacionados, terminologia diversa)
• Consulta: “abordagens para testar código assíncrono” → Encontra notas sobre “fixtures pytest-asyncio”, “mock event loops” e “async test patterns” (mesmo conceito expresso por detalhes de implementação)

Quando a busca vetorial falha

A busca vetorial tem dificuldade com identificadores exatos:

• Consulta: _rrf_fuse → Retorna notas sobre “fusion algorithms” e “rank merging”, mas pode ranquear a definição real da função abaixo de discussões conceituais
• Consulta: PostToolUse → Retorna notas sobre “tool lifecycle hooks” e “post-execution handlers” em vez do nome específico do hook

A busca vetorial também tem dificuldade com dados estruturados. Arquivos de configuração JSON, blocos YAML e snippets de código produzem embeddings que capturam padrões estruturais em vez de significado semântico. Um arquivo JSON com "review": true gera um embedding diferente de uma discussão em prosa sobre code review.

Degradação suave

Se o sqlite-vec não carregar (extensão ausente, plataforma incompatível, biblioteca corrompida), o retriever faz fallback para busca apenas com BM25:

class VectorIndex:
    def __init__(self, db_path):
        self.db = sqlite3.connect(db_path)
        self._vec_available = False
        try:
            self.db.enable_load_extension(True)
            self.db.load_extension("vec0")
            self._vec_available = True
        except Exception:
            pass  # BM25-only mode

    @property
    def vec_available(self):
        return self._vec_available

O retriever verifica vec_available antes de tentar consultas vetoriais. Quando desabilitado, todas as buscas usam apenas BM25, e a etapa de fusão RRF é ignorada.

Reciprocal Rank Fusion (RRF)

RRF combina duas listas ranqueadas sem exigir calibração de pontuação. Esta seção aborda o algoritmo, um rastreamento de consulta trabalhado, o ajuste do parâmetro k e por que RRF foi escolhido em vez de alternativas. Para uma calculadora interativa com ranks editáveis, presets de cenário e um explorador visual de arquitetura, veja o mergulho aprofundado no hybrid retriever.

O algoritmo

RRF atribui a cada documento uma pontuação baseada apenas na sua posição de rank em cada lista:

score(d) = Σ (weight_i / (k + rank_i))

Onde: - k é uma constante de suavização (60, seguindo Cormack et al.³) - rank_i é o rank do documento, baseado em 1, na lista de resultados i - weight_i é um multiplicador opcional por lista (padrão 1.0)

Documentos que ficam bem ranqueados em várias listas recebem pontuações fusionadas mais altas. Documentos que aparecem em apenas uma lista recebem uma pontuação dessa única fonte.

Por que RRF em vez de alternativas

Combinação linear ponderada exige calibrar pontuações BM25 contra distâncias de cosine similarity. As pontuações BM25 não têm limite superior e escalam com o tamanho do corpus. As distâncias de cosine similarity são limitadas a [0, 2]. Combiná-las exige normalização, e os parâmetros de normalização dependem do dataset. RRF usa apenas posições de rank, que são sempre números inteiros começando em 1, independentemente do método de pontuação.

Modelos de fusão aprendidos exigem dados de treinamento rotulados — pares de relevância entre consulta e documento. Para uma base de conhecimento pessoal, esses dados de treinamento não existem. Você precisaria julgar manualmente centenas de pares consulta-documento para treinar um modelo útil. RRF funciona sem nenhum dado de treinamento.

Métodos de votação Condorcet (Borda count, Schulze method) são teoricamente elegantes, mas mais complexos de implementar e ajustar. O artigo original de RRF demonstrou que RRF supera métodos Condorcet em dados de avaliação TREC.³

Fusão na prática

Consulta: “how does the review aggregator handle disagreements”

BM25 ranqueia review-aggregator.py na posição 3 (correspondências exatas de palavras-chave em “review,” “aggregator,” “disagreements”), mas coloca dois arquivos de configuração acima (eles correspondem a “review” com mais destaque). A busca vetorial ranqueia o mesmo chunk na posição 1 (correspondência semântica em resolução de conflitos). Após a fusão por RRF:

Chunks que ficam bem ranqueados em ambas as listas sobem para o topo. Chunks que aparecem em apenas uma lista recebem uma pontuação de fonte única e ficam abaixo dos resultados ranqueados em duas listas. A lógica real de resolução de desacordos vence porque os dois métodos a encontraram — BM25 por palavras-chave, busca vetorial por semântica.

Para o rastreamento completo passo a passo com a matemática de RRF por rank, experimente diferentes valores de k na calculadora interativa de RRF.

Implementação

RRF_K = 60

def _rrf_fuse(self, bm25_results, vec_results,
              bm25_weight=1.0, vec_weight=1.0):
    """Fuse BM25 and vector results using Reciprocal Rank Fusion."""
    scores = {}

    for rank, r in enumerate(bm25_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += bm25_weight / (self._rrf_k + rank)
        scores[cid]["bm25_rank"] = rank

    for rank, r in enumerate(vec_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += vec_weight / (self._rrf_k + rank)
        scores[cid]["vec_rank"] = rank

    fused = sorted(
        scores.values(),
        key=lambda x: x["rrf_score"],
        reverse=True,
    )
    return fused

Ajustando k

A constante k controla quanto peso é dado aos resultados mais bem ranqueados em relação aos resultados de rank mais baixo:

• k mais baixo (por exemplo, 10): Os resultados no topo dominam. Rank 1 pontua 1/11 = 0,091, rank 10 pontua 1/20 = 0,050 (diferença de 1,8x). Bom quando você confia que os rankers individuais acertam o resultado principal.
• k padrão (60): Equilibrado. Rank 1 pontua 1/61 = 0,0164, rank 10 pontua 1/70 = 0,0143 (diferença de 1,15x). As diferenças de rank são comprimidas, dando mais peso a aparecer em várias listas.
• k mais alto (por exemplo, 200): Aparecer nas duas listas importa muito mais do que a posição de rank. Rank 1 pontua 1/201, rank 10 pontua 1/210 — quase idêntico. Use quando os rankers individuais produzem rankings ruidosos, mas a concordância entre listas é confiável.

Comece com k=60. O artigo original de RRF encontrou esse valor robusto em diversos datasets TREC. Ajuste apenas depois de medir casos de falha na sua própria distribuição de consultas.

Desempate

Quando dois chunks têm pontuações RRF idênticas (raro, mas possível com o mesmo rank em uma lista e sem aparecer na outra), desfaça empates assim:

1. Prefira chunks que aparecem nas duas listas em vez de chunks que aparecem em apenas uma
2. Entre chunks nas duas listas, prefira aquele com o menor rank combinado
3. Entre chunks em apenas uma lista, prefira aquele com o menor rank nessa lista

O pipeline completo de retrieval

Esta seção acompanha uma consulta da entrada à saída por todo o pipeline: busca BM25, busca vetorial, fusão RRF, truncamento por orçamento de tokens e montagem do contexto.

Fluxo de ponta a ponta

User query: "PostToolUse hook for context compression"
  │
  ├─ BM25 Search (FTS5)
  │    → MATCH "PostToolUse hook context compression"
  │    → Top 30 results ranked by BM25 score
  │    → 12ms
  │
  ├─ Vector Search (sqlite-vec)
  │    → Embed query with Model2Vec
  │    → KNN k=30 on chunk_vecs
  │    → Top 30 results ranked by cosine distance
  │    → 8ms
  │
  └─ RRF Fusion
       → Merge 60 candidates (may overlap)
       → Score by rank position
       → Top 10 results
       → 3ms
       │
       └─ Token Budget
            → Truncate to max_tokens (default 4000)
            → Estimate at 4 chars per token
            → Return results with metadata
            → <1ms

Latência total: ~23ms para um banco de dados com 49.746 chunks em hardware Apple M3 Pro.

A API de search

class HybridRetriever:
    def search(self, query, limit=10, max_tokens=4000,
               bm25_weight=1.0, vec_weight=1.0):
        """
        Search the vault using hybrid BM25 + vector retrieval.

        Args:
            query: Search query text
            limit: Maximum results to return
            max_tokens: Token budget for total result text
            bm25_weight: Weight for BM25 results in RRF
            vec_weight: Weight for vector results in RRF

        Returns:
            List of SearchResult with file_path, section,
            chunk_text, rrf_score, bm25_rank, vec_rank
        """
        # BM25 search
        bm25_results = self._bm25_search(query, limit=30)

        # Vector search (if available)
        if self.index.vec_available:
            vec_results = self._vector_search(query, limit=30)
            fused = self._rrf_fuse(
                bm25_results, vec_results,
                bm25_weight, vec_weight,
            )
        else:
            fused = bm25_results  # BM25-only fallback

        # Token budget truncation
        results = []
        token_count = 0
        for r in fused[:limit]:
            chunk_tokens = len(r["chunk_text"]) // 4
            if token_count + chunk_tokens > max_tokens:
                break
            results.append(r)
            token_count += chunk_tokens

        return results

Truncamento por orçamento de tokens

O parâmetro max_tokens impede que o retriever retorne mais contexto do que a ferramenta de AI consegue usar. A estimativa usa 4 caracteres por token (uma aproximação razoável para prosa em inglês). Os resultados são truncados de forma gulosa: adiciona resultados na ordem do ranking até o orçamento acabar.

Essa é uma estratégia conservadora. Uma abordagem mais sofisticada consideraria as pontuações de qualidade de cada resultado e preferiria resultados mais curtos e de maior qualidade em vez de resultados mais longos e de menor qualidade. A abordagem gulosa é mais simples e funciona bem na prática porque o ranking RRF já ordena os resultados por relevância.

Esquema do banco de dados (completo)

-- Chunk content and metadata
CREATE TABLE chunks (
    id INTEGER PRIMARY KEY,
    file_path TEXT NOT NULL,
    section TEXT NOT NULL,
    chunk_text TEXT NOT NULL,
    heading_context TEXT DEFAULT '',
    mtime_ns INTEGER NOT NULL,
    embedded_at REAL NOT NULL
);

CREATE INDEX idx_chunks_file ON chunks(file_path);
CREATE INDEX idx_chunks_mtime ON chunks(mtime_ns);

-- FTS5 for BM25 search (content-synced to chunks table)
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id
);

-- sqlite-vec for vector KNN search
CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

-- Model metadata for compatibility tracking
CREATE TABLE model_meta (
    key TEXT PRIMARY KEY,
    value TEXT
);

Caminho de degradação gradual

Full pipeline:     BM25 + Vector + RRF  →  Best results
No sqlite-vec:     BM25 only            →  Good results (no semantic)
No model download:  BM25 only            →  Good results (no semantic)
No FTS5:           Vector only           →  Decent results (no keyword)
No database:       Error                 →  Prompt user to run indexer

O retriever verifica os recursos disponíveis na inicialização e adapta sua estratégia de consulta. Um componente ausente reduz a qualidade, mas não causa erros. A única falha crítica é a ausência do arquivo do banco de dados.

Estatísticas de produção

Medido em um vault com 16.894 arquivos, 49.746 chunks, banco de dados SQLite de 83 MB, Apple M3 Pro:

Hashing de conteúdo e detecção de alterações

O indexador precisa saber quais arquivos mudaram desde a última execução do índice. Esta seção cobre o mecanismo de detecção de alterações e a estratégia de hashing.

Comparação de horário de modificação do arquivo

O indexador armazena mtime_ns (horário de modificação do arquivo em nanossegundos) para cada chunk na tabela chunks. Em uma execução incremental, o indexador:

1. Examina o vault em busca de todos os arquivos .md nas pastas permitidas
2. Lê o mtime_ns de cada arquivo a partir do sistema de arquivos
3. Compara com o mtime_ns armazenado no banco de dados
4. Identifica três categorias:
5. Arquivos novos: o path existe no sistema de arquivos, mas não no banco de dados
6. Arquivos alterados: o path existe nos dois, mas o mtime_ns é diferente
7. Arquivos excluídos: o path existe no banco de dados, mas não no sistema de arquivos

def get_stale_files(self, vault_mtimes):
    """Find files whose mtime changed or are new."""
    stored = dict(self.db.execute(
        "SELECT DISTINCT file_path, mtime_ns FROM chunks"
    ).fetchall())

    stale = []
    for path, mtime in vault_mtimes.items():
        if path not in stored or stored[path] != mtime:
            stale.append(path)
    return stale

def get_deleted_files(self, vault_paths):
    """Find files in database that no longer exist in vault."""
    stored_paths = set(r[0] for r in self.db.execute(
        "SELECT DISTINCT file_path FROM chunks"
    ).fetchall())
    return stored_paths - set(vault_paths)

Por que mtime, não hash de conteúdo

O hashing de conteúdo (SHA-256 do conteúdo do arquivo) seria mais confiável do que a comparação por mtime — ele detectaria casos em que um arquivo foi tocado sem alteração (por exemplo, um git checkout restaurando o mtime original). Porém, o hashing exige ler todos os arquivos em cada execução incremental. Para 16.894 arquivos, ler o conteúdo dos arquivos leva de 2 a 3 segundos. Ler mtimes do sistema de arquivos leva <100ms.

O trade-off: a comparação por mtime ocasionalmente dispara a reindexação desnecessária de arquivos inalterados (falsos positivos), mas nunca deixa de detectar alterações reais. Falsos positivos custam algumas chamadas extras de embedding por execução. A diferença de velocidade (100ms vs 3 segundos) torna o mtime a escolha pragmática para um sistema que roda em cada interação com AI.

Como lidar com exclusões

Quando um arquivo é excluído do vault, o indexador remove todos os seus chunks do banco de dados:

def remove_file(self, file_path):
    """Remove all chunks and vectors for a file."""
    chunk_ids = [r[0] for r in self.db.execute(
        "SELECT id FROM chunks WHERE file_path = ?",
        [file_path],
    ).fetchall()]

    for cid in chunk_ids:
        self.db.execute(
            "DELETE FROM chunk_vecs WHERE id = ?", [cid]
        )
    self.db.execute(
        "DELETE FROM chunks WHERE file_path = ?",
        [file_path],
    )

A instrução DELETE FROM chunk_vecs funciona nativamente a partir do sqlite-vec v0.1.7, com uma correção de bug na v0.1.9 para operações DELETE em tabelas vec0 com colunas de texto de metadados mais longas.¹⁴²³ Versões anteriores exigiam workarounds (remover e recriar a tabela virtual, ou manter um conjunto externo de “IDs ativos”). Se você estiver usando uma versão anterior à 0.1.9, atualize antes de depender de exclusões diretas em esquemas com muitos metadados.

Tabelas FTS5 com sincronização de conteúdo exigem exclusão explícita via INSERT INTO chunks_fts(chunks_fts, rowid, ...) VALUES('delete', ?, ...) para cada linha removida. O indexador lida com isso como parte do processo de remoção de arquivos.

Reindex incremental vs completo

O indexador oferece suporte a dois modos: incremental (rápido, para uso diário) e completo (lento, ocasional). Esta seção explica quando usar cada um, as garantias de idempotência e a recuperação de corrupção.

Reindex incremental

Quando usar: Indexação diária depois de editar notas. É o modo padrão.

O que ele faz: 1. Varre o vault em busca de alterações de arquivos (comparação de mtime) 2. Exclui chunks de arquivos removidos 3. Refaz o chunking e os embeddings dos arquivos alterados 4. Insere novos chunks para arquivos novos 5. Sincroniza o índice FTS5

Duração típica: <10 segundos para as edições de um dia em um vault com 16.000 arquivos.

python index_vault.py --incremental

Reindex completo

Quando usar: - Depois de alterar o modelo de embedding (incompatibilidade de hash do modelo detectada) - Depois de uma migração de schema (novas colunas, índices alterados) - Depois de corrupção do banco de dados (falha na verificação de integridade) - Quando a indexação incremental produz resultados inesperados

O que ele faz: 1. Remove todos os dados existentes (chunks, vetores, entradas FTS5) 2. Varre o vault inteiro 3. Faz o chunking de todos os arquivos 4. Gera embeddings de todos os chunks 5. Cria o índice FTS5 do zero

Duração típica: ~4 minutos para 16.894 arquivos no Apple M3 Pro.

python index_vault.py --full

Idempotência

Ambos os modos são idempotentes: executar o mesmo comando duas vezes produz o mesmo resultado. O indexador exclui os chunks existentes de um arquivo antes de inserir novos, então repetir a indexação incremental em um banco de dados já atualizado produz zero alterações. Repetir a indexação completa produz um banco de dados idêntico.

Recuperação de corrupção

Se o banco de dados SQLite for corrompido (queda de energia durante a escrita, erro de disco, processo encerrado no meio de uma transação):

# Check integrity
sqlite3 vectors.db "PRAGMA integrity_check;"

# If corruption detected, full reindex rebuilds from source files
python index_vault.py --full

A fonte da verdade sempre são os arquivos do vault, não o banco de dados. O banco de dados é um artefato derivado que pode ser reconstruído a qualquer momento. Esta é uma propriedade crítica do design: você nunca precisa fazer backup do banco de dados.

A flag --incremental

Quando o indexador roda com --incremental:

1. Verificação do hash do modelo. Compara o hash do modelo armazenado com o modelo atual. Se for diferente, muda automaticamente para o modo de reindex completo e avisa o usuário.
2. Varredura de arquivos. Percorre as pastas permitidas, coleta caminhos de arquivos e mtimes.
3. Detecção de alterações. Compara com os dados armazenados.
4. Processamento em lote. Refaz o chunking e os embeddings dos arquivos alterados em lotes de 64.
5. Relatório de progresso. Imprime a contagem de arquivos processados e o tempo decorrido.
6. Encerramento controlado. Trata SIGINT concluindo o arquivo atual antes de parar.

Filtragem de credenciais e limites de dados

Notas pessoais contêm segredos: chaves API, bearer tokens, strings de conexão de banco de dados, chaves privadas coladas durante sessões de debugging. O filtro de credenciais impede que isso entre no índice de retrieval.

O problema

Uma nota sobre debugging de uma integração OAuth pode conter:

The token was: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
I used this curl command:
  curl -H "Authorization: Bearer sk-ant-api03-abc123..."

Sem filtragem, tanto o JWT quanto a chave API seriam divididos em chunks, transformados em embeddings e armazenados no banco de dados. Uma busca por “authentication” retornaria o chunk contendo segredos reais. Pior, se o retriever enviar resultados para uma ferramenta de AI por meio de MCP, os segredos aparecem na janela de contexto da AI e, potencialmente, nos logs da ferramenta.

Filtragem baseada em padrões

O filtro de credenciais roda em cada chunk antes do armazenamento, fazendo correspondência com 25 padrões específicos de fornecedores, além de padrões genéricos:

Padrões específicos de fornecedores:

Padrões genéricos:

Implementação do filtro

def clean_content(text):
    """Scrub credentials from text before indexing."""
    result = ScanResult(is_clean=True, match_count=0, patterns=[])

    for pattern in CREDENTIAL_PATTERNS:
        matches = pattern.regex.findall(text)
        if matches:
            text = pattern.regex.sub(
                f"[REDACTED:{pattern.name}]", text
            )
            result.is_clean = False
            result.match_count += len(matches)
            result.patterns.append(pattern.name)

    return text, result

Principais escolhas de design:

1. Filtrar antes do embedding. O texto limpo é o que recebe o embedding. A representação vetorial nunca codifica padrões de credenciais. Uma consulta por “chave API” retorna notas que discutem gerenciamento de chaves API, não notas que contêm chaves reais.

2. Substituir, não remover. O token [REDACTED:pattern-name] preserva o contexto semântico do texto ao redor. O embedding captura que “algo parecido com uma credencial estava aqui” sem codificar a credencial em si.

3. Registrar padrões, não valores. O filtro registra quais padrões corresponderam (por exemplo, “Scrubbed 2 credential(s) from oauth-debug.md [jwt, bearer-token]”), mas nunca registra o valor da credencial.

Exclusão baseada em caminho

O arquivo .indexignore oferece exclusão granular ampla por caminho. O filtro de credenciais oferece limpeza granular fina dentro dos arquivos indexados. Ambos são necessários:

• .indexignore para pastas inteiras que você sabe que contêm conteúdo sensível (notas de saúde, registros financeiros, documentos de carreira)
• Filtro de credenciais para segredos acidentalmente incorporados em conteúdo que, de outra forma, poderia ser indexado

Classificação de dados

Para vaults com conteúdo diverso, considere classificar as notas por sensibilidade:

Arquitetura do servidor MCP

Os servidores do Model Context Protocol (MCP) expõem o retriever como uma ferramenta que os agentes de IA podem chamar. Esta seção aborda o design do servidor, a superfície de capacidades e os limites de permissão.

Escolha do protocolo: STDIO vs HTTP

O MCP oferece suporte a dois modos de transporte:

STDIO — A ferramenta de IA inicia o servidor MCP como um processo filho e se comunica por stdin/stdout. Este é o modo padrão para ferramentas locais. Claude Code, Codex CLI e Cursor oferecem suporte a servidores MCP via STDIO.

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/path/to/vault",
        "DB_PATH": "/path/to/vectors.db"
      }
    }
  }
}

HTTP — O servidor MCP é executado como um serviço HTTP independente. Útil para acesso remoto, configurações com vários clientes ou configurações de equipe em que o vault está em um servidor compartilhado.

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Recomendação: Use STDIO para vaults pessoais. É mais simples, mais seguro (sem exposição à rede), e o ciclo de vida do servidor é gerenciado pela ferramenta de IA. Use HTTP somente quando várias ferramentas ou várias máquinas precisarem de acesso simultâneo ao mesmo vault.

Evolução da especificação MCP. A especificação MCP de junho de 2025 adicionou autorização OAuth 2.1, saídas estruturadas de ferramentas (esquemas de retorno tipados) e elicitação (prompts ao usuário iniciados pelo servidor). A versão de novembro de 2025 trouxe o Streamable HTTP como modo de transporte de primeira classe, descoberta de URL .well-known para navegação automática pelas capacidades do servidor, anotações estruturadas de ferramentas que declaram se uma ferramenta é somente leitura ou mutável, e um sistema de padronização de níveis SDK.⁷⁹ A próxima revisão agora é concreta: a especificação de 2026-07-28 entrou em Release Candidate em 21 de maio de 2026 — a maior revisão do MCP desde o lançamento. Suas principais mudanças são um núcleo de protocolo sem estado (o handshake initialize e o cabeçalho Mcp-Session-Id foram removidos, portanto os servidores não rastreiam mais o estado da sessão por conexão), Apps do MCP (os servidores podem retornar HTML renderizado no servidor, exibido em iframes sandboxed do cliente), Tasks deixando o núcleo experimental e se tornando uma extensão oficial (tasks/get, tasks/update, tasks/cancel para operações de longa duração), autorização OAuth 2.0 / OIDC reforçada e uma política de ciclo de vida de descontinuação de recursos de 12 meses. Ela foi lançada conforme o cronograma como a revisão de 28 de julho de 2026 — agora a especificação atual (verificada em 14 de agosto de 2026).²⁴ Para servidores de vaults pessoais, STDIO continua sendo o caminho mais simples, e o núcleo sem estado torna os servidores STDIO para um único usuário ainda mais enxutos. O transporte Streamable HTTP, a descoberta .well-known e os Apps do MCP beneficiam principalmente implantações HTTP empresariais com roteamento multilocatário e balanceamento de carga. Acompanhe o roadmap do MCP para atualizações que afetem sua escolha de transporte.

Design de capacidades

O servidor MCP deve expor um conjunto mínimo de ferramentas:

search — A ferramenta principal. Executa a recuperação hybrid e retorna resultados classificados.

{
  "name": "obsidian_search",
  "description": "Search the Obsidian vault using hybrid BM25 + vector retrieval",
  "parameters": {
    "query": { "type": "string", "description": "Search query" },
    "limit": { "type": "integer", "default": 5 },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

read_note — Lê o conteúdo completo de uma nota específica pelo caminho. Útil quando o agente quer ver o contexto completo de um resultado de busca.

{
  "name": "obsidian_read_note",
  "description": "Read the full content of a note by file path",
  "parameters": {
    "file_path": { "type": "string", "description": "Relative path within vault" }
  }
}

list_notes — Lista notas que correspondem a um filtro (por pasta, tag, tipo ou intervalo de datas). Útil para exploração quando o agente não tem uma consulta específica.

{
  "name": "obsidian_list_notes",
  "description": "List notes matching filters",
  "parameters": {
    "folder": { "type": "string", "description": "Folder path within vault" },
    "tag": { "type": "string", "description": "Tag to filter by" },
    "limit": { "type": "integer", "default": 20 }
  }
}

get_context — Uma ferramenta de conveniência que executa uma busca e formata os resultados como um bloco de contexto adequado para inserção em uma conversa.

{
  "name": "obsidian_get_context",
  "description": "Get formatted context from vault for a topic",
  "parameters": {
    "topic": { "type": "string", "description": "Topic to get context for" },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

Limites de permissão

O servidor MCP deve impor limites rigorosos:

1. Somente leitura. O servidor lê o vault e o banco de dados do índice. Ele não cria, modifica nem exclui notas. As operações de escrita (captura de novas notas) são tratadas por hooks ou skills separados, não pelo servidor MCP.

2. Restrito ao vault. O servidor lê apenas arquivos dentro do caminho configurado do vault. Tentativas de path traversal (../../etc/passwd) devem ser rejeitadas.

3. Saída com credenciais filtradas. Mesmo que o banco de dados contenha conteúdo pré-filtrado, aplique filtragem de credenciais na saída como uma medida de defesa em profundidade.

4. Respostas limitadas por tokens. Aplique max_tokens em todas as respostas das ferramentas para evitar que a ferramenta de IA receba blocos de contexto excessivamente grandes.

Tratamento de erros

As ferramentas do MCP devem retornar mensagens de erro estruturadas que ajudem a ferramenta de IA a se recuperar:

def search(self, query, limit=5, max_tokens=2000):
    if not self.db_path.exists():
        return {
            "error": "Index database not found. Run the indexer first.",
            "suggestion": "python index_vault.py --full"
        }

    results = self.retriever.search(query, limit, max_tokens)

    if not results:
        return {
            "results": [],
            "message": f"No results found for '{query}'. Try broader terms."
        }

    return {
        "results": [
            {
                "file_path": r["file_path"],
                "section": r["section"],
                "text": r["chunk_text"],
                "score": round(r["rrf_score"], 4),
            }
            for r in results
        ],
        "count": len(results),
        "query": query,
    }

Integração com Claude Code

Claude Code é o principal consumidor do sistema de recuperação do Obsidian. Esta seção aborda a configuração do MCP, a integração de hooks e o padrão obsidian_bridge.py.

Configuração do MCP

Registre o servidor personalizado com claude mcp add (o escopo de usuário grava em ~/.claude.json; -s project grava um .mcp.json compartilhável — ~/.claude/settings.json não é uma superfície de configuração do MCP):

claude mcp add obsidian -s user \
  -e VAULT_PATH=/absolute/path/to/vault \
  -e DB_PATH=/absolute/path/to/vectors.db \
  -- python /path/to/obsidian_mcp.py

A entrada equivalente em .mcp.json, caso você prefira escrevê-la manualmente:

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

Depois de adicionar a configuração, reinicie o Claude Code. O servidor MCP será iniciado como um processo filho. Verifique se ele está em execução:

> What tools do you have from the obsidian MCP server?

Claude Code deve listar as ferramentas disponíveis (obsidian_search, obsidian_read_note etc.).

Integração de hooks

Hooks estendem o comportamento do Claude Code em pontos definidos do ciclo de vida. Dois hooks são relevantes para a integração com o Obsidian:

Os hooks são registrados nas configurações (~/.claude/settings.json, sob a chave hooks, com um nome de evento e matcher) e recebem um payload JSON no stdin — não há um diretório de hooks que o Claude Code descubra automaticamente, e os detalhes da ferramenta nunca chegam como argumentos $1/$2.

Hook UserPromptSubmit — consulta o vault quando você envia um prompt e injeta contexto relevante (o stdout desse evento é adicionado à conversa):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{ "type": "command", "command": "/path/to/obsidian-context.sh" }]
      }
    ]
  }
}

#!/bin/bash
# obsidian-context.sh — read the JSON payload from stdin
PROMPT=$(jq -r '.prompt // empty')
[ -z "$PROMPT" ] && exit 0
CONTEXT=$(python /path/to/retriever.py search "$PROMPT" --limit 3 --max-tokens 1500)
if [ -n "$CONTEXT" ]; then
    printf 'Relevant vault context:\n%s\n' "$CONTEXT"   # stdout -> added as context
fi

Hook PostToolUse — captura saídas significativas de ferramentas de volta para o vault para recuperação futura (registrado com um matcher para que seja acionado apenas para as ferramentas que importam):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [{ "type": "command", "command": "/path/to/capture-insight.sh" }]
      }
    ]
  }
}

#!/bin/bash
# capture-insight.sh — tool name and response arrive as stdin JSON
PAYLOAD=$(cat)
TOOL_NAME=$(printf '%s' "$PAYLOAD" | jq -r '.tool_name')
OUTPUT=$(printf '%s' "$PAYLOAD" | jq -r '.tool_response // "" | tostring')
if [ ${#OUTPUT} -gt 500 ]; then
    python /path/to/capture.py --text "$OUTPUT" --source "claude-code-$TOOL_NAME"
fi

O padrão obsidian_bridge.py

Um módulo bridge fornece uma Python API que hooks e skills podem chamar:

# obsidian_bridge.py
from retriever import HybridRetriever

_retriever = None

def get_retriever():
    global _retriever
    if _retriever is None:
        _retriever = HybridRetriever(
            db_path="/path/to/vectors.db",
            vault_path="/path/to/vault",
        )
    return _retriever

def search_vault(query, limit=5, max_tokens=2000):
    """Search vault and return formatted context."""
    retriever = get_retriever()
    results = retriever.search(query, limit, max_tokens)

    if not results:
        return ""

    lines = ["## Vault Context\n"]
    for r in results:
        lines.append(f"**{r['file_path']}** — {r['section']}")
        lines.append(f"> {r['chunk_text'][:500]}")
        lines.append("")

    return "\n".join(lines)

A skill /capture

Uma skill do Claude Code para capturar insights de volta no vault:

/capture "OAuth token rotation requires both access and refresh token invalidation"
  --domain security
  --tags oauth,tokens

A skill cria uma nova nota em 00-inbox/ com o frontmatter correto e aciona uma reindexação incremental para que a nova nota possa ser pesquisada imediatamente.

Padrões de comandos personalizados

As skills do Claude Code podem encapsular operações do vault em comandos nomeados. Profissionais criaram bibliotecas de comandos específicos para Obsidian que tratam o vault tanto como fonte de leitura quanto como destino de escrita.

Varredura de sinais. Um comando /scan-intel consulta fontes externas, pontua descobertas em relação a interesses pessoais de pesquisa e grava sinais qualificados como notas no vault com frontmatter:

/scan-intel --topics "agent infrastructure, security" --lookback 7d

O comando busca informações em fontes configuradas (arXiv, HN, RSS), aplica um modelo de pontuação (relevância, capacidade de gerar ação, profundidade, autoridade) e grava os sinais aprovados em pastas do vault específicas por tópico. O vault se torna o consumidor downstream de um pipeline automatizado de inteligência.

Diário de bordo. Um comando /captains-log agrega a atividade diária do git em todos os repositórios, grava uma entrada estruturada de diário no vault e inclui decisões tomadas, percepções e tópicos em aberto:

/captains-log

O comando coleta o histórico de commits do GitHub, agrupa por repositório e formata como uma entrada narrativa de diário. Com o tempo, os registros diários criam um histórico pesquisável do que foi entregue e por quê.

Captura no Obsidian. Um comando /obsidian-capture recebe um insight da sessão atual do Claude Code e o grava diretamente no vault com os metadados corretos:

/obsidian-capture "SAST gates in agent loops increase security degradation"
  --folder AI-Tools --tags security,agents

O padrão se estende a qualquer operação no vault: criar MOCs, atualizar notas de status de projetos, vincular sinais relacionados ou gerar resumos semanais a partir de registros diários acumulados.

Exemplos da comunidade. Profissionais estão publicando suas bibliotecas de comandos. Um desenvolvedor compartilhou 22 comandos personalizados para Obsidian + Claude Code que abrangem revisões diárias, planejamento de projetos, captura de pesquisas e fluxos de trabalho de conteúdo.¹ Outro criou uma skill “Visual Explainer” que gera notas com diagramas no vault a partir da análise de código.² Os comandos variam, mas a arquitetura é consistente: skills do Claude Code como interface, notas do vault como camada de armazenamento e infraestrutura de recuperação como mecanismo de consulta.

Gerenciamento da janela de contexto

A integração deve considerar a janela de contexto do Claude Code:

• Limite o contexto injetado a 1.500-2.000 tokens por consulta. Mais do que isso compete com a memória de trabalho do agente.
• Inclua atribuição da fonte. Sempre inclua o caminho do arquivo e o título da seção para que o agente possa consultar a fonte.
• Trunque o texto dos chunks. Chunks longos devem ser truncados com ..., em vez de omitidos por completo. Os primeiros 300-500 caracteres normalmente contêm as informações principais.
• Não injete em todos os prompts. A injeção é executada por UserPromptSubmit (o evento cujo stdout chega ao modelo), portanto, gerencie o orçamento nela: pule prompts conversacionais curtos, injete apenas quando o prompt mencionar código, arquivos ou decisões anteriores e limite o bloco injetado. Eventos restritos a ferramentas, como PreToolUse, podem bloquear ou registrar, mas o stdout deles nunca chega ao modelo.

Integração do Codex CLI

O Codex CLI se conecta a servidores MCP por meio de config.toml. O padrão de integração difere do Claude Code na sintaxe de configuração e na entrega de instruções.

Configuração do MCP

Adicione a ~/.codex/config.toml (o Codex lê $CODEX_HOME/config.toml; instruções no nível do projeto pertencem a AGENTS.md, não a um arquivo de configuração do projeto):

[mcp_servers.obsidian]
command = "python"
args = ["/path/to/obsidian_mcp.py"]

[mcp_servers.obsidian.env]
VAULT_PATH = "/absolute/path/to/vault"
DB_PATH = "/absolute/path/to/vectors.db"

Padrões de AGENTS.md

O Codex CLI lê AGENTS.md para instruções no nível do projeto. Inclua orientações para pesquisar o vault:

## Available Tools

### Obsidian Vault (MCP: obsidian)
Use the `obsidian_search` tool to find relevant context from the knowledge base.
Search the vault when you need:
- Background on a concept or pattern
- Prior decisions or rationale
- Reference material for implementation

Example queries:
- "authentication patterns in FastAPI"
- "how does the review aggregator work"
- "sqlite-vec configuration"

Diferenças em relação ao Claude Code

Diferença principal: ambas as ferramentas agora oferecem suporte a hooks e skills; o que difere é o formato. O Codex combina uma política de aprovação com um modo de sandbox no nível do sistema operacional, em vez dos modos de permissão do Claude Code, e seus eventos de hook são diferentes — adapte o padrão (consulte o vault antes de trabalhar, capture depois), não a configuração. AGENTS.md continua sendo o lugar certo para instruções persistentes de pesquisar-primeiro-no-vault no Codex.

Cursor e outras ferramentas

Cursor e outras ferramentas de IA compatíveis com MCP podem se conectar ao mesmo servidor MCP do Obsidian. Esta seção aborda a configuração de ferramentas comuns.

Cursor

Adicione a .cursor/mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

O arquivo .cursorrules do Cursor pode incluir instruções para usar o vault:

When working on implementation tasks, search the Obsidian vault
for relevant context before writing code. Use the obsidian_search
tool with descriptive queries about the concept you're implementing.

Matriz de compatibilidade

Alternativa para ferramentas sem MCP

Para ferramentas que não oferecem suporte a MCP, o recuperador pode ser encapsulado como um CLI:

# Search from command line
python retriever_cli.py search "query text" --limit 5

# Output formatted for copy-paste into any tool
python retriever_cli.py context "query text" --format markdown

O CLI produz texto estruturado que pode ser colado manualmente na entrada de qualquer ferramenta de IA. Isso é menos elegante do que a integração com MCP, mas funciona universalmente.

Cache de prompts a partir de notas estruturadas

Notas estruturadas no vault podem servir como blocos de contexto reutilizáveis que reduzem o uso de tokens nas interações com IA. Esta seção aborda o design de chaves de cache e o gerenciamento do orçamento de tokens.

O padrão

Em vez de buscar contexto em cada interação, crie antecipadamente blocos de contexto a partir de notas bem estruturadas do vault e armazene-os em cache:

# cache_keys.py
CONTEXT_BLOCKS = {
    "auth-patterns": {
        "vault_query": "authentication patterns implementation",
        "max_tokens": 1500,
        "ttl_hours": 24,  # Rebuild daily
    },
    "api-conventions": {
        "vault_query": "API design conventions REST patterns",
        "max_tokens": 1000,
        "ttl_hours": 168,  # Rebuild weekly
    },
    "project-architecture": {
        "vault_query": "current project architecture decisions",
        "max_tokens": 2000,
        "ttl_hours": 12,  # Rebuild twice daily
    },
}

Invalidação do cache

A invalidação do cache se baseia em dois sinais:

1. Expiração do TTL. Cada bloco de contexto tem um tempo de vida. Quando o TTL expira, o bloco é reconstruído consultando novamente o vault.
2. Detecção de mudanças no vault. Quando o indexador detecta mudanças em arquivos que contribuíram para um bloco de contexto armazenado em cache, o bloco é invalidado imediatamente.

Gerenciamento do orçamento de tokens

Uma sessão começa com um orçamento total de contexto. Os blocos em cache consomem parte desse orçamento:

Total context budget:    8,000 tokens
├─ System prompt:        1,500 tokens
├─ Cached blocks:        3,000 tokens (pre-loaded)
├─ Dynamic search:       2,000 tokens (on-demand)
└─ Conversation:         1,500 tokens (remaining)

Os blocos em cache são carregados no início da sessão. Os resultados de buscas dinâmicas preenchem o orçamento restante por consulta. Essa abordagem híbrida oferece ao agente uma base de contexto frequentemente necessária, preservando o orçamento para consultas específicas.

Uso de tokens antes/depois

Sem cache: Cada consulta relevante aciona uma busca no vault, retornando 1.500-2.000 tokens de contexto. Em 10 consultas em uma sessão, o agente consome 15.000-20.000 tokens de contexto do vault.

Com cache: Três blocos de contexto pré-criados consomem 4.500 tokens no total. Buscas adicionais acrescentam 1.500-2.000 tokens por consulta única. Em 10 consultas, das quais 6 são atendidas por blocos em cache, o agente consome 4.500 + (4 * 1.500) = 10.500 tokens — aproximadamente metade do uso sem cache.

Captura de resumos comprimidos de saídas detalhadas

As saídas de ferramentas podem ser detalhadas: stack traces, listagens de arquivos e resultados de testes. Um hook não consegue reduzir o que o modelo vê — quando PostToolUse é acionado, a saída completa já está na janela de contexto, e nada que um hook imprima a substitui. O que um hook pode fazer é gravar um resumo comprimido no vault, para que sessões futuras recuperem o veredito em duas linhas em vez de executar novamente ou reler o original de 5.000 tokens. Trate isso como um padrão de captura para memória entre sessões, não como uma forma de economizar contexto durante a sessão (nela, os recursos reais são /compact, prompts com escopo definido e solicitar saídas menos detalhadas).

O problema

Uma chamada à ferramenta Bash que executa testes pode retornar:

PASSED tests/test_auth.py::test_login_success
PASSED tests/test_auth.py::test_login_failure
PASSED tests/test_auth.py::test_token_refresh
PASSED tests/test_auth.py::test_session_expiry
... (200 more lines)
FAILED tests/test_api.py::test_rate_limit_exceeded

A saída completa tem 5.000 tokens, mas o sinal está em 2 linhas: 200 aprovados, 1 com falha.

Implementação do hook

Registrado em PostToolUse com um matcher Bash (registrado nas configurações, JSON via stdin — consulte Integração de hooks acima):

#!/bin/bash
# summarize-and-capture.sh — write a compressed summary to the vault
PAYLOAD=$(cat)
OUTPUT=$(printf '%s' "$PAYLOAD" | jq -r '.tool_response // "" | tostring')

# Only summarize large outputs
[ ${#OUTPUT} -lt 2000 ] && exit 0

if printf '%s' "$OUTPUT" | grep -q "PASSED\|FAILED"; then
    PASSED=$(printf '%s' "$OUTPUT" | grep -c "PASSED")
    FAILED=$(printf '%s' "$OUTPUT" | grep -c "FAILED")
    SUMMARY="Tests: $PASSED passed, $FAILED failed"
    [ "$FAILED" -gt 0 ] && SUMMARY="$SUMMARY
$(printf '%s' "$OUTPUT" | grep 'FAILED')"
    python /path/to/capture.py --text "$SUMMARY" --source "test-run-summary"
fi
exit 0

Cada invocação do hook é um processo novo, portanto não é necessária uma proteção contra recursão — as próprias gravações de um hook não o acionam novamente, e variáveis exportadas nunca sobrevivem até a próxima invocação.

Heurísticas de compressão

Pipeline de entrada e triagem de sinais

A camada de entrada determina o que entra no vault. Sem curadoria, o vault acumula ruído. Esta seção aborda o pipeline de pontuação que direciona sinais para pastas de domínio.

Fontes

Os sinais vêm de vários canais:

• Feeds RSS: Blogs técnicos, avisos de segurança, notas de lançamento
• Favoritos via Web Clipper: A extensão oficial Obsidian Web Clipper (Chrome, Firefox, Safari) é o caminho de entrada com maior fidelidade para captura no navegador. O ciclo de lançamentos de abril de 2026 a tornou significativamente mais útil para fluxos de trabalho com IA:²²
  • 1.4.0 (9 de abr.): Interface interativa de transcrições do YouTube — fixe o vídeo, navegue pela transcrição, role automaticamente e destaque a posição atual. Além de um padrão “Open in Reader” que envia uma captura com um clique diretamente para o modo Reader.
  • 1.5.0–1.5.1 (15 de abr.): Visualizador de destaques — navegue e pesquise destaques capturados em todo o vault. Transição de entrada gradual para o Reader. Reprodução/pausa do YouTube mais fluida. A versão 1.5.1 corrigiu uma regressão na compilação do webpack.
  • 1.6.0–1.6.2 (21–23 de abr.): Reformulação da UX do marcador de texto com suporte para dispositivos móveis. Defuddle 0.18 adiciona extratores específicos para LinkedIn, Threads, Bluesky, Discourse e Medium. A versão 1.6.2 corrige uma regressão da área de transferência no modo incorporado do Safari. Configure templates por domínio de origem para que transcrições do YouTube, READMEs de GitHub e artigos longos cheguem cada um a uma nota com nome apropriado e o frontmatter correto para o pipeline de pontuação abaixo.
• Newsletters: Trechos importantes de newsletters por e-mail
• Captura manual: Notas escritas durante leituras, conversas ou pesquisas
• Saída de ferramentas: Saídas relevantes de ferramentas de IA capturadas por meio de hooks
• Extensão de Compartilhamento do iOS: O app iOS do Obsidian (atualizado no início de 2026) inclui uma Extensão de Compartilhamento que salva conteúdo do Safari, redes sociais e outros apps diretamente no vault sem abrir o Obsidian; a linha 1.13 adiciona destinos configuráveis na Folha de Compartilhamento com variáveis de template — incluindo url, para que uma página capturada registre automaticamente seu link de origem no frontmatter.¹⁹ Isso cria um caminho de entrada móvel sem atrito — compartilhe um artigo pelo Safari e ele chega como uma nota no vault pronta para ser pontuada.
• Obsidian CLI: Scripts de shell e hooks podem criar notas via obsidian file create ou acrescentar conteúdo a notas existentes via obsidian file append, permitindo pipelines automatizados de entrada no desktop.

Dimensões de pontuação

Cada sinal recebe uma pontuação em quatro dimensões (de 0,0 a 1,0 cada):

Pontuação composta e direcionamento

composite = (relevance * 0.35) + (actionability * 0.25) +
            (depth * 0.25) + (authority * 0.15)

Direcionamento por domínio

Sinais com pontuação acima de 0.55 são direcionados a uma de 12 pastas de domínio com base em correspondência de palavras-chave e classificação de tópicos:

05-signals/
├── ai-tooling/        # Claude, LLMs, AI development tools
├── security/          # Vulnerabilities, auth, cryptography
├── systems/           # Architecture, distributed systems
├── programming/       # Languages, patterns, algorithms
├── web/               # Frontend, backends, APIs
├── data/              # Databases, data engineering
├── devops/            # CI/CD, containers, infrastructure
├── design/            # UI/UX, product design
├── mobile/            # iOS, Android, cross-platform
├── career/            # Industry trends, hiring, growth
├── research/          # Academic papers, whitepapers
└── other/             # Signals that don't fit a domain

Estatísticas de produção

Ao longo de 14 meses de operação:

Padrões de grafo de conhecimento

O grafo de wiki-links do Obsidian codifica relações entre notas. Esta seção aborda a semântica dos links, o percurso do grafo para expansão de contexto e antipadrões que degradam a qualidade do grafo.

Semântica de backlinks

Cada wiki-link cria uma aresta direcionada no grafo. O Obsidian rastreia links diretos e backlinks:

• Link direto: A nota A contém [[Note B]] → A cria um link para B
• Backlink: A nota B mostra que a nota A faz referência a ela

O grafo codifica diferentes tipos de relações, dependendo do contexto:

Maps of Content (MOCs)

MOCs são notas de índice que organizam notas relacionadas em uma estrutura navegável:

---
title: "Authentication & Security MOC"
type: moc
domain: security
---

## Core Concepts
- [[OAuth 2.0 Overview]]
- [[JWT Token Anatomy]]
- [[Session Management Patterns]]

## Implementation Patterns
- [[OAuth Token Rotation]]
- [[Refresh Token Security]]
- [[PKCE Flow Implementation]]

## Failure Modes
- [[Token Expiry Handling]]
- [[Session Fixation Prevention]]
- [[CSRF Defense Strategies]]

Os MOCs beneficiam a recuperação de duas formas:

1. Correspondência direta. Uma busca por “authentication overview” encontra o próprio MOC, fornecendo ao agente uma lista curada de notas relacionadas.
2. Expansão de contexto. Depois de encontrar uma nota específica, o recuperador pode verificar se a nota aparece em algum MOC e incluir a estrutura do MOC nos resultados, oferecendo ao agente um mapa do tópico mais amplo.

Percurso do grafo para expansão de contexto

Uma melhoria futura para o recuperador: depois de encontrar os principais resultados, expanda o contexto seguindo links:

def expand_context(results, depth=1):
    """Follow wiki-links from top results to find related context."""
    expanded = set()
    for result in results:
        # Parse wiki-links from chunk text
        links = extract_wiki_links(result["chunk_text"])
        for link_target in links:
            # Resolve link to file path
            target_path = resolve_wiki_link(link_target)
            if target_path and target_path not in expanded:
                expanded.add(target_path)
                # Include target's most relevant chunk
                target_chunks = get_chunks_for_file(target_path)
                # ... rank and include best chunk
    return results + list(expanded_results)

Isso não está implementado no recuperador atual, mas representa uma extensão natural da estrutura do grafo.

Antipadrões

Clusters órfãos. Grupos de notas que se vinculam entre si, mas não têm conexões com o restante do vault. O painel de grafo no Obsidian torna esses grupos visíveis como ilhas desconectadas. Clusters órfãos indicam MOCs ausentes ou links entre domínios ausentes.

Proliferação de tags. Usar tags de forma inconsistente ou criar tags detalhadas demais. Um vault com 500 tags únicas em 5.000 notas tem, em média, 1 nota a cada 10 tags — as tags não são úteis para filtragem. Consolide em 20 a 50 tags de alto nível que correspondam às suas pastas de domínio.

Notas com muitos links e pouco conteúdo. Notas compostas inteiramente de wiki-links, sem prosa. Essas notas são mal indexadas porque o chunker não tem texto para transformar em embeddings. Adicione pelo menos um parágrafo de contexto explicando por que as notas vinculadas estão relacionadas.

Links bidirecionais para tudo. Nem toda referência precisa ser um wiki-link. Mencionar “OAuth” de passagem não exige [[OAuth 2.0 Overview]]. Reserve wiki-links para relações intencionais e navegáveis, nas quais clicar no link forneceria um contexto útil.

Receitas de fluxo de trabalho para desenvolvedores

Fluxos de trabalho práticos que combinam recuperação do vault com tarefas diárias de desenvolvimento.

Carregamento de contexto pela manhã

Comece o dia carregando o contexto relevante:

Search my vault for notes about [current project] updated in the last week

O retriever retorna notas recentes sobre seu projeto ativo, oferecendo uma rápida recapitulação de onde você parou. Mais eficaz do que reler as mensagens de commit de ontem.

Captura de pesquisa durante o código

Ao implementar um recurso, capture insights sem sair do editor:

/capture "FastAPI dependency injection with async generators requires yield,
not return. The generator is the dependency lifecycle."
  --domain programming
  --tags fastapi,dependency-injection

O insight capturado é indexado imediatamente e fica disponível para recuperação futura. Ao longo dos meses, essas microcapturas criam um corpus de conhecimento específico de implementação.

Início de projeto

Ao começar um novo projeto ou recurso:

1. Pesquise no vault: “O que eu sei sobre [tecnologia/padrão]?”
2. Revise os 5 principais resultados em busca de decisões anteriores e gotchas
3. Verifique se existe um MOC para o domínio; se não existir, crie um
4. Pesquise modos de falha: “problemas com [tecnologia]”

Debugging com pesquisa no vault

Ao encontrar um erro ou comportamento inesperado:

Search my vault for [error message or symptom]

Notas anteriores de debugging muitas vezes contêm a causa raiz e a correção. Isso é especialmente valioso para problemas recorrentes entre projetos — o vault lembra o que você esquece.

Preparação para code review

Antes de revisar um PR:

Search my vault for patterns and conventions about [module being changed]

O vault retorna decisões anteriores, restrições arquiteturais e padrões de código relevantes para o código em revisão. A revisão é informada por conhecimento institucional, não apenas pelo diff.

Ajuste de performance

Esta seção cobre estratégias de otimização para diferentes tamanhos de vault e padrões de uso.

Gerenciamento do tamanho do índice

Com 50.000+ notas, considere: - Aumentar o tamanho do lote de 64 para 128 para gerar embeddings mais rápido - Usar o modo WAL (padrão) para acesso concorrente - Executar a reindexação completa fora dos horários de pico

Otimização de consulta

Modo WAL. O modo Write-Ahead Logging do SQLite permite leituras concorrentes enquanto o indexador escreve:

db.execute("PRAGMA journal_mode=WAL")

Isso é essencial quando o servidor MCP lida com consultas enquanto o indexador executa uma atualização incremental.

Pooling de conexões. O servidor MCP deve reutilizar conexões com o banco de dados em vez de abrir uma nova conexão por consulta. Uma única conexão de longa duração com modo WAL oferece suporte a leituras concorrentes.

# MCP server initialization
db = sqlite3.connect(DB_PATH, check_same_thread=False)
db.execute("PRAGMA journal_mode=WAL")
db.execute("PRAGMA mmap_size=268435456")  # 256 MB mmap

I/O mapeado em memória. O pragma mmap_size informa ao SQLite para usar I/O mapeado em memória para o arquivo de banco de dados. Para um banco de dados de 83 MB, mapear o arquivo inteiro na memória elimina a maioria das leituras em disco.

Otimização de FTS5. Após uma reindexação completa, execute:

INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

Isso mescla os segmentos internos de b-tree do FTS5, reduzindo a latência de consulta para pesquisas posteriores.

Benchmarks de escala

Medido em Apple M3 Pro, 36 GB de RAM, SSD NVMe:

Todos os benchmarks incluem acesso ao banco de dados, execução da consulta e formatação dos resultados. A latência de rede para comunicação MCP STDIO adiciona 1-2ms.

Solução de problemas

Desvio do índice

Sintoma: A pesquisa retorna resultados desatualizados ou não encontra notas adicionadas recentemente.

Causa: O indexador incremental não foi executado após adicionar notas, ou o mtime de um arquivo não foi atualizado (por exemplo, sincronizado de outra máquina com timestamps preservados).

Correção: Execute uma reindexação completa: python index_vault.py --full

Troca do modelo de embeddings

Sintoma: Depois de alterar o modelo de embeddings, a pesquisa vetorial retorna resultados sem sentido.

Causa: Vetores antigos (do modelo anterior) estão sendo comparados com novos vetores de consulta. As dimensões ou a semântica do espaço vetorial são incompatíveis.

Correção: O indexador deve detectar a incompatibilidade de hash do modelo e acionar automaticamente uma reindexação completa. Se isso não acontecer, limpe manualmente o banco de dados e reindexe:

rm vectors.db
python index_vault.py --full

Manutenção do FTS5

Sintoma: Consultas FTS5 retornam resultados incorretos ou incompletos após muitas atualizações incrementais.

Causa: Segmentos internos do FTS5 podem ficar fragmentados depois de muitas atualizações pequenas.

Correção: Reconstrua e otimize:

INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');
INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

Timeout do MCP

Sintoma: A ferramenta de AI informa que o servidor MCP atingiu timeout.

Causa: A primeira consulta aciona o carregamento do modelo (inicialização preguiçosa), que leva 2-5 segundos. O timeout padrão de MCP da ferramenta de AI pode ser menor.

Correção: Faça o pré-aquecimento do modelo na inicialização do servidor:

# In MCP server initialization
retriever = HybridRetriever(db_path, vault_path)
retriever.search("warmup", limit=1)  # Trigger model load

Locks de arquivo do SQLite

Sintoma: Erros SQLITE_BUSY ou SQLITE_LOCKED.

Causa: Vários processos escrevendo no banco de dados ao mesmo tempo. O modo WAL permite leituras concorrentes, mas apenas um escritor.

Correção: Garanta que apenas um processo (o indexador) escreva no banco de dados. O servidor MCP e os hooks devem apenas ler. Se você precisar de escritas concorrentes, use o modo WAL e defina um timeout de ocupado:

db.execute("PRAGMA busy_timeout=5000")  # Wait up to 5 seconds

sqlite-vec não carrega

Sintoma: A pesquisa vetorial está desativada; o retriever roda em modo somente BM25.

Causa: A extensão sqlite-vec não está instalada, não foi encontrada no caminho da biblioteca ou é incompatível com a versão do SQLite.

Correção:

# Install via pip
pip install sqlite-vec

# Or compile from source
git clone https://github.com/asg017/sqlite-vec
cd sqlite-vec && make

Verifique se a extensão carrega:

import sqlite3
db = sqlite3.connect(":memory:")
db.enable_load_extension(True)
db.load_extension("vec0")
print("sqlite-vec loaded successfully")

Problemas de memória em vault grande

Sintoma: Erros de falta de memória durante a reindexação completa de um vault grande (50.000+ notas).

Causa: O tamanho do lote de embeddings é grande demais, ou todo o conteúdo dos arquivos está sendo carregado na memória simultaneamente.

Correção: Reduza o tamanho do lote e processe os arquivos incrementalmente:

BATCH_SIZE = 32  # Reduce from 64

Também garanta que o indexador processe os arquivos um de cada vez (lendo, fazendo chunking e gerando embeddings de cada arquivo antes de passar para o próximo), em vez de carregar todos os arquivos na memória.

Guia de migração

Do Apple Notes

1. Exporte o Apple Notes usando a opção “Export All” (macOS) ou use uma ferramenta de migração como apple-notes-liberator
2. Converta as exportações HTML para markdown usando markdownify ou pandoc
3. Mova os arquivos convertidos para a pasta 00-inbox/ do seu vault
4. Revise e adicione frontmatter a cada nota
5. Mova as notas para as pastas de domínio apropriadas

Do Notion

1. Exporte do Notion: Settings → Export → Markdown & CSV
2. Descompacte a exportação na pasta 00-inbox/ do seu vault
3. Corrija artefatos de markdown específicos do Notion:
4. O Notion usa - [ ] para checklists — isso é markdown padrão
5. O Notion inclui tabelas de propriedades como HTML — converta para frontmatter YAML
6. O Notion incorpora imagens como caminhos relativos — copie as imagens para sua pasta de anexos
7. Adicione frontmatter padrão (type, domain, tags)
8. Substitua links de páginas do Notion por wiki-links do Obsidian

Do Google Docs

1. Use o Google Takeout para exportar todos os documentos
2. Converta arquivos .docx para markdown: pandoc -f docx -t markdown input.docx -o output.md
3. Converta em lote: for f in *.docx; do pandoc -f docx -t markdown "$f" -o "${f%.docx}.md"; done
4. Mova para o vault, adicione frontmatter e organize em pastas

De markdown puro (sem Obsidian)

Se você já tem um diretório de arquivos markdown:

1. Abra o diretório como um vault do Obsidian (Obsidian → Open Vault → Open folder)
2. Adicione .obsidian/ ao .gitignore se o diretório tiver controle de versão
3. Crie templates de frontmatter e aplique aos arquivos existentes
4. Comece a conectar notas com [[wiki-links]] conforme você lê e organiza
5. Execute o indexador imediatamente — o sistema de recuperação funciona desde o primeiro dia

De outro sistema de recuperação

Se você está migrando de um sistema diferente de embeddings/pesquisa:

1. Não tente migrar vetores. Modelos diferentes produzem espaços vetoriais incompatíveis. Execute uma reindexação completa com o novo modelo.
2. Migre o conteúdo, não o índice. Os arquivos do vault são a fonte da verdade. O índice é um artefato derivado.
3. Verifique após a migração. Execute 10-20 consultas cujas respostas você já conhece e confira se os resultados correspondem às suas expectativas.

Registro de alterações

Referências