Toda sessão do Claude Code começa do zero. É o combinado — você abre um terminal, o modelo lê o repositório, e tudo que vocês resolveram juntos na terça passada evaporou. Você reexplica a arquitetura. Reexplica por que descartou a abordagem óbvia. Reexplica de novo na semana seguinte.
Durante quase um ano eu resolvi isso do jeito que todo mundo resolve: não resolvendo. Voltava nas conversas antigas quando precisava de alguma coisa, achava talvez metade das vezes, e re-deduzia o resto. O caro era o re-deduzir. Não a digitação — o fato de o Claude propor com toda a confiança justamente aquilo que eu já tinha tentado e jogado fora, e eu precisar lembrar por quê antes de conseguir dizer não.
Então construí um segundo cérebro. É um vault do Obsidian em ~/Brain, versionado num repositório git privado, e é a memória de longo prazo de todo agente que eu rodo. Hoje são umas 370 notas. Este post é sobre por que ele tem o formato que tem — as regras que fazem funcionar e as que eu errei primeiro.
Por que arquivos, e não histórico de conversa
A alternativa óbvia é confiar na própria plataforma de chat. Quase todas hoje têm alguma memória: o assistente percebe algo que vale guardar e guarda pra você. É genuinamente útil. Só não era o que eu precisava, por três motivos.
Não é meu. A memória de chat vive dentro de um produto. Meu trabalho passa pelo Claude Code no terminal, pelo Claude na web e por um agente rodando numa VM aqui em casa. Uma memória que só um deles consegue ler não é memória, é cache. O vault é uma pasta de arquivos Markdown — os três conseguem ler, o grep lê, e eu leio num avião sem internet.
Não dá pra revisar o que não dá pra ver. Memória hospedada decide o que vale lembrar e te mostra um resumo. Eu quero abrir o arquivo. Quero ver o diff quando um agente edita, e quero que o git log me diga quem escreveu o quê e quando. Três autores mexem no meu vault — eu, o Claude e o agente da VM — e o git é a única razão pela qual eu confio em qualquer coisa ali. Quando tem algo errado, eu acho o commit que errou.
O difícil não é recuperar, é estruturar. Esse foi o que demorei mais pra aceitar. O valor do vault não é conseguir achar coisas — uma boa busca no histórico de conversa também acha. O valor é que escrever uma nota obriga a decisão a ser dita em voz alta. "Escolhemos X em vez de Y por causa de Z, nesta data." Essa frase não existe no seu histórico. Ela existe no vão entre quatro mensagens, e nenhum sistema de recuperação reconstrói isso com fidelidade. O arquivo torna a decisão real.
Tem um quarto motivo, menos nobre e mais prático: o Obsidian já é onde eu penso. O vault não é um artefato de agente que eu visito pra fazer manutenção. É o mesmo lugar onde escrevo notas de leitura e planejo a semana, e os agentes por acaso também escrevem lá. Se fosse um repositório separado, exclusivo de agente, eu teria parado de abrir em um mês.
Compartimentos, e por que eles nunca se cruzam
O vault tem um compartimento por contexto de trabalho — o trabalho atual, engajamentos passados, minha própria empresa, a vida pessoal. Mais o _shared/.
A regra é dura: uma sessão montada em um compartimento usa só aquele compartimento, e não existe wikilink entre compartimentos. Não é "de preferência não". É nenhum.
Isso começou como cautela e acabou sendo a melhor decisão estrutural do sistema inteiro. Por dois motivos — e o segundo me surpreendeu.
O primeiro é o óbvio. Contextos de trabalho diferentes carregam obrigações de confidencialidade diferentes, e essas obrigações não expiram quando o engajamento termina. Se uma sessão trabalhando em um contexto consegue alcançar material de outro, eu criei exatamente o vazamento que eu mandaria uma pessoa júnior evitar. Isolamento por pasta é grosseiro, mas grosseiro e aplicável ganha de elegante e aspiracional: quando abro uma sessão contra um compartimento, não existe mecanismo pelo qual algo de fora dele chegue.
O segundo motivo é que isso deixa as notas melhores. Uma nota que pode linkar pra qualquer lugar tende a virar uma nota sobre tudo. Quando os únicos links disponíveis estão dentro de um compartimento, a nota precisa se sustentar sozinha naquele contexto — precisa dizer o que significa nos termos daquele contexto, sem se apoiar numa definição que mora três pastas adiante. É a mesma disciplina de um módulo com API pública estreita. Restrinja as bordas e o miolo fica mais claro.
E o conhecimento que é genuinamente geral? Um padrão de cache não pertence a ninguém. É pra isso que serve o _shared/ — material de carreira, convenções da casa, templates, receitas de ferramenta e um zettelkasten pequeno de conceitos atemporais. É a única ponte, e atravessar ela custa de propósito. Pra promover uma lição pro _shared/, você tem que tirar dela os específicos que a prendiam a um contexto. Que é exatamente o trabalho que transforma "o job de sincronização deu race" em algo reaproveitável. O atrito aqui é a funcionalidade, não o defeito.
A linha sobre o que entra
Essa é a regra que mais reescrevi, e a parte interessante não é a redação atual — é por que a primeira versão falhou.
A versão um era uma proibição seca: nada de específico, nunca. Só padrões genéricos.
Soa responsável. Não funciona, e a razão vale a pena entender se você está escrevendo regras pra si mesma ou pra um agente. Uma nota despida de todo específico não é uma nota cautelosa, é uma nota inutilizável. "O serviço upstream naquele domínio se comportou de forma inesperada" não é conhecimento, é charada — eu leria aquilo seis semanas depois sem a menor ideia do que apontava. E uma regra cujo produto não serve pra nada não é seguida com cuidado. É seguida com desleixo, ou abandonada em silêncio, e aí você tem uma regra que ninguém aplica mais a ilusão confortável de que algo está sendo aplicado. Isso é estritamente pior do que não ter regra.
Então parei de escrever proibições e escrevi uma instrução de reescrita:
Fique com o insight, jogue fora o identificador.
A diferença é tudo. Uma proibição te diz pra não escrever algo e te deixa sem nada. Uma instrução de reescrita te diz o que escrever no lugar — e a nota reescrita é quase sempre a melhor nota, porque a forma geral sobrevive à instância. "Aquele job falhou na terça naquela conta" é um chamado de suporte. "Jobs com esse formato falham quando o upstream assume uma ordenação que ele não controla" é conhecimento, e é o que eu de fato quero seis meses depois.
É por isso que essa versão se sustenta onde a proibição não se sustentou. Não é disciplina contra o meu próprio interesse. Segui-la deixa o vault mais afiado, então não tem com o que brigar.
E aí as fronteiras duras — as categorias onde a resposta é não, por mais útil que a nota fosse:
- PHI e PII de pacientes ou clientes finais. Nomes, datas de nascimento, contatos, prontuários, ou capturas de tela que mostrem isso. Sem exceção e sem "anonimizado o suficiente".
- Artefatos que não fui eu que escrevi. Decks, PDFs, especificações, código-fonte. Minhas próprias notas são minhas pra guardar; o arquivo de outra pessoa não é meu pra segurar, por mais conveniente que fosse.
- Credenciais vivas e identificadores de infraestrutura. Tokens, connection strings, IDs de conta, hostnames internos. Anote onde a coisa mora, nunca o que ela é.
- Detalhe de segurança. Que existe uma classe de problema, e qual ticket acompanha. Essa é a nota inteira. Mecânica nunca entra num repositório pessoal.
- Dados pessoais de terceiros. Salário, saúde, avaliações de contratação ou de desempenho de outras pessoas. Os meus, tudo bem. Os delas não são meus pra guardar.
A decisão de projeto que sustenta tudo isso é que vale na hora da escrita, não na hora da revisão. Um repositório de conhecimento não tem desfazer — o que foi commitado fica no histórico independentemente de você apagar o arquivo depois, então "eu limpo isso na triagem" nunca foi um plano de verdade. O filtro tem que rodar antes de a nota existir. E é exatamente por isso que ele é formulado como instrução de reescrita e não como checklist: é barato o bastante pra aplicar no meio da frase, e uma verificação cara de rodar é uma verificação que não roda.
As regras de escrita que fazem o trabalho de verdade
Estrutura é barata de projetar e cara de manter. Três regras seguram quase todo o peso.
Decisão vira arquivo datado
decisions/AAAA-MM-DD-slug.md. Uma decisão, um arquivo, data no nome.
É a convenção de maior valor do vault e é quase constrangedoramente simples. A data no nome faz a cronologia sobreviver sem banco de dados — eu vejo o que eu acreditava em março e o que mudou até julho. Substituir uma decisão não significa editar o passado, significa escrever um arquivo datado novo que referencia o antigo. A crença antiga continua visível, e isso importa, porque "por que a gente parou de fazer daquele jeito" é uma pergunta que eu faço muito mais do que "o que a gente faz".
E dá um alvo concreto pros agentes. Quando eu digo "vamos de fila em vez de polling", a resposta não é um aceno — é um nome de arquivo proposto. Isso é um contrato bem melhor que "vou lembrar disso".
00-inbox/ é estacionamento, não default
Essa é a regra que eu errei por meses, e é a que eu defenderia com mais força pra quem for construir a mesma coisa.
O desenho intuitivo é uma caixa de entrada de captura: tudo cai ali, você tria semanalmente, as notas fluem pros lugares definitivos. Todo sistema de produtividade já inventado funciona assim. O meu também funcionava.
O que acontece de verdade é que a caixa de entrada vira o sistema. Arquivar é trabalho adiado, trabalho adiado acumula, e na sexta-feira tem quarenta notas cujo contexto eu já perdi. A triagem deixa de ser arquivamento e vira arqueologia — ler minha própria nota de terça e tentar reconstruir qual conversa gerou aquilo e se ainda é verdade. Fiz essa varredura umas três vezes antes de parar caladinha, e aí a inbox virou só o lugar onde notas iam morrer. O sistema tinha uma pilha de compostagem no centro.
Então inverti. Conhecimento durável é arquivado direto no compartimento dele, no momento em que é produzido. O agente propõe o caminho exato do arquivo, eu confirmo, ele escreve lá — pasta certa, tags certas, commitado e enviado. O 00-inbox/ hoje só é usado quando eu digo explicitamente "estaciona isso", ou seja, quando decidi que aquilo precisa de um pensamento que eu não quero fazer agora. Essa é uma categoria real e merece uma pasta. Ela só não é a pasta padrão.
A prova está na contagem. Minha inbox tem três arquivos. No modelo antigo ela nunca teve menos de trinta.
Teve um corolário que precisei acrescentar depois: notas de erro de agente e status de ferramenta também não vão pra inbox. Elas estavam inundando a pasta com coisas que eu nunca escolhi estacionar, o que me levava de volta a ignorar a pasta. Agora vão pra caixa de saída do próprio agente. A inbox só guarda o que eu decidi adiar — que é a única forma de eu continuar confiando nela o suficiente pra abrir.
Arquive na hora em que produz
Ligada à anterior, mas mais ampla, e mirada no agente e não na pasta: não estoque.
O modo de falha é uma sessão que trabalha bem por duas horas e no final oferece escrever o que aprendeu. A essa altura o resumo é o resumo de um resumo. A razão específica pela qual descartamos a segunda abordagem — justamente o que seria mais valioso pra mim-do-futuro — foi comprimida pra fora três passos atrás, porque na hora parecia detalhe.
Hoje a instrução é: quando algo durável for produzido, proponha o destino imediatamente e arquive assim que eu confirmar. No meio da sessão, com o raciocínio ainda no contexto. Interrompe um pouco o fluxo. Vale a pena, porque nota escrita no momento da decisão contém o porquê, e nota escrita no fim da sessão contém o o quê. O "o quê" dá pra recuperar do código. O "porquê" nunca.
Tudo termina com commit e push, no mesmo fôlego da escrita. Não enviado é não salvo. Perdi um conjunto de repositórios que só existiam localmente numa migração de máquina ano passado e virei uma pessoa chata quanto a isso.
No que ele é ruim
A seção honesta, porque já li post de segundo cérebro demais que termina na volta olímpica.
Compartimentar impede síntese de verdade. Esse é o custo que eu sinto na pele, não uma hipótese. Algumas das coisas mais úteis que eu sei são padrões que já encontrei em vários lugares diferentes — o mesmo erro de arquitetura, a mesma falha organizacional, com roupa diferente a cada vez. O vault estruturalmente não consegue me mostrar isso. Cada instância fica numa pasta lacrada, e nenhum agente vai jamais trazer a terceira e me dizer que ela tem o mesmo formato da primeira. O _shared/ é a saída de emergência, mas só funciona se eu perceber o padrão e promover na mão. E perceber é exatamente a parte em que eu queria ajuda. Não tenho solução que não comprometa o isolamento, então eu pago esse preço.
Exigir confirmação em toda escrita me põe de volta no loop do qual eu queria sair. Os agentes propõem um destino e esperam meu sim. É o default certo — não vou deixar agente escrevendo sem supervisão em algo pelo qual eu respondo, e o filtro de hora-da-escrita só funciona se uma pessoa o executa. Mas isso significa que o vault só cresce na velocidade em que eu aprovo coisas, e em dia corrido eu não aprovo nada. O sistema de memória tem um gargalo, e o gargalo sou eu.
Nada nunca é apagado. As notas acumulam e nenhuma decai. Não existe processo que sinalize uma decisão de oito meses atrás que está silenciosamente falsa desde março. Substituir é manual, então nota velha fica ali parecendo tão autoritativa quanto nota nova, e um agente que recupera as duas não distingue. Esse é o modo de falha com maior chance de me morder de verdade — recuperação confiantemente errada é pior que recuperação nenhuma, e até aqui eu tenho tido sorte, não cuidado.
Só compensa se você já mora nas suas notas. O vault funciona pra mim porque o Obsidian já era onde eu pensava. Se eu tivesse construído isso como repositório dedicado de memória de agente, teria parado de abrir em um mês e hoje seria uma pasta velha mentindo pros meus agentes. Encaixe esse padrão num hábito que você já tem, não num que você pretende adquirir.
O que eu mudaria
Se eu reconstruísse amanhã: colocaria decaimento. Alguma noção de frescor em cada nota — última verificação, confiança, um cutucão quando um arquivo de decisão passa seis meses intocado numa área que claramente andou. Não exclusão automática. Só um sinal, pra que a recuperação consiga pesar conhecimento recente acima de conhecimento antigo e confiante, em vez de tratar os dois como igualmente verdadeiros.
E eu quereria um loop de revisão que não fosse eu. Algo que periodicamente lesse um compartimento e perguntasse: o que aqui dentro contradiz outra coisa aqui dentro? O isolamento por compartimento torna isso tratável — o espaço de busca é uma pasta só — e contradição é bem mais fácil de detectar do que obsolescência. Ainda não construí. É a próxima coisa.
O ganho de verdade
O que eu não previa é que o vault mudou como as sessões começam, não como elas terminam.
Eu abria uma sessão e gastava os dez primeiros minutos reconstruindo contexto em voz alta — o sistema é assim, já tentamos aquilo, a abordagem óbvia não funciona aqui por isso. Hoje a sessão abre contra um compartimento e esse contexto já está em disco. A primeira mensagem pode ser a pergunta de verdade.
E o efeito composto é real, num sentido bem específico: a resposta pra "a gente já discutiu isso?" hoje é um caminho de arquivo em vez de um dar de ombros. Essa pergunta me custava vinte minutos de rolagem e geralmente terminava em re-dedução. Hoje custa uma busca.
Nada disso veio do Obsidian. O Obsidian é um editor de Markdown. Veio de quatro regras — uma pasta por contexto e nenhum link entre elas, fique com o insight e jogue fora o identificador, decisão vira arquivo datado, e arquive no momento em que produz. A ferramenta é substituível. As regras não são.