Combinando Obsidian e Claude Code para Acumulação de Conhecimento Sem Desorganização de Arquivos

Qualquer pessoa que tentou manter uma base de conhecimento pessoal encontrou o mesmo problema. Tudo começa com boas intenções: configurar um Obsidian belamente estruturado, organizar pensamentos de forma ordenada, vincular notas entre si. E alguns meses depois, o cofre se transforma em uma bagunça caótica de trechos de código copiados, links não processados e rascunhos abandonados deixados pela metade.

O pesquisador Andrej Karpathy uma vez descreveu o conceito de um Wiki LLM: um conceito onde uma rede neural ajuda a estruturar o conhecimento pessoal, transformando-o em um grafo coerente. O repositório claude-obsidian coloca essa ideia em prática. É uma ferramenta local para Claude Code e hosts compatíveis com Agent Skills que processa materiais recebidos por conta própria, verifica fatos contra fontes primárias e organiza tudo em arquivos Markdown no seu disco.

Por que se incomodar quando existem plugins de IA regulares

A maioria das extensões de anotações com IA funciona simplesmente assim: elas pegam seu texto, enviam para um banco de dados na nuvem, constroem um índice vetorizado e geram outro pedaço de texto generativo. Se você fechar o plugin ou cancelar sua assinatura, todo esse "inteligente" andaime desaparece.

Em claude-obsidian, a abordagem é diferente. A base de conhecimento permanece uma pasta comum com arquivos Markdown, JSON e de código-fonte. Os dados não estão escondidos no cache interno do plugin e não voam para servidores de terceiros sem o seu consentimento. Toda a mágica acontece por cima dos seus próprios arquivos.

O sistema é construído em torno de um processo cíclico:

1. Você joga material na pasta inbox/. A ferramenta cria uma cópia exata e imutável com um hash fixo.
2. Durante a análise, a IA extrai afirmações específicas do texto. Se os fatos forem questionáveis ou se contradisserem, eles são marcados separadamente. O sistema não inventa fontes — referencia explicitamente o original salvo.
3. A partir do material processado, são geradas notas atômicas, índices e diagramas visuais no Obsidian Canvas.
4. A base finalizada pode ser consultada através do Claude Code, contradições podem ser encontradas, links quebrados podem ser procurados e novos tópicos podem ser adicionados.

O resultado parece uma base de conhecimento elegantemente organizada que é igualmente conveniente para trabalhar tanto através de um agente de IA quanto manualmente através da interface padrão do Obsidian.

Sob o capô: 15 habilidades em um CLI

Os desenvolvedores organizaram a funcionalidade como um conjunto de 15 chamadas habilidades. Elas podem ser invocadas como comandos separados do Claude Code ou usadas como scripts independentes.

Todas as habilidades são divididas em três grupos lógicos:

• Operações de banco de dados e wiki — inicialização do cofre (wiki), salvamento de respostas exatas sem registrar desordem desnecessária (save), parsing de arquivos de entrada (wiki-ingest), resposta baseada apenas em fatos verificados do banco de dados (wiki-query) e busca de problemas como páginas órfãs ou seções vazias (wiki-lint).
• Cenários avançados — busca web autônoma com salvamento isolado de resultados (autoresearch), geração de quadros Obsidian Canvas (canvas), limpeza de páginas web de desordem antes da leitura (defuddle), agregação de logs (wiki-fold) e busca contextual BM25 com reranking opcional (wiki-retrieve).
• Formatação e metodologia — suporte para metodologias de anotações (wiki-mode), templates de marcação corretos de Obsidian Flavored Markdown (obsidian-markdown) e tabelas nativas com bancos de dados (obsidian-bases).

Um detalhe interessante: o comando wiki-mode pode organizar novas notas em sistemas populares como PARA, Zettelkasten ou LYT (Linking Your Thinking). Ao mesmo tempo, arquivos antigos são deixados intocados e ninguém tenta renomeá-los à força.

Proteção contra mãos desajeitadas e agentes paralelos

Se você der a um modelo de linguagem acesso direto ao sistema de arquivos, mais cedo ou mais tarde ele corromperá algo ou excluirá uma nota necessária. O autor de claude-obsidian considerou esse risco e projetou uma fronteira de confiança estrita.

Qualquer operação de modificação consiste em etapas seguras. Primeiro, o sistema obtém hashes SHA-256 de todos os arquivos afetados. Processos paralelos geram apenas rascunhos de alterações. Então o orquestrador monta isso em um único pacote, mostra ao usuário o plano JSON final e espera confirmação.

Só depois que você verificar o hash do plano aprovado e passá-lo ao comando --apply é que as alterações serão gravadas no disco. Se um arquivo foi modificado durante o preparo, a gravação será cancelada. Se o processo for interrompido no meio do caminho, a operação será revertida a partir do backup.

Início rápido e uso diário

É necessária a versão 3.11 ou mais recente do Python para executá-lo. Se você estiver no Windows, precisará gravar alterações através do WSL, já que a versão nativa do Windows atualmente funciona apenas em modos somente leitura e dry-run.

Clone o repositório do projeto para sua máquina:

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

Crie uma pasta separada para seu banco de dados de notas e solicite um plano de inicialização:

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

Na resposta, você verá um JSON detalhado e a linha approved_plan_sha256. Copie o hash e confirme a execução:

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<полученный-хэш>" --apply

Se você já tem um cofre Obsidian funcionando, não precisará reescrevê-lo do zero. Para isso, é fornecido o comando adopt, que adiciona cuidadosamente os arquivos de índice e tabelas necessários sem tocar no seu conteúdo pessoal.

Em seguida, abra a pasta criada no Obsidian e, pelo console, inicie o Claude Code:

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /абсолютный/путь/к/claude-obsidian

Comandos rápidos se tornam disponíveis dentro do Claude Code:

/claude-obsidian:wiki
/claude-obsidian:wiki-ingest
/claude-obsidian:wiki-lint

Jogue qualquer arquivo de texto ou artigo em inbox/ e invoque /claude-obsidian:wiki-ingest. A ferramenta fará o parsing do texto, criará os cards necessários, vinculará eles com referências cruzadas e atualizará o mapa de conhecimento geral.

Para quem este projeto é perfeito

claude-obsidian dificilmente é necessário para quem usa o Obsidian uma vez por semana para uma lista de compras. Mas o projeto será uma descoberta para aqueles que:

• Lêem muita documentação técnica, artigos e especificações que desejam salvar em um formato conveniente.
• Conduzem pesquisa de arquitetura e querem ver conexões entre diferentes tecnologias sem criar manualmente centenas de notas.
• Não estão prontos para entregar suas notas pessoais para nuvens fechadas ou se prender a formatos proprietários.

O sistema vence com sua honestidade: transações transparentes, saída limpa em Markdown e nenhuma tentativa de fazer do modelo um "oráculo onisciente". Se a rede neural não estiver confiante em um fato ou não conseguir encontrar confirmação nos arquivos salvos, ela simplesmente dirá diretamente a você.