The repo name and its one-line GitHub description (“Google Cloud Knowledge Catalog Tools and Samples”) undersell what is actually inside. The headline here is not a pile of vendor SDK samples. It is OKF, the Open Knowledge Format, and the repo’s own okf/README.md says so plainly: “This repository is primarily about the Open Knowledge Format. The format itself is the contribution.” Everything else, the enrichment agent and the graph visualizer, exists to make that format tangible at both ends.
What OKF actually is
OKF is a spec for representing knowledge, meaning the metadata, context, and curated insight around data, as a directory of plain markdown files with YAML frontmatter. No schema registry, no central authority, no required runtime. The pitch in the spec is blunt: if you can cat a file you can read OKF, and if you can git clone a repo you can ship it.
The interesting part is who is shipping it. “Knowledge Catalog” is Google Cloud’s rebrand of Dataplex, its managed catalog product, so this lives under a repo named after a paid Google service. Yet OKF goes out of its way to be vendor-neutral. The spec names Unity Catalog and Collibra, two direct competitors, as legitimate producers, and states the format is “not tied to any particular agent, framework, model provider, or serving system.” A hyperscaler publishing an anti-lock-in format under its own product’s name is the tension worth noticing, and it is why the repo reads more like a standards play than a samples dump.
Why it showed up on trending
The star curve tells the story. The repo was created on 2026-05-04 and sat near a single star for weeks. It went vertical in mid-June: roughly 700 stars on June 13, past 1,300 on June 14, over 2,100 on June 15, and about 2,320 by June 16 (snapshot as of 2026-06). That window lines up with the commits that landed the agents/ directory and the OKF reference agent (PRs #28, #40, #42 on June 12 to 13). The format went public right as “how should agents store and exchange knowledge” became a crowded question, and an open spec from Google Cloud was enough to pull attention fast.
What is in the box
- The spec (
okf/SPEC.md), currently v0.1 Draft. It defines a bundle as a directory tree of markdown concept files, reservesindex.md(directory listing for progressive disclosure) andlog.md(update history), and uses ordinary markdown links between concepts to express a graph rather than a plain tree. - A reference enrichment agent (
okf/, packageenrichment-agent) built on the Google Agent Development Kit with Gemini as the model backend. BigQuery is the first metadata source, behind a pluggableSourceinterface. It runs in two passes: a BQ pass that writes one OKF doc per concept from BigQuery metadata, then an optional web pass where the LLM crawls seed URLs through afetch_urltool to enrich the docs. - Three ready-to-browse bundles in
bundles/: a GA4 e-commerce dataset, the Stack Overflow public dataset, and Bitcoin blocks/transactions, each with a self-containedviz.htmlgraph viewer that needs no backend and no install on the consumer side. - A toolbox (
toolbox/) with “metadata as code” (mdcode) for syncing catalog metadata as source artifacts, plus the enrichment harness.
The frontmatter rule that matters
OKF is deliberately minimal about what a concept document must declare. In §4.1 the only required frontmatter key is type (a short string like BigQuery Table or Metric). title, description, resource, tags, and timestamp are all optional, and producers may add arbitrary extra keys. That minimalism is the whole design bet: a programmatic producer can emit {"type": "API Endpoint"} and nothing else and still be conformant.
Install and run the reference agent
The format needs no tooling, but the reference agent is a normal Python package installed from source. From the okf/ directory (Python 3.11+):
python3.13 -m venv .venv
.venv/bin/pip install -e .[dev]A minimal enrichment run points at a BigQuery dataset and an output directory; add --no-web to skip the LLM web pass:
.venv/bin/python -m enrichment_agent enrich \
--source bq \
--dataset <project>.<dataset> \
--no-webYou can also open the repo in Cloud Shell via the button in the top-level README. There is no published PyPI package or pip install okf; treat the agent as reference code you clone, not a product you install.
Where it fits, and where it does not
Good fit if you want a portable, git-diffable knowledge corpus that both humans and LLMs can read without an SDK, or if you are tired of metadata trapped behind a catalog’s proprietary API. Because a bundle is just files, it composes with Obsidian, MkDocs, Notion, and static hosting out of the box.
Poor fit if you need a stable, frozen spec today (it is v0.1 Draft and changing weekly), or if you expected a turnkey Google Cloud product. The reference agent specifically requires Google Cloud credentials, BigQuery, and Gemini access, so the “automatic production” half is not vendor-neutral even though the format is. And the repo carries an explicit disclaimer: it is “not an official Google product.”
OKF vs other agent-knowledge formats
OKF is a format, not a catalog, so the truest comparison is to other open conventions for agent- and LLM-readable knowledge expressed as markdown, plus the catalog incumbent it positions against. Star counts as of 2026-06.
| Project | Stars | License | What it is | Same idea? |
|---|---|---|---|---|
| OKF (this repo) | ~2.3k | Apache-2.0 | Markdown + YAML frontmatter format for knowledge bundles, with a reference agent | The format is the product |
| Agent Skills | ~151k | (none listed) | Markdown + YAML frontmatter packaging agent capabilities | Same md+frontmatter shape, different payload |
| llms.txt | ~2.4k | Apache-2.0 | A markdown convention for exposing site content to LLMs | Markdown-for-LLMs, narrower scope |
| Unity Catalog | ~3.4k | Apache-2.0 | Open data catalog server (Databricks) | A catalog, not a file format |
Across the top two rows the container is identical: markdown plus YAML frontmatter, with the payload being a skill in one case and a data concept in the other. That OKF reaches for that same shape instead of inventing a new file type is the part of this comparison worth remembering.
Gotchas worth knowing before you build on it
- The reference validator was stricter than the spec. As contributors noted in issue #62,
validate()setREQUIRED_FRONTMATTER_KEYSto("type", "title", "description", "timestamp")while §4.1 requires onlytype. A spec-minimal, type-only bundle would fail the bundled validator until PR #64 corrected it. If you pinned an early commit, check that your validator matches the spec, not the old tuple. - v0.1 is a moving target. The issue tracker is full of live spec debate: where
okf_versionshould live (#57), whether scope extends beyond single-concept docs, a proposed §9 conformance corpus (#62), and producer proposals for OpenAPI and other sources (#56). Useful, but do not treat the format as frozen. - It is not an official Google product, despite the GoogleCloudPlatform org and the product name. Support and longevity are community-grade, not SLA-backed.
Related
- anthropics/skills for the closest structural cousin, Agent Skills, which uses the same markdown-plus-frontmatter container.
- The broader LLM tooling trend this format slots into.
FAQ
Is Knowledge Catalog the same as Dataplex? Knowledge Catalog is Google Cloud’s current name for what was Dataplex, its AI-powered data catalog and metadata platform. This repo holds tools, samples, and the OKF spec around that product, but OKF itself is designed to work independently of it.
Is OKF an official Google product? No. The repo’s own disclaimer states it “is not an official Google product.” It lives under the GoogleCloudPlatform org and is Apache-2.0 licensed, but treat it as open-source reference work, not a supported service.
Does the OKF reference agent require Google Cloud and Gemini? Yes. The enrichment agent is built on the Google Agent Development Kit with Gemini as the model backend and BigQuery as the first source, so running it needs Google Cloud credentials. The format you produce is portable, but the bundled producer is not.
Is OKF tied to a vendor? The format is explicitly vendor-neutral: the spec invites competitors like Unity Catalog and Collibra to produce OKF and says it is not bound to any agent, framework, model, or serving system. Only the reference agent is Google-specific.
What frontmatter does an OKF document require?
Just one key: type. Everything else (title, description, resource, tags, timestamp) is optional, and producers may add their own keys. Note that early versions of the reference validate() wrongly demanded more, fixed in PR #64.
How does OKF compare to Agent Skills? Both store content as markdown with YAML frontmatter that humans and agents can read directly. Agent Skills package executable agent capabilities; OKF packages knowledge and metadata about data. Same container, different payload.