Seu vault do Obsidian não pode ser a base de conhecimento dos seus agentes de IA

Um vault do Obsidian falha como base de conhecimento para agentes de IA por três razões estruturais: ele é privado de uma máquina, suas afirmações não trazem citações, e nada avisa quando uma nota deixou de ser verdade. Agentes leem o que recebem e não têm como distinguir uma nota atual de outra que venceu três sprints atrás — então a resposta confiante e errada e a certa chegam com a mesma cara.

Isto não é uma crítica ao Obsidian. Ele é muito bom no trabalho para o qual foi feito, que é uma pessoa pensando. A falha é um erro de categoria: uma ferramenta pessoal de pensamento sendo cobrada como fonte de verdade compartilhada.

Agentes conseguem ler um vault do Obsidian?

Conseguem, e vale esclarecer isso primeiro porque é onde a conversa costuma começar. Um vault é uma pasta de markdown puro. Qualquer agente com acesso a arquivos lê sem cerimônia, e existem servidores MCP que ligam um deles numa tarde.

O acesso nunca foi o problema. Ler e confiar são operações diferentes, e um vault não carrega nenhum sinal que as separe. Uma nota escrita semana passada e uma nota que deixou de ser verdade em 2024 são o mesmo tipo de objeto, na mesma pasta, com a mesma autoridade. Quem lê o próprio vault desconta automaticamente — ah, essa é velha — usando conhecimento que não está em lugar nenhum do arquivo. Um agente não tem com o que descontar.

Então a metade fácil é resolvida, a metade difícil passa despercebida, e o arranjo parece estar funcionando até o momento em que ele age com toda a confiança sobre algo que já tinha vencido.

As três falhas, na ordem do que custam

1. É privado, então o conhecimento é por pessoa

Um vault mora num notebook. Sincronize e você tem uma pasta compartilhada, não conhecimento compartilhado — porque o vault não tem noção de revisão. Ninguém aprova uma nota. Ninguém responde por ela. Dois engenheiros mantêm dois vaults, cada um certo sobre coisas diferentes, e o agente fica com o vault de quem estiver operando.

O sintoma é fácil de reconhecer: a mesma pergunta recebe duas respostas dependendo de quem perguntou ao agente.

2. As afirmações não têm procedência

Uma nota diz “a gente faz migrations em duas etapas.” Isso é uma decisão que alguém tomou, a observação de um incidente, ou algo em que um colega acreditava em 2024? A nota não diz, e depois de alguns meses ninguém lembra.

Para um leitor humano isso é atrito. Para um agente é fatal, porque ele não consegue pesar uma afirmação que não consegue rastrear. Ele vai seguir uma nota vencida exatamente com a mesma confiança com que segue uma correta.

3. Nada marca uma nota como vencida

Esta é a que faz mais estrago em silêncio. Um vault não tem estado de morte. As notas se acumulam, e o único mecanismo para tirar uma errada é alguém lembrar que ela está errada — o que falha com regularidade, porque quem sabe que a nota está vencida não é quem está lendo.

O resultado é um corpo de notas que cresce monotonicamente mais confiante e menos exato.

O que a documentação para agentes precisa ser?

Cada propriedade abaixo existe por causa de um jeito específico pelo qual os vaults falham:

Propriedade	A falha que ela responde
Mora no repositório	Revisada como código, não sincronizada como uma pasta
Cita uma decisão, uma task ou um arquivo	Uma afirmação que você não rastreia é uma que você não pesa
Escrita quando o trabalho fecha	Não “quando alguém lembrar”, que é nunca
Tem um estado de arquivada	Uma nota errada precisa poder sair por algo que não seja memória
Carregada pelo que a task declara	Cinquenta notas não são contexto, são ruído

Essa última linha é a que a maioria das ferramentas ignora. Entregar uma base de conhecimento inteira a um agente não é engenharia de contexto; é um prompt maior. O que uma task precisa é do subconjunto relevante para aquela task, escolhido por algo que a própria task declarou.

Por que não dar o vault inteiro para o agente?

O movimento óbvio, e ele falha de três jeitos específicos:

Volume não é contexto. Quatrocentas notas num prompt significam que as três relevantes ficam diluídas entre trezentas e noventa e sete que não são. Isso é um prompt maior, não um embasamento melhor, e custa exatidão em vez de comprá-la.

Nada diz quais notas valem aqui. Os links de um vault codificam associação — isto me lembrou daquilo — não aplicabilidade à task que está na sua frente. São relações diferentes, e só uma delas serve para escolher.

Contradições não têm desempate. Duas notas discordam sobre como se faz deploy. Nada no vault registra qual venceu, porque a vencedora foi decidida numa conversa. O agente resolve escolhendo a que mais se parece com o prompt, e relata o resultado com a mesma confiança nos dois casos.

O desfecho é pior do que um arquivo curto e curado teria sido: uma resposta bem escrita, aparentemente bem fundamentada, e errada.

RAG sobre o vault resolve?

Em parte, e vale ser preciso sobre qual parte, porque é a correção mais proposta.

A recuperação resolve a seleção. Isso é genuíno: transforma “o agente leu quatrocentas notas” em “o agente leu as quatro mais próximas”, que é uma melhora de verdade e o incômodo que mais se sente.

Ela não toca em procedência nem em validade, e na validade pende levemente para o lado errado. A recuperação traz o que está textualmente mais perto da pergunta, e uma nota vencida escrita com segurança — “a gente faz migrations em duas etapas” — costuma ser a coisa mais próxima de uma pergunta sobre migrations. A nota correta pode ser mais nova, mais cheia de ressalvas e escrita menos parecida com a pergunta. Embeddings não têm opinião sobre datas nem sobre verdade; eles ordenam por similaridade.

Então RAG promove o problema de o agente leu tudo e não sabia o que estava valendo para o agente leu as quatro coisas mais relevantes e não sabia o que estava valendo. Melhor, e não a correção.

E o Notion, o Confluence ou um wiki?

Eles respondem a uma das três falhas com clareza e deixam as outras duas mais ou menos onde estavam.

Compartilhado: sim. Este é o ganho real, e não é pouco — um corpo de notas, muitos leitores, acabou o “a mesma pergunta recebe duas respostas dependendo de qual vault o agente leu”.

Procedência: não. Uma página de wiki raramente diz de qual decisão veio ou qual incidente a produziu, pela mesma razão que uma nota de vault não diz: quem escreveu sabia, então anotar parecia redundante.

Validade: discutivelmente pior. As notas ruins de um vault pelo menos estão enterradas. As de um wiki estão indexadas, são buscáveis e linkadas de outras quatro páginas, então a escala torna uma afirmação vencida mais fácil de achar, não menos, e nada na ferramenta a arquiva. O mecanismo para tirar uma página errada continua sendo alguém lembrar.

E uma falha que o wiki acrescenta: ele não fica onde o código muda. Uma nota no repositório está na sua frente, no diff, no momento em que você altera a coisa que ela descreve. Uma nota num wiki é lida quando alguém vai procurar — que é justamente o comportamento que você estava tentando corrigir.

Como o CommitCycle faz

O CommitCycle chama isso de playbooks — arquivos de conhecimento por topic e por projeto que moram no seu repositório. Quatro propriedades, cada uma respondendo a uma linha da tabela acima:

• Eles citam. Toda afirmação aponta para uma decisão, uma task ou um arquivo. Um lint aponta a afirmação que não traz citação nenhuma — ele avisa, não bloqueia — e quando o cycle seed redige playbooks, uma afirmação que cita um arquivo que não está no repositório é descartada, e um playbook que fica sem nada citado nem chega a ser criado.
• São alimentados no fechamento do trabalho, um item por vez, enquanto a pessoa ainda lembra o porquê. Não numa retro, não quando alguém lembrar.
• São carregados pelos topics que a task declarou, então uma task sobre o banco de dados não carrega as convenções do frontend.
• Podem ser arquivados. archived é um estado real, e é isso que permite que o conjunto encolha.

E uma passada adversarial — cycle challenge — foi feita para propor as práticas que o repositório visivelmente não tem, cada uma com uma fonte nomeada. Como o cycle seed, ela precisa de um modelo configurado no board, e ainda não rodou contra um modelo de verdade. Você pode recusar, e a sua recusa fica registrada com os motivos. “A gente se desvia disso de propósito, e eis o porquê” também é conhecimento, e é do tipo que os vaults nunca capturam porque ninguém escreve o que decidiu não fazer.

A parte honesta

Aqui existe uma objeção real e ela merece resposta direta: “se você gerar um playbook a partir do meu repositório legado, isso não vai só codificar a minha bagunça?”

Vai. Por design, só descrever codifica a bagunça — com recibos. É por isso que o challenger existe: ele foi feito para propor o que falta no repo em vez de apenas descrever o que existe, e uma pessoa aceita ou recusa cada proposta. Não há aceitação automática, e um teste mantém esse caminho fechado.

O que isto não substitui

Fique com o vault. Isto não é uma migração.

O Obsidian continua melhor do que qualquer coisa aqui para pensar — para ideias pela metade, para conexões que você ainda não fez, para notas que são suas e têm permissão de estar erradas. O que sai dele é o subconjunto do qual outros leitores dependem para ser verdade. Esse subconjunto sempre foi a parte que doía quando vencia, e nunca foi a parte que o Obsidian foi projetado para segurar.

Uma linha útil de traçar: se errar sobre esta nota levaria outra pessoa a errar junto, ela não pertence a um vault pessoal.

Para onde isso vai, no caso das notas que um agente deve ler, é uma skill no repositório — o mesmo markdown, mas versionado com o código que ele descreve e carregado só quando a task pede.

Onde o CommitCycle está de verdade

O CommitCycle conduz o próprio desenvolvimento — o board, o gate, os audit records e os playbooks descritos acima estão em uso hoje no repositório dele. A metade de enforcement se instala como plugin do Claude Code; o pacote commitcycle no npm coloca a CLI cycle no seu PATH, sem o hook. O board hospedado é só por convite enquanto isto é pequeno. A Phase 0 está medida e publicada com os seus limites.

Então este post não está pedindo que você migre nada hoje. Ele faz um argumento que você pode avaliar pelo mérito, e se ele se sustentar, a waitlist é o próximo passo honesto. Se o argumento estiver errado, isso vale mais para nós do que um cadastro.

---

O resto do produto está documentado por completo: o bloco de contexto AGENTS.md, as zones e o audit record.