Como Evoluí Meu Segundo Cérebro para o Claude Code com Pastas Semânticas e Wikilinks

Há algumas semanas publiquei sobre como criei um segundo cérebro compartilhado para o Claude Code. A ideia era simples: Git + symlinks + Obsidian para sincronizar a memória entre máquinas. Funcionou.

Mas depois de meses de uso real, o sistema começou a mostrar suas limitações. Este post é sobre como identifiquei os problemas e o que fiz para resolver.

O que aconteceu depois de 3 meses

O vault cresceu de 31 para mais de 40 arquivos. Notas sobre projetos, incidentes de segurança, inteligência competitiva, decisões de arquitetura, feedback pessoal — tudo misturado numa pasta flat.

O MEMORY.md, que era o index do Claude Code, ficou inchado. Toda vez que o agente iniciava uma conversa, ele carregava a lista completa de memórias no contexto — gastando tokens com informações irrelevantes para a tarefa do momento.

Pedir "reinicia o nginx" não deveria exigir carregar notas sobre Meta Ads.

A inspiração: OpenClaw Brain Guide

Encontrei o OpenClaw Brain Guide — um projeto do Matheus Soier que usa OpenClaw + Obsidian + Syncthing para criar um sistema parecido com o meu, mas com diferenças importantes na arquitetura.

Comparei as duas abordagens:

Cada um tem pontos fortes. O Git dá histórico completo e merge resolution robusto. O Syncthing é P2P puro, sem intermediário. O mcpvault permite busca semântica. Os wikilinks economizam tokens.

O que fiz: combinei o melhor dos dois.

Melhoria 1: Pastas semânticas

Reorganizei os 40+ arquivos flat em pastas com significado:

brain/
├── index.md          # entry point com wikilinks
├── MEMORY.md         # index do Claude Code
├── projects/         # projetos ativos (hubnews, papeou, reino...)
├── intel/            # inteligência competitiva
├── deep-dives/       # análises detalhadas
├── references/       # docs e referências técnicas
├── incidents/        # registro de incidentes
├── feedback/         # preferências e feedback
├── daily/            # checkpoints diários (auto-gerados)
├── templates/        # templates de notas
└── maintenance/      # scripts de manutenção

Usei git mv para mover tudo, mantendo o histórico. Cada pasta tem um propósito claro. Quando o Claude Code precisa de contexto sobre um projeto, vai em projects/. Investigando um incidente? incidents/. Precisa de uma referência técnica? references/.

Melhoria 2: index.md com wikilinks

Antes, o MEMORY.md listava todas as memórias de forma linear. Agora, o index.md funciona como um mapa de navegação com wikilinks do Obsidian:

# Brain Vault

## Projetos Ativos
- [[projects/hubnews]] — HubNews.ai (Laravel + Next.js)
- [[projects/papeou]] — Papeou SaaS
- [[projects/sistema-reino-growth]] — Sistema Reino

## Incidentes
- [[incidents/malware-20260218]] — Malware (Fev 2026)

## Referências
- [[references/brain-vault]] — Como este sistema funciona

O agente entra pelo index, segue os links conforme precisa, e carrega só o que é relevante. Isso é o que o OpenClaw chama de progressive disclosure — e é a melhoria que mais impactou o uso de tokens.

Melhoria 3: Manutenção automatizada

Inspirado pelo nightly maintenance do OpenClaw, criei um script bash que roda toda noite às 23:00 UTC:

# /root/brain/maintenance/nightly-brain.sh
# Cron: 0 23 * * *

O que ele faz:

1. Detecta notas órfãs — arquivos que nenhuma outra nota referencia via wikilink
2. Gera checkpoint diário — um arquivo daily/2026-03-23.md com resumo do que mudou
3. Valida o sync — confirma que o git está sincronizado com o remote

O checkpoint diário é útil. Quando o Claude Code precisa de contexto sobre "o que aconteceu ontem", ele lê o checkpoint em vez de vasculhar o histórico do git. Mais rápido, menos tokens.

Melhoria 4: Progressive disclosure na prática

Antes:

• Agente inicia → carrega MEMORY.md (40+ referências) → gasta ~2k tokens só no contexto inicial

Depois:

• Agente inicia → carrega MEMORY.md (resumo + vault structure) → segue wikilinks conforme necessário

Uma tarefa de deploy só abre [[projects/hubnews]]. Uma investigação de incidente abre [[incidents/malware-20260218]]. O contexto é carregado sob demanda.

O que mantive diferente do OpenClaw

Nem tudo do OpenClaw fazia sentido para o meu setup:

1. Git em vez de Syncthing — Mantenho Git + GitHub. O histórico de versões e o merge resolution são insubstituíveis. Se um conflito acontece entre o servidor e o notebook, o git resolve. O Syncthing pode ter conflitos silenciosos.

2. mcpvault MCP — Mantenho a busca semântica via MCP. O OpenClaw navega só por wikilinks, o que funciona mas é limitado quando você não sabe exatamente onde a informação está. O mcpvault permite buscar "qual foi o incidente de segurança?" e encontrar o arquivo certo.

3. Symlinks — O truque do symlink (memória do Claude Code → repositório git) continua sendo a peça mais elegante da arquitetura. Zero configuração no agente, zero middleware.

O resultado

O vault agora tem:

• 9 pastas semânticas organizadas por função
• index.md como entry point navegável
• Manutenção noturna automática com detecção de órfãos
• Checkpoints diários auto-gerados
• Progressive disclosure que economiza tokens

E mantém tudo que já funcionava:

• Sync via Git a cada 5 minutos
• Obsidian nos computadores pessoais
• mcpvault para busca semântica
• Custo total: zero

Para quem já implementou o setup original

Se você seguiu o post anterior e já tem um vault funcionando:

# 1. Criar pastas
mkdir -p ~/brain/{projects,intel,deep-dives,references,incidents,feedback,daily,templates,maintenance}

# 2. Mover arquivos (use git mv para manter histórico)
git mv arquivo.md projects/

# 3. Criar index.md com wikilinks

# 4. Criar script de manutenção
# (código completo no repositório)

# 5. Instalar cron
(crontab -l; echo "0 23 * * * ~/brain/maintenance/nightly-brain.sh") | crontab -

O setup leva 15 minutos se você já tem o vault rodando.

O que vem a seguir

Duas coisas que ainda quero implementar:

1. RAG (Retrieval-Augmented Generation) — Busca por significado em vez de palavras-chave. O MCP server knowledge-rag já existe, só falta integrar.
2. Graph view automático — Gerar uma visualização do grafo de notas acessível via web, sem precisar do Obsidian aberto.

Mas isso fica para o próximo post.