Codex Technomanticus

Por que Obsidian e markdown como substrato

Leitura de 8 min

Por que Obsidian e markdown como substrato

TL;DR

Markdown + Obsidian é o substrato natural para memória de agentes em 2026. As razões são concretas: o conteúdo é humano-legível (e quem opera o agente pode revisar o que o LLM escreveu sem ferramenta especializada), versionável em git (diff, blame, rollback gratuitos), portável (zero vendor lock-in), e o grafo emerge sozinho via wikilinks. Obsidian funciona como IDE — graph view, backlinks, dataview — sem ser pesado. O ponto-chave: o mesmo formato é lido e escrito tanto por humano quanto por LLM. O servidor MCP basic-memory é evidência prática: ele expõe um vault Obsidian para o LLM sem conversão de formato. Quando o substrato é o mesmo, a colaboração humano↔agente para de exigir tradução.

O que é

Substrato, no contexto de memória de agentes, é o formato físico em que o conhecimento vive em disco — o nível abaixo da arquitetura de camadas, abaixo do schema, abaixo da estratégia de retrieval. É o que sobra quando se desliga o agente: arquivos. A escolha desse formato decide o que o sistema consegue fazer com baixo atrito e o que vira fricção crônica.

A proposta de markdown como substrato é peculiar por um motivo: é o mesmo formato textual servindo humano e LLM, em escrita E em leitura. O humano abre o arquivo num editor qualquer, lê, edita, comenta. O LLM abre o mesmo arquivo, lê, edita, comenta. Não há fase de export, transformação ou projeção entre representações — o que está em disco é o que o agente vê. Não é a única opção viável (vector DB puro, JSON, SQL, knowledge graphs dedicados são alternativas legítimas), mas markdown captura a maior parte do valor com simplicidade radical, e essa simplicidade é o que torna o pattern adotável.

Por que importa

A escolha de substrato é uma decisão arquitetural de longa duração — uma vez que a wiki tem milhares de entradas, migrar custa caro. E substrato impacta dimensões que só aparecem com o tempo: legibilidade do conteúdo gerado pelo LLM, versionamento das mudanças, portabilidade entre máquinas e ferramentas, capacidade de revisão humana sob estresse, custo de saída quando o vendor da ferramenta muda termos.

Em sistemas de memória que evoluem por anos, esses fatores são amplificados. Um vault que cresce devagar mas continuamente acumula valor exponencial — e qualquer fricção (não conseguir abrir num editor, não ter histórico, não conseguir migrar) compõe junto com o valor. Escolher mal é pesadelo de migração; escolher bem é uma decisão que se paga sozinha.

O gist de Karpathy explicita markdown como escolha deliberada, não acidental. A frase canônica é “Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase” — e o paralelo com código-fonte não é decorativo. Código-fonte vive em arquivos texto justamente pelas mesmas razões: legibilidade, diff em git, portabilidade, ausência de lock-in. Conhecimento mantido por LLM herda os mesmos requisitos.

Como funciona — vantagens enumeradas

São oito vantagens concretas que se reforçam mutuamente. Nenhuma delas isoladamente justifica a escolha; o conjunto, sim.

  1. Humano-legível. Abrir um arquivo .md num editor qualquer e entender o conteúdo sem parser, sem ferramenta proprietária, sem build step. Em sistemas onde o LLM escreve a maior parte do conteúdo, isso é crítico: quem opera precisa revisar o que o agente produziu com baixa fricção. Conteúdo ilegível por humano vira caixa-preta — e caixa-preta gerada por LLM é receita para erro silencioso virar dogma.

  2. Versionável em git. Diff por mudança, rollback de um lint que correu mal, branching para experimentar reorganizações, blame para descobrir quando determinada afirmação entrou. Knowledge base como código — com todas as práticas maduras que o ecossistema git acumulou em duas décadas. Em vector DBs, “diff” não é uma operação natural.

  3. Portável. Zero vendor lock-in real. Os arquivos abrem em qualquer editor (VSCode, Sublime, Vim, Notepad), em qualquer SO, em qualquer ano. Obsidian é apenas uma das views possíveis sobre o conteúdo — se o Obsidian fechar amanhã, o vault continua acessível. Comparar com uma base proprietária num SaaS que pode mudar API, encerrar o produto ou aumentar preço unilateralmente.

  4. Grafo emergente. Wikilinks [[Nota X]] formam um grafo sem schema explícito de relacionamentos. Backlinks são gratuitos — Obsidian computa quem aponta pra cada nota automaticamente. Diferente de knowledge graphs dedicados (Neo4j, Memgraph), aqui o grafo cresce como subproduto da escrita normal, sem necessidade de modelar entidades e arestas a priori.

  5. Obsidian como IDE. Graph view para visualização, backlinks no painel lateral, dataview para queries declarativas, plugins para tudo (lint, search semântico, exportadores, integrações com agents). É ferramenta poderosa sem ser pesada — instalação local, sem servidor, arquivos seus. O Obsidian é gratuito para uso pessoal e o Sync é opcional.

  6. Formato compartilhado humano↔LLM. O mesmo arquivo .md é lido e escrito por humano e por agente. Nada de “exportar para o agent” ou “importar a resposta do agent”. O servidor basic-memory (MCP nativo Obsidian) é prova de conceito viva: aponta o agente para o vault e ele opera diretamente nos arquivos que o humano também edita. Eliminação de fronteira entre formatos é eliminação de bug surface.

  7. Frontmatter como metadata estruturada. Tags, status, type, datas, aliases, autoria — tudo em YAML no topo do arquivo, sem banco de dados separado. Plugins como dataview consultam esse metadata como se fosse SQL sobre uma tabela. Metadata e conteúdo no mesmo arquivo significa que mover, copiar ou versionar uma nota leva tudo junto, sem joins quebrados.

  8. Compatibilidade com Quartz e static sites. Publicação direta da wiki via render estático (Quartz, MkDocs, Hugo, Astro). O vault é também a fonte do site público — sem pipeline de export complexo. Notas com publish: true viram páginas; notas privadas ficam no vault. Continuidade de formato entre nota privada e página publicada reduz drasticamente o atrito de compartilhar conhecimento.

Quando NÃO usar markdown

Markdown não é universal. Há cenários em que outro substrato ganha por critérios objetivos.

  • Dados estruturados em escala — quando o sistema lida com milhões de registros tabulares e queries complexas (joins multi-tabela, agregações, filtros profundos), banco de dados relacional ou de grafo é melhor. Markdown não foi feito pra ser questionado em SQL.
  • Transações ACID — markdown em arquivos não suporta consistência transacional. Se múltiplos agentes escrevem ao mesmo arquivo concorrentemente, o melhor que se tem é file locking ad-hoc. Sistemas que precisam de garantias de consistência forte (financeiro, regulatório) precisam de DB transacional.
  • Relacionamentos densos com queries de grafo profundas — quando o caso de uso central é “encontre todos os nodes a 3 hops de X que satisfazem propriedade Y”, knowledge graph dedicado (Neo4j, Memgraph, ArangoDB) ganha. Wikilinks dão grafo, mas não dão Cypher.
  • Conteúdo binário pesado — imagens, vídeos, áudio, datasets grandes. Markdown referencia esses arquivos, mas o storage real precisa estar em outro lugar (filesystem, S3, CDN). Vault Obsidian não é blob storage.

A regra é simples: markdown ganha quando o caso de uso central é conhecimento conceitual interligado, mantido por humano e LLM, com horizonte de anos. Para casos fora desse perfil, escolha o substrato adequado e prossiga.

Armadilhas comuns

Riscos práticos do substrato markdown

Markdown é simples, mas vault sem governance vira lixão. Os pontos abaixo já fizeram vaults bem-intencionados degenerarem.

  • Vault sem convenção vira lixão. Sem schema (CLAUDE.md, AGENTS.md ou similar), o LLM espalha conteúdo sem coerência: notas duplicadas, naming divergente, pastas órfãs. A simplicidade do markdown não dispensa documento de regras — ela apenas torna mais barato corrigir quando se decide arrumar.
  • Wikilinks quebrados acumulam. Renomear uma nota sem ferramenta adequada quebra wikilinks que apontavam para ela. Sem lint regular ou plugin de detecção (Obsidian Linter, Broken Link Finder), os links quebrados acumulam silenciosamente até a wiki perder coerência interna.
  • Frontmatter inconsistente complica dataview. Schema YAML divergente entre notas — tag vs tags, created vs date, valores em formatos diferentes — torna queries dataview difíceis ou impossíveis. Definir o schema do frontmatter no documento de regras desde o início economiza retrabalho.
  • Confiar que “markdown é simples = sem manutenção”. Vault grande exige governance: lint regular, naming convention documentada, taxonomia de tags estável. A simplicidade do substrato não se transfere automaticamente para o sistema. Manutenção continua sendo trabalho.
  • Misturar conteúdo público e privado no mesmo vault sem separação. Risco real de vazar dados sensíveis numa publicação Quartz ou ao compartilhar o vault. Convenção de publish: true/false no frontmatter, isolamento por pasta, ou vaults separados são opções — qualquer uma serve, desde que adotada antes do primeiro vazamento.

Veja também

Referências

  • Karpathy, gist oficial — https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f — analogia compiler/source-code/executable; markdown apresentado como escolha deliberada de substrato; “Obsidian is the IDE”.
  • basic-memory — Obsidian integration — https://docs.basicmemory.com/integrations/obsidian — argumentos de markdown nativo, leitura/escrita compartilhada humano↔LLM via MCP, ausência de conversão de formato.
  • Obsidian Help — https://help.obsidian.md/ — referência oficial sobre wikilinks, frontmatter (Properties), graph view e plugins. Documenta o que torna o Obsidian uma IDE viável para markdown.
  • Quartz documentation — https://quartz.jzhao.xyz/ — gerador estático que publica vaults Obsidian, evidência prática de continuidade entre nota privada e página publicada.

Visão de gráfico

Backlinks