FAQ — Open Knowledge Format (OKF)

Perguntas frequentes sobre o OKF, respondidas com honestidade e sem enrolação.

O que é OKF?

OKF (Open Knowledge Format) é uma spec aberta pra representar conhecimento — metadados, contexto e insights curados — de forma que humanos leiam sem ferramentas e agentes de IA consumam sem SDKs proprietários.

Na prática: uma pasta de arquivos Markdown com YAML frontmatter. Cada arquivo é um “conceito” (tabela, métrica, playbook, API). Estrutura hierárquica, versionável com git, simples ao ponto de um cat arquivo.md já te mostrar tudo.

As regras obrigatórias cabem em três linhas:

1. Todo .md (exceto index.md e log.md) precisa de frontmatter YAML parseável
2. Todo frontmatter precisa ter campo type não-vazio
3. Arquivos reservados (index.md, log.md) seguem estrutura definida

Fora isso? Liberdade total. Organiza os conceitos como quiser.

Quem criou o OKF?

Sam McVeety e Amir Hormati (Tech Leads, Data Analytics Engineering, Google Cloud) projetaram e anunciaram o OKF em 12 de junho de 2026 via Google Cloud Blog.

Publicado sob Apache 2.0. O repositório canônico é GoogleCloudPlatform/open-knowledge-format. O caminho original knowledge-catalog/okf/ agora é um snapshot congelado usado para tooling do Knowledge Catalog; use o repo novo pra spec atual e implementações de referência.

Nasceu no contexto do Knowledge Catalog (antigo Dataplex) — plataforma de catálogo de dados com IA do Google Cloud. Mas a spec é vendor-neutral: não exige Google Cloud, não tem dependência de produto, qualquer organização adota.

Versão atual: v0.2 (publicada jul 2026), que adiciona trust signals (sources, generated, verified, status, stale_after) para rastreamento de proveniência. Bundles produzidos na v0.1 continuam válidos e conformantes.

O que é o pattern “LLM Wiki”?

OKF formaliza um pattern que reaparece sob diferentes nomes: dar a agentes de IA uma biblioteca compartilhada em Markdown que fica mais útil com o tempo.

Andrej Karpathy articulou a ideia com clareza no seu LLM Wiki gist: “LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass.” A burocracia que faz humanos abandonarem wikis pessoais é exatamente o que LLMs fazem bem.

O mesmo pattern aparece como vaults Obsidian conectados a coding agents, a família de arquivos AGENTS.md / CLAUDE.md, repos cheios de index.md e log.md que agentes consultam antes de agir, e repositórios “metadata as code” dentro de times de dados.

O problema: cada instância é artesanal. O wiki do Karpathy e o wiki do seu time podem parecer iguais (markdown, frontmatter, cross-links), mas nenhum foi desenhado para interoperar com outro. Não existe acordo sobre quais campos todo documento deveria ter.

OKF é a camada de interoperabilidade que faltava. Define o set mínimo de convenções pra que wikis de diferentes produtores sejam consumidos por diferentes agentes sem tradução.

Precisa de SDK?

Não. Essa é uma das filosofias fundadoras do OKF.

A spec é explícita: “If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.”

Pra produzir OKF: um editor de texto. Pra consumir OKF: saber ler Markdown. Pra validar: checar 3 regras simples (frontmatter YAML parseável, campo type presente, arquivos reservados com estrutura certa).

Existem ferramentas que facilitam (validadores, geradores de index.md, enrichment agents). Mas nenhuma é requisito. Esse é o ponto.

Qual a diferença pro AGENTS.md?

Propósitos bem diferentes:

AGENTS.md diz ao agente como se comportar. OKF diz ao agente o que existe no mundo — quais tabelas, métricas, APIs, playbooks, processos.

São complementares: seu AGENTS.md pode instruir o agente a “consultar o bundle OKF em /knowledge” pra entender o domínio.

E pro Obsidian?

Obsidian e OKF compartilham DNA — ambos usam Markdown hierárquico com frontmatter e cross-links. Mas o propósito diverge:

Obsidian é ferramenta de personal knowledge management. Notas pessoais, second brain, zettelkasten. Formato proprietário de links ([[wikilinks]]), plugins, graph view — tudo voltado pra um humano individual.

OKF é spec de intercâmbio. O objetivo: um bundle produzido pela equipe A ser consumido pela equipe B (ou agente C) sem perda de informação. É a diferença entre suas anotações pessoais e um manual técnico publicado.

Na prática:

• Links no OKF são Markdown padrão ([texto](caminho.md)), não wikilinks
• OKF exige campos obrigatórios no frontmatter (type é mandatório)
• OKF tem index.md e log.md como arquivos reservados com estrutura definida
• OKF é pensado pra agentes de IA consumirem programaticamente

Dá pra editar bundles OKF no Obsidian sem problema nenhum. Mas OKF não é Obsidian — é formato portável que roda em qualquer lugar.

E pro DESIGN.md?

DESIGN.md é tipicamente um documento único descrevendo decisões arquiteturais, design system, ou design de um componente. É um documento, não um formato.

OKF é formato estruturado com regras de conformidade, hierarquia de conceitos, cross-links, e suporte a múltiplos tipos de conhecimento.

Se o DESIGN.md virasse OKF, seria um conceito dentro de um bundle — talvez type: Architecture Decision ou type: Design Document. OKF é o container; DESIGN.md é algo que vive dentro dele.

Posso usar com Claude/GPT/Gemini?

Sim, todos. Esse é o ponto inteiro.

OKF é Markdown + YAML. Qualquer LLM que leia texto (todos, portanto) consome bundles OKF nativamente. Zero lock-in de provider.

Na prática:

• Claude/Cursor: Jogue o bundle no contexto do projeto. O agente entende quais tabelas existem, como se relacionam, quais métricas importam.
• GPT/ChatGPT: Upload dos .md ou ZIP do bundle. O modelo navega pelos conceitos.
• Gemini: Integração natural via Knowledge Catalog, mas funciona standalone também.
• Qualquer agente MCP: Bundle pode ser servido como recurso via MCP.

A spec foi feita pra ser “parseable by agents without bespoke SDKs” — agnosticismo de modelo é requisito fundacional.

Como validar um bundle?

Validar OKF v0.1 = checar 3 regras.

As 3 regras de conformidade

1. Todo .md não-reservado tem frontmatter YAML parseável — bloco entre --- precisa ser YAML válido
2. Todo frontmatter tem campo type não-vazio — string descrevendo o tipo do conceito
3. Arquivos reservados seguem a estrutura — index.md é listagem; log.md é histórico cronológico

Na prática

Manual (funciona sempre):

# Verifica se todos os .md têm frontmatter com type
for f in $(find ./bundle -name "*.md" ! -name "index.md" ! -name "log.md"); do
  head -50 "$f" | grep -q "^type:" || echo "FAIL: $f sem type"
done

Validador online (em breve): Temos um validador client-side em /validador — aceita upload de ZIP/folder, parseia YAML, gera relatório com badge de conformidade.

Programaticamente: Qualquer parser YAML + 3 checks. Sem mistério.

OKF vai substituir catálogos de dados?

Não. A spec é explícita nos non-goals.

OKF não substitui Knowledge Catalog, Datahub, Atlan, Amundsen. Ele complementa:

• Catálogos são plataformas com UI, API, governance, lineage, permissões
• OKF é formato de exportação/troca de conhecimento

O catálogo de dados é o sistema de record. O bundle OKF é o snapshot portável — que você versiona no git, compartilha com outro time, ou injeta no contexto de um agente.

Catálogo pode exportar em OKF. Agente pode consumir OKF gerado pelo catálogo. Camadas diferentes.

É só pra BigQuery?

De jeito nenhum. Os exemplos usam BigQuery porque o OKF nasceu no ecossistema Google Cloud, mas o formato é completamente agnóstico.

O campo type é livre — define seus próprios tipos:

type: PostgreSQL Table       # funciona
type: API Endpoint           # funciona
type: Metric                 # funciona
type: Runbook                # funciona
type: Business Process       # funciona
type: Qualquer Coisa         # funciona também

O campo resource (opcional) é URI genérico — aponta pra dashboard Grafana, endpoint REST, tabela Snowflake, página Confluence, o que for.

OKF serve pra documentar qualquer conhecimento organizacional: dados, APIs, processos, playbooks, métricas, decisões. Se é algo que humano ou agente precisa saber, cabe num bundle.

Como contribuir com a spec?

A spec vive no GitHub, aberta:

1. Repo canônico: GoogleCloudPlatform/open-knowledge-format
2. Issues: Sugestões, dúvidas, propostas de mudança
3. Pull Requests: Texto, exemplos, implementações de referência
4. Licença: Apache 2.0 — use, modifique, distribua

Nota: O diretório knowledge-catalog/okf/ mantém um snapshot congelado mais tooling específico do Knowledge Catalog. Pra contribuir com a spec e implementações de referência, use o repo open-knowledge-format.

O formato ainda tá no início do ciclo — momento bom pra influenciar direções. Veja CONTRIBUTING.md no repo pra guidelines.

Pra comunidade brasileira, estamos construindo recursos em português no okf.ia.br — docs traduzidos, guias práticos, exemplos pro mercado BR.

Precisa de backend?

Não. OKF é estático por natureza.

Bundle = pasta de .md. Pra servir: qualquer file server estático. Pra validar: roda client-side (JS no browser). Pra versionar: git. Pra distribuir: ZIP ou clone.

Zero banco de dados, zero API, zero infra dedicada.

Se você quiser construir algo em cima do OKF — catálogo com busca, enrichment pipeline, UI de navegação — aí pode precisar de backend. Mas o formato em si? Puro filesystem.

Funciona com git?

Perfeitamente. Git é o método de distribuição recomendado pela spec.

Por quê:

• Histórico: Cada mudança num conceito fica rastreável (quem, quando, o quê)
• Diffs: Markdown é texto puro — diffs legíveis e úteis
• Branches: Propõe mudanças no conhecimento via PR/MR
• Colaboração: Várias pessoas (ou agentes) editam ao mesmo tempo
• Distribuição: git clone e pronto

O log.md da spec é até redundante se você usa git (commits fazem o mesmo trabalho). Mas ele existe pra quando o bundle é distribuído sem VCS (ZIP, tarball).

Git + OKF = conhecimento organizacional com as mesmas práticas que a gente já aplica em código.

Qual o futuro do OKF?

⚠️ Opinião pessoal — análise especulativa, não fatos confirmados.

OKF tá em desenvolvimento ativo. Versão 0.2 chegou em jul 2026 com trust signals pra proveniência. Google Cloud tá empurrando adoção enterprise real via Knowledge Catalog.

O que tá rolando agora:

Curto prazo: padrões de escala no Knowledge Catalog (post de ago 2026 mostra entries governadas por IAM e distribuição enterprise). Tooling oficial amadurecendo (kcmd, validators, GitHub Actions). Suporte a MCP server expandindo nas plataformas de agentes.

Médio prazo: provável reconhecimento de outros cloud providers, enrichment agents gerando bundles de fontes diversas, possível registry público de bundles ou marketplaces.

Minha aposta: OKF tem chance real de ser o “Markdown do conhecimento organizacional”. Mesmo playbook — vence por ser simples e universal. O timing é certo: agentes precisam de contexto estruturado, mercado fragmentado em soluções proprietárias, e a spec tem barreira zero pra adoção.

O risco: Se o Google não empurrar adoção cross-cloud, pode estagnar. Mas licença Apache 2.0, design vendor-neutral e engajamento com W3C Holon CG reduzem risco de vendor lock-in.

Recomendação: experimenta agora. Custo zero (é Markdown!) e o upside de estar preparado quando o ecossistema amadurecer é alto.

Por que tantos times estão construindo a mesma coisa?

Quatro times sem conexão entre si lançaram ideias quase idênticas em 2026. Não é coincidência — é convergência pra um padrão cujo momento chegou.

• Google publicou o OKF como spec pra conhecimento legível por IA
• O CEO da Obsidian lançou 5 skills ensinando agentes a ler vaults nativamente
• Tencent liberou uma wiki open-source que se reestrutura conforme documentos entram
• Projetos open-source independentes surgiram fazendo a mesma coisa

O insight por baixo é o mesmo em todo lugar: agentes precisam de contexto curado e estruturado — não só documentos pra recuperar. O fato de múltiplos times chegarem em “pastas de markdown com frontmatter” independentemente sugere que esse é um equilíbrio natural, não escolha arbitrária.

A vantagem do OKF não é ter sido primeiro. É ter uma spec com regras explícitas (mesmo que mínimas), licença Apache 2.0 e o alcance de distribuição do Google. Se vai virar o padrão depende da comunidade se unir ou fragmentar em variantes incompatíveis.

OKF ajuda em handoffs entre agentes?

Sim — e esse é um caso de uso pouco explorado.

Um experimento (compartilhado por @ainewsusa) usou bundles OKF como formato de handoff entre três modelos Qwen2.5-Coder (7B → 3B → 1.5B). O resultado: redução de 28–37% no time-to-first-token (TTFT) passando contexto pré-estruturado em vez de prompts crus.

O setup: em vez de cada modelo re-parsear o problema do zero, o modelo upstream escreve seu entendimento num documento de handoff estruturado em OKF. O modelo downstream lê o bundle e parte de contexto organizado em vez de texto solto.

Isso importa porque:

• Pipelines multi-modelo estão ficando comuns — modelos diferentes pra tarefas diferentes (raciocínio → código → revisão)
• Preparação de contexto é cara — handoffs estruturados reduzem trabalho redundante
• OKF é agnóstico de modelo — qualquer LLM que leia Markdown se beneficia

É cedo, e um benchmark não é prova. Mas o padrão é promissor: OKF como lingua franca entre agentes, não só entre humanos e agentes.

OKF vs llms.txt vs schema.org?

Três formatos, três audiências, três propósitos. Não competem — se empilham.

Na prática: schema.org é pro Google te entender. llms.txt é pro ChatGPT te encontrar. OKF é pro seu agente saber o que sua org sabe.

Faz os três. Não são excludentes. São camadas de uma mesma stack de visibilidade.

Posso vender bundles OKF?

Não há impeditivo técnico. A licença é Apache 2.0, o formato é aberto, o conteúdo é seu.

Quem já poderia fazer isso amanhã:

• Advogados empacotando jurisprudência curada
• SEOs vendendo bundles de keyword research estruturados
• Data teams entregando dicionários de dados como produto
• Consultores vendendo playbooks operacionais

O problema hoje: falta infraestrutura de distribuição. Não existe um “npm de bundles OKF” — sem registry, sem billing, sem discovery padronizado.

Então por enquanto, bundle OKF é como qualquer digital asset: empacota num ZIP, vende no Gumroad, entrega via git privado. Funciona, mas é artesanal.

A oportunidade tá aí pra quem quiser construir o marketplace.

Como agentes descobrem meu OKF?

Não existe mecanismo oficial de discovery. A spec não define como um agente externo encontra seu bundle — ela define o formato, não a distribuição.

Caminhos prováveis:

1. Via llms.txt — Incluir link pro bundle no seu llms.txt. É o mais natural: “aqui tá meu conhecimento estruturado”
2. Via AGENTS.md / auth.md — Padrão emergente pra agentes autenticados descobrirem recursos
3. Via .well-known/okf — Convenção que pode surgir (tipo .well-known/security.txt)
4. Via MCP server card — Se seu agente usa MCP, declarar o bundle como resource disponível
5. Hardcoded — Seu AGENTS.md manda o agente olhar /knowledge/bundle/

Pra agentes internos (seu Cursor, seu Claude Code), não precisa discovery — você configura o path. O problema de discovery é mais relevante pra cenários cross-org, e isso ainda tá verde.

Como faço o agente realmente consultar o OKF?

Discovery é uma coisa; fazer o agente usar o bundle no meio da tarefa é outra. Padrões que funcionam no mundo real:

Pra agentes conectados via MCP:

• Use MCP lookup/list tools (ex: kcmd mcp expõe lookup-entry, list-entries)
• Agente chama lookup-entry("nome da métrica") quando precisa de contexto

Pra agentes baseados em skills (Cursor, Claude Code):

• Adiciona no seu AGENTS.md ou arquivo de skill: “Antes de responder perguntas sobre fatos da org, consulte o bundle OKF em /knowledge/”
• Instrução explícita faz o agente checar o bundle proativamente

Pra workflows enterprise com Knowledge Catalog:

• Caminho de retrieve do agente (conforme post de ago 2026 do Google): searchEntries → LookupContext → entries.get(view=ALL)
• Governado por IAM: agentes veem só o que têm autorização
• Push via kcmd push com AspectType okf sinalizando campos de trust v0.2

Quando usar RAG ao invés:

• OKF é pra fatos conhecidos e estáveis (schemas, métricas, playbooks) — leitura direta, latência zero
• RAG é pra queries fuzzy em corpora grandes e dinâmicos
• Veja a pergunta OKF substitui RAG? pra distinção completa

Resumo: bundles OKF não “chamam” agentes. Você conecta o agente pra consultá-los. Faz parte das instruções ou tooling do agente, e funciona.

OKF substitui RAG?

Não. Muda o que RAG recupera, não elimina RAG.

A distinção:

• Fatos estáveis (definições, schemas, playbooks, decisões documentadas) → OKF funciona por leitura direta. O agente lê o bundle, tem o contexto. Sem embedding, sem vector search, sem chunk splitting.
• Queries dinâmicas (buscar em milhões de documentos, dados que mudam constantemente) → RAG continua necessário.

Karpathy colocou isso bem: a diferença entre build once e re-derive every time. OKF é conhecimento construído uma vez e consumido N vezes por leitura. RAG é retrieval sob demanda de corpora imensos.

Na prática, os dois coexistem: seu agente lê o bundle OKF pro contexto base (o que são nossas tabelas, quais métricas importam, qual o playbook de incident response) e usa RAG pra queries ad-hoc contra fontes maiores.

OKF reduz a superfície onde você precisa de RAG. Não mata RAG.

O vídeo Google’s OKF Explained: The Folder Replacing RAG do canal Signal Coders explica bem essa distinção. O título é clickbait assumido — mas o conteúdo é sólido.

O que o W3C tá fazendo com OKF?

O Holon Community Group do W3C — 30+ participantes — teve sua primeira reunião em 19 de junho de 2026. Objetivo: formalizar OKF como padrão web interoperável.

A direção técnica é tratar o conceito de “DataBook” (bundle OKF) como um profile dentro da stack de padrões web:

• IRI pra identificação única de conceitos
• RDF pra representação semântica
• SPARQL pra queries sobre bundles
• SHACL pra validação de conformidade

Traduzindo: o W3C quer que OKF fale a língua da web semântica sem perder a simplicidade do Markdown. DataBook vira um profile — tipo como Schema.org é um profile de RDF.

Isso é bom? Depende. Se conseguirem manter a barreira de entrada baixa (editar Markdown) enquanto adicionam interoperabilidade formal por baixo dos panos, é win-win. Se virarem XHTML 2.0 de tão complexos, a comunidade ignora e segue com o Markdown puro.

Acompanhe: é cedo, mas o fato de ter W3C olhando dá legitimidade institucional.

E se o Google abandonar o OKF?

Preocupação válida. O cemitério de produtos do Google é lendário.

Mas o risco aqui é menor que o habitual:

1. Apache 2.0 — A spec já tá publicada, licença irrevogável. Ninguém precisa de permissão do Google pra continuar usando.
2. Custo zero pra entrar, zero pra sair — Você não tá deployando infra proprietária. São arquivos Markdown. Se o Google sumir amanhã, seus bundles continuam funcionando.
3. W3C Holon CG — Já existe grupo fora do Google dando legitimidade institucional.
4. O formato é só Markdown — Pior cenário: você tem uma pasta de documentos Markdown bem organizados. Isso não “quebra”.

O risco real não é perder seus dados — é perder momentum. Se o Google parar de investir, o ecossistema de tooling (validadores, CLIs, integrações) estagna. Mas como a base é Markdown + YAML, qualquer comunidade pode manter.

Comparação honesta: Google matou o Reader, o Wave, o Plus. Mas não matou Kubernetes, Go, Protobuf, ou Terraform (ok, esse é HashiCorp). Specs abertas com comunidade ativa tendem a sobreviver ao criador.

Qual a diferença entre OKF e knowledge graph?

OKF é implicitamente um graph. Knowledge graph é formalmente um graph.

OKF é graph-adjacent: os links entre conceitos formam um grafo implícito, mas você não precisa pensar em termos de nós e arestas pra usar. É tipo a diferença entre linkar páginas na Wikipedia e modelar o Wikidata.

Se você precisa de queries formais sobre relações tipadas (“me dê todas as tabelas que alimentam esta métrica via este pipeline”), um knowledge graph faz isso melhor. Se você precisa que um agente entenda seu domínio lendo documentação, OKF é mais prático.

E sim — um knowledge graph pode exportar pra OKF, e um bundle OKF pode ser importado num knowledge graph. São representações diferentes do mesmo conhecimento.

OKF ajuda com SEO?

Não. E o Google foi explícito sobre isso.

OKF não é indexado por search engines. Não gera rich results. Não melhora ranking. Não aparece no Google Search.

Pra SEO, use:

• schema.org — Structured data que o Google entende (JSON-LD nas páginas)
• llms.txt — Pra AI crawlers encontrarem seu conteúdo
• Conteúdo limpo e bem estruturado — O básico que sempre funcionou

OKF é infraestrutura de conhecimento interno. É pra seus agentes, seus times, seus sistemas consumirem. Não é pra o Googlebot.

Confundir OKF com ferramenta de SEO é como usar um ERP pra fazer landing page. Ferramentas diferentes, problemas diferentes.

Como está a adoção pela indústria?

O sinal é maior que a spec em si.

A Semrush — uma das maiores plataformas de SEO e marketing — colocou assim: “Conforme sistemas de IA passam de encontrar informação para usar informação, visibilidade depende de mais que publicar conteúdo. Depende de como o conhecimento é organizado e estruturado.”

Esse framing importa. Players grandes estão de olho no OKF não porque é produto do Google, mas porque representa uma mudança: de otimizar pra search engines pra otimizar pra agentes de IA. As organizações que estruturarem seu conhecimento pra consumo por máquinas agora vão ter vantagem quando workflows agent-first virarem norma.

É hype? Parcialmente. A aposta direcional faz sentido? Provavelmente. O custo de experimentar é baixo (são arquivos Markdown), e o upside de estar cedo é real.

Como OKF funciona com MCP?

kcmd é um MCP server. Qualquer agente que fale Model Context Protocol pode consumir bundles OKF via tools padronizadas.

Tools disponíveis:

Além do kcmd, qualquer MCP server pode servir um bundle OKF como resources — o bundle vira um recurso que agentes consultam via protocolo padrão.

Na prática: seu Claude Code, Cursor, ou qualquer agente MCP-compatible pode fazer lookup-entry("métrica de churn") e receber o conceito OKF com definição, fórmula, owner, e links relacionados. Sem precisar jogar o bundle inteiro no contexto.

É a diferença entre dar um livro pro agente ler inteiro e dar acesso a um índice remissivo.

Mais perguntas?

• 📖 Spec OKF anotada (e a fonte oficial)
• 🛠️ Ferramentas OKF — validadores, agentes, CLI, conversores
• 🧠 Skill OKF — ensine Claude / Codex / Cursor o formato
• 📚 Snapshot congelado + tooling KC: github.com/GoogleCloudPlatform/knowledge-catalog/okf/
• 🇧🇷 Docs em português: okf.ia.br
• 🌐 Site de referência: okf.md