Open Knowledge Format: Agents Don’t Need More Context. They Need Better Disclosure.
How Google Cloud’s Open Knowledge Format shows a practical path toward Partial Disclosure Architecture. Giving AI agents the right knowledge at the right time without flooding the LLM context window.
Most agent failures do not happen because the model knows too little. They happen because we drown the model in too much context, then act surprised when it loses the plot.
Summary: As AI agents move from demos into real enterprise workflows, the limiting factor is no longer just model intelligence or context window size. The deeper challenge is knowledge disclosure: how to reveal the right information to the model at the right moment without overwhelming its reasoning space.
Google Cloud’s Open Knowledge Format gives agents a simple way to browse knowledge instead of swallowing it whole. With indexes, metadata, links, logs, and citations, OKF supports Partial Disclosure Architecture: reveal only the context the model needs, when it needs it.
This article explains why OKF is more than lightweight documentation. It is a practical pattern for agent-ready knowledge systems that treat the LLM context window as a scarce reasoning surface, not a storage layer.
How Google Cloud’s Open Knowledge Format points toward Partial Disclosure Architecture for agent-ready knowledge
The biggest lie in AI infrastructure is that bigger context windows will solve knowledge management.
They help, of course. A model that can read more can sometimes do more. But giving an LLM a larger context window does not magically teach it what matters. It only gives us more room to make the same mistake: dumping too much information into the prompt and hoping the model sorts it out.
That is not architecture.
That is context flooding.
As agents become more capable, the real challenge is not merely how much knowledge they can access. It is how that knowledge is disclosed.
This is where Google Cloud’s Open Knowledge Format, or OKF, becomes interesting.
On the surface, OKF is simple: a directory of Markdown files with YAML frontmatter. It is intentionally minimal, human-readable, agent-readable, diffable in version control, and portable across tools and organizations.
But viewed through the lens of PDA — Partial Disclosure Architecture — OKF becomes something more important.
It becomes a pattern for not drowning the LLM.
What Partial Disclosure Architecture is really about
Partial Disclosure Architecture is the discipline of showing an agent only what it needs, when it needs it, at the level of detail it can use.
Instead of loading an entire corpus into the model context, PDA gives the agent a navigable structure.
First, the agent sees the map.
Then it chooses a region.
Then it opens a specific document.
Then it follows links or citations only when the task requires them.
This is how humans work with large bodies of knowledge. We do not read an entire company wiki before answering one question. We scan the table of contents. We open the relevant page. We skim headings. We inspect the section we need. We follow references if something is unclear.
PDA applies that same discipline to agents.
The core idea is simple:
Do not confuse access with attention.
An agent may have access to thousands of documents. That does not mean all of them belong in the prompt.
OKF is almost tailor-made for PDA
The OKF spec defines a “Knowledge Bundle” as a self-contained hierarchical collection of knowledge documents. Each “Concept” is a single unit of knowledge represented as one Markdown document. A concept can describe a table, an API, a metric, a business process, a playbook, or almost anything else.
That already fits the PDA mindset.
Instead of one giant knowledge blob, OKF gives us small addressable units.
Each concept has a path. Each path becomes a concept ID. Each concept has structured frontmatter and a Markdown body. Each file can be opened independently, summarized independently, cited independently, and updated independently.
For an agent, that matters.
A 500-page internal knowledge base is not a useful unit of retrieval.
A specific concept file called metrics/active-customer.md is.
OKF turns knowledge into navigable atoms.
PDA tells the agent when to open which atom.
The index.md file is the PDA primitive
The most important OKF feature for Partial Disclosure Architecture is not YAML frontmatter.
It is index.md.
In OKF, an index.md file may appear at any level of the directory tree. Its purpose is to enumerate the contents of that directory so a human or agent can see what is available before opening individual documents.
That is PDA in one sentence.
The index is the disclosure layer.
It says: here is what exists, but not all the details yet.
A root index might show top-level areas:
datasets/
metrics/
playbooks/
apis/
references/This prevents the most common failure mode in agent knowledge systems: retrieving too broadly and stuffing the prompt with semi-relevant material.
With OKF, the agent does not need to ingest the whole bundle.
It can browse.
PDA is not about hiding knowledge
The phrase “partial disclosure” can sound like concealment.
That is not the point.
PDA is not about hiding knowledge from the agent. It is about sequencing knowledge for the agent.
A well-designed PDA system can still make the entire corpus available. It simply refuses to put the entire corpus into context at once.
That distinction matters.
A filesystem gives you access to everything. But your screen only shows the directory you are in. A database may contain millions of rows. But your query returns the relevant slice. A documentation site may contain years of material. But navigation starts with headings, menus, and search results.
PDA brings that same common sense to LLM context.
The context window should not be treated like a landfill.
It should be treated like a workbench.
Only the tools needed for the current job should be on it.
Why YAML frontmatter matters for routing
OKF concept files begin with YAML frontmatter. The only required field is type, a short string identifying the kind of concept. Recommended fields include title, description, resource, tags, and timestamp.
This is small, but powerful.
Frontmatter gives the agent enough metadata to make routing decisions without reading the full body.
A concept with:
type: Metric
title: Active Customer
description: A customer with at least one paid transaction in the last 30 days.
tags: [customers, revenue, analytics]tells the agent a lot before it spends context on the full document.
It can decide whether this concept is likely relevant. It can show the title in search results. It can use the description in an index. It can filter by type. It can prioritize recent documents using timestamps. It can route “Metric” documents to one interpretation strategy and “Playbook” documents to another.
That is PDA again.
Disclose metadata first.
Disclose body content second.
Disclose citations, examples, schemas, and linked concepts only when needed.
Links let the agent traverse instead of hoard
OKF supports standard Markdown links between concepts. A concept about an orders table can link to a customers table. A metric can link to the tables that support it. A playbook can link to a dashboard or incident process.
The spec intentionally keeps link semantics lightweight. The relationship is conveyed by surrounding prose rather than a formal typed edge.
For PDA, this is a practical choice.
The agent can treat links as optional next steps.
It does not need to follow every link immediately. It can inspect the current concept, decide whether more context is needed, and then traverse to a related concept only when the task requires it.
This is very different from eager retrieval.
Eager retrieval says: “This document links to five other documents, so load them too.”
Partial Disclosure Architecture says: “This document points to five possible next places. Choose only the one that matters.”
That difference is the difference between context navigation and context explosion.
Logs give agents temporal awareness without full replay
OKF also defines optional log.md files. A log can appear at any level of the hierarchy and record chronological updates for that scope.
This matters because freshness is one of the hardest problems in agent systems.
A model can answer confidently from stale context. A retrieval system can pull an old document because it matches the query. A knowledge base can contain deprecated procedures that still look authoritative.
A log file gives the agent a lightweight way to ask, “What changed here?”
Again, this fits PDA.
The agent does not need the entire change history of the organization. It may only need the recent update log for the directory it is about to use.
If the task involves a metric, inspect the metric directory log.
If the task involves an incident playbook, inspect the playbook directory log.
If the task involves a dataset, inspect the dataset log.
Disclose the relevant history, not all history.
Citations make partial disclosure trustworthy
OKF recommends a # Citations section for claims based on external material.
This is especially important in a PDA system because the model may initially see only a summary, index entry, or frontmatter description. When the answer requires more confidence, the agent can drill down into the supporting citation.
That creates an escalation path for trust.
Level one: show the index entry.
Level two: open the concept.
Level three: inspect the relevant section.
Level four: follow the citation.
This is exactly how expert humans work.
We do not verify every statement at maximum depth every time. We use summaries until the stakes require sources. Then we dig.
A good agent needs the same pattern.
Without citations, partial disclosure can become shallow disclosure.
With citations, partial disclosure becomes navigable evidence.
The anti-pattern: stuffing the LLM with everything
A lot of agent systems still behave like nervous interns.
They gather every document that might possibly be relevant and dump it into the model context.
The result is predictable.
The model gets distracted. Important details are buried. Contradictory snippets compete. The agent overfits to irrelevant passages. The final answer sounds confident but is based on a noisy blend of context.
This gets worse as organizations add more tools and more knowledge sources.
The temptation is to solve it with bigger windows, better embeddings, and more aggressive reranking. Those help, but they do not replace architecture.
At some point, the agent needs to know how to browse.
OKF gives agents a browsable knowledge layout.
PDA gives them the behavioral rule:
Open less first. Open more only when justified.
What an OKF-powered PDA workflow looks like
Imagine an agent receives this question:
“Why did revenue retention drop last month?”
A context-flooded system might retrieve dashboards, metric docs, customer tables, churn notes, sales summaries, finance reports, and incident logs all at once.
An OKF plus PDA system behaves differently.
First, it opens the root index.md.
It sees metrics/, datasets/, dashboards/, and playbooks/.
Then it opens metrics/index.md.
It finds net-revenue-retention.md.
The frontmatter tells the agent this is a metric related to revenue, expansion, contraction, and churn.
The agent opens the concept file.
The body explains the definition, formula, caveats, and related tables.
The concept links to the customer subscriptions table and the revenue dashboard.
Only then does the agent open the linked dataset concept.
If the metric definition recently changed, it checks metrics/log.md.
If the answer requires evidence, it follows the citations.
At every step, the agent is narrowing.
That is the heart of PDA.
Not less knowledge.
Less irrelevant knowledge.
Why OKF is better than a giant prompt
The obvious alternative to OKF is to generate a giant “agent knowledge prompt.”
Teams already do this.
They write long system prompts. They paste in documentation. They add tool descriptions. They include policies, examples, constraints, and domain context. Then they wonder why the agent behaves inconsistently.
The problem is not that the prompt is bad.
The problem is that the prompt is trying to be a knowledge base.
A prompt is a terrible place to store a large evolving corpus.
OKF moves knowledge out of the prompt and into a navigable structure.
The prompt can then teach the agent how to browse:
Start with indexes.
Use frontmatter for triage.
Open concept bodies only when relevant.
Follow links selectively.
Check logs for freshness.
Use citations for high-stakes claims.
Do not load unrelated branches.
That is a far better division of labor.
The knowledge bundle stores knowledge.
The agent policy controls disclosure.
The model context becomes a focused workspace.
PDA turns retrieval into exploration
Traditional retrieval often works like a search engine: query in, chunks out.
That is useful, but limited.
Agentic systems need something closer to exploration.
They need to inspect what exists, choose paths, ask follow-up questions of the corpus, compare concepts, notice missing links, and decide when they have enough context to answer.
OKF supports that because it is hierarchical, linked, and human-readable.
An agent can move through it like a documentation site:
Open index.
Read descriptions.
Open concept.
Inspect headings.
Follow relevant link.
Check citations.
Return with answer.
This is a more natural fit for multi-step agents than flat chunk retrieval alone.
Embeddings can still help. Search can still help. Vector databases can still help. But they become part of a broader navigation strategy rather than the entire architecture.
The best knowledge systems will be partially disclosed by default
The agent era will reward teams that design knowledge for navigation.
Not every fact belongs in the first prompt.
Not every document belongs in the first retrieval call.
Not every linked concept needs to be opened.
Not every citation needs to be followed.
The art is knowing what to disclose when.
That means future knowledge systems will need layers:
Indexes for orientation.
Frontmatter for triage.
Concept files for explanation.
Links for traversal.
Logs for freshness.
Citations for verification.
Schemas and resources for deeper inspection.
OKF includes all of these pieces in a minimal format.
That is why it deserves attention.
It is not trying to be a giant enterprise knowledge platform. It is trying to define the small structural conventions that make knowledge portable and agent-consumable.
For PDA, that is exactly the right level of ambition.
The real lesson: context is a scarce resource
Even when context windows grow, attention remains scarce.
The model still has to decide what matters. The agent still has to reason over what it sees. The system still has to avoid irrelevant, stale, contradictory, or low-quality context.
Partial Disclosure Architecture starts from a sober premise:
The LLM context window is not a storage layer.
It is a reasoning surface.
That surface should be protected.
OKF helps because it gives agents a way to approach knowledge gradually. It lets them orient before they ingest, inspect before they answer, and verify before they claim.
That is the future of agent-ready knowledge.
Not one giant prompt.
Not one giant vector dump.
Not one giant memory blob.
A map.
A set of concepts.
A trail of links.
A history of changes.
A path to citations.
And an agent disciplined enough to open only what the task requires.
Conclusion: the future belongs to agents that can browse
The next generation of AI agents will not win simply by having more context.
They will win by using context better.
Google Cloud’s Open Knowledge Format is interesting because it gives us a simple, open way to structure knowledge so agents can browse it without swallowing it whole.
That is the essence of Partial Disclosure Architecture.
Show the agent the map before the territory.
Show the summary before the details.
Show the concept before the citations.
Show the linked document only when the current one is not enough.
The goal is not to starve the model of information.
The goal is to stop drowning it.
Because agents do not need infinite context to be useful.
They need the right context, revealed at the right time.
About the Author — Claude Certified Architect
Rick is a Claude Certified Architect, AI systems practitioner, builder of production multi-agent systems, creator of Skilz, and author of an upcoming Manning book on Harness Engineering.
Ready to make your company AI-first? Connect with Rick on LinkedIn, Substack or Medium, book him to speak or train your team, or visit Spillwave to explore mentoring, training, and custom AI solutions for your organization. Check out Rick Hightower’s SpeakerHub.