AI & ML

Hot Topic

Why AI Agents Need a Portable Knowledge Layer

By Gaurav Agarwaal

Published September 21, 2026

1.3K |

0:00 0:00

EXECUTIVE ABSTRACT AI agents are becoming capable of working directly inside software environments. They can inspect repositories, invoke APIs, search internal documents and execute multi-step tasks. What they still lack is a dependable way to understand the business and operational knowledge surrounding those systems. That gap is easy to miss. A coding agent may correctly identify the function that changes a user’s permissions but still not know that privileged access requires a second approver. A support agent may retrieve a policy document but have no way of knowing that the document was superseded last quarter. A data agent may produce a perfectly valid SQL query while using a calculation that finance does not recognize as the approved definition. Google’s Open Knowledge Format, or OKF, is interesting because it focuses on this layer directly. It does not attempt to replace search, RAG, MCP or agent workflows. Instead, it provides a portable way to package knowledge so that humans, agents and software systems can work with the same artifact. The specification uses familiar components—Markdown, YAML frontmatter, directories and links—but the goal is broader: making knowledge independent of the platform that happens to store or serve it. 1. Reading the System Is Not the Same as Understanding the System Consider a coding agent working on an internal access-management service. It can inspect the repository and find the function that grants elevated permissions. It can trace the API call and understand which database table is updated. From the code alone, however, it may not know that production access requires approval from both the application owner and security, or that access to one regulated environment expires automatically after 24 hours. Those rules may be documented somewhere else. One may live in an IAM policy. Another may be in an architecture decision record. A third may exist in an operations runbook. A fourth may only be understood by the security engineer who designed the process. Coding agent access-decision workflow showing why code alone is insufficient. This is the problem the source article identifies when it says that the codebase is only part of the system and that the rest of the knowledge may be scattered across wikis, product documents, APIs, shared drives, issue trackers and people’s heads. For a human engineer, this fragmentation is inconvenient but familiar. People learn which document matters, which colleague to ask and which policy is outdated. An agent has no such instinct unless the organization gives it a structured way to discover that context. The issue, then, is not simply whether the agent has access to more documents. It is whether the relevant knowledge is represented in a form the agent can navigate, interpret and evaluate. 2. Why the File Format Is the Least Interesting Part At first glance, OKF looks almost ordinary. A knowledge bundle can be a collection of Markdown files arranged in directories, with YAML metadata attached to individual concepts. A project might contain something like: Portable knowledge bundle connecting structured files with humans, AI agents, and search. A concept can then carry a small amount of structured metadata while keeping the actual knowledge readable in plain Markdown. YAML policy metadata for privileged access approval. There is nothing particularly novel about Markdown or YAML themselves. The value is that the artifact is not tied to a particular knowledge-management product, vector database or agent framework. A security engineer can edit the file. A coding agent can read it. A retrieval pipeline can index it. Another system can export or transform it. The knowledge does not have to be rewritten simply because the serving technology changes. That producer-consumer separation is the important part of OKF. The specification is deliberately independent of a specific model, agent framework or serving system. The closest comparison is not another document platform. It is an interface contract. OpenAPI did not invent APIs; it gave different tools a common description they could interpret. OKF is exploring a similar idea for knowledge. 3. A Knowledge Bundle Gives the Agent Somewhere to Start Once the amount of organizational knowledge becomes large, representation alone is not enough. The agent also needs a way to navigate it without loading everything into context. That is where Knowledge Bundles, Concepts and index.md files become useful. Imagine a cloud-platform repository with the following structure: Platform knowledge repository structure with networking, identity, deployment, and compliance files. If an agent is asked to modify workload identity for a production service, it does not need to read every file in the bundle. It can begin with the root index.md, move into identity/index.md, open workload-identity.md, and follow links to audit-logging.md only if the deployment touches a regulated environment. The source article refers to this pattern as progressive disclosure: the agent discovers the knowledge one level at a time rather than loading the entire bundle at once. That design matters because retrieval systems often reduce knowledge to isolated chunks. A hierarchy preserves something retrieval alone may miss: where a concept belongs, what sits next to it and which related concepts should be consulted before acting. 4. RAG Finds the Material; OKF Defines the Material RAG and OKF are often easy to conflate because both sit close to the knowledge layer, but they solve different problems. RAG answers a retrieval question: Which piece of information should the system fetch for this task? OKF answers a representation question: What does that knowledge look like once it exists, and how is it organized so different systems can understand it? The source makes this distinction explicitly. RAG concerns how relevant knowledge is retrieved, while OKF concerns how that knowledge is represented, organized and exchanged. The two can sit in the same flow: Agent workflow for searching knowledge, building context, and applying policies. The search layer finds the right entry point. The knowledge structure tells the agent what the concept means and where to look next. This is especially useful in environments where the answer depends on more than one policy. A network rule may only make sense when read alongside a data-residency requirement or a security exception. Similarity search can surface the files; structure helps preserve the relationships between them. 5. Agent Skills Should Not Become Policy Dumping Grounds The same separation is useful when thinking about Agent Skills. A Skill might tell a cloud-operations agent how to process a deployment request: Validate the target environment. Check the deployment window. Verify required approvals. Confirm rollback readiness. Execute or escalate. That is procedural knowledge. It describes the order of operations. It should not also contain every deployment rule, security exception, business continuity policy and regional constraint. If those details are embedded directly inside the Skill, the workflow becomes difficult to maintain because every policy update now requires the Skill itself to be changed. A cleaner structure is: Deployment agent structure with skill and knowledge folders for environments, changes, rollback, and compliance. The Skill tells the agent what sequence to follow. The knowledge bundle contains the rules it should consult during that sequence. The source article draws the same line: Skills describe how an agent performs work, while OKF provides the knowledge needed while doing that work. This matters because the owners are often different. Platform engineering may own the workflow, security may own the approval policy, and compliance may own the regional restriction. Keeping those concerns separate reflects how the organization actually operates. 6. The Most Useful Knowledge May Sit Beside the Code The most practical use of a portable knowledge format may not begin with a company-wide knowledge platform. It may begin inside a single repository. Take a SaaS billing service: Billing service repository with architecture, business rules, security, and operations knowledge. Suppose a coding agent is asked to add a new enterprise entitlement. It can inspect the implementation, but it can also read the entitlement rules, check whether the change crosses the PCI boundary and review the deployment constraints before modifying anything. The source article argues for this type of project-local knowledge because production software cannot always be understood from source code alone. Business and product knowledge often defines the behaviour the code is expected to preserve. This also changes the relationship between code and documentation. If the agent modifies a rule that affects entitlements, the corresponding knowledge file can be updated in the same pull request. The reviewer sees the code change and the knowledge change together. That is far more useful than documentation that is updated weeks later, if at all. 7. Some Knowledge Belongs With the Project; Some Belongs With the Company Not everything should be copied into every repository. A billing service may need local knowledge about entitlements, event contracts and deployment behaviour. But identity standards, regulatory controls and architecture principles apply across many services. An agent may therefore consult two scopes: AI agent connecting project-specific and shared knowledge. The first answers: What do I need to know about this service? The second answers: What company-wide rule applies to this service? The source article makes the same distinction between project-local and organization-wide knowledge, and notes that the central layer may be distributed through Git, object storage, metadata indexes, search or MCP without changing the underlying knowledge format. This is an important boundary. Distribution is an infrastructure decision. Knowledge representation is a content contract. Combining the two too tightly makes every platform migration unnecessarily expensive. 8. The Real Problem Appears When Two Documents Disagree Portability is useful until two portable files say different things. Suppose an agent finds two documents describing production access. One was generated yesterday from the current security policy and approved by the IAM owner. The other was created seven months ago before the approval process changed. Both are readable. Both may appear internally consistent. The agent still needs to decide which one should influence an action. This is where the newer OKF work becomes more consequential. The specification begins treating provenance, verification, freshness, lifecycle and attestation as first-class information. The metadata might look something like: Security policy metadata showing its source, verification, status, and expiry. Now the consumer can inspect more than the text. It can ask who produced the concept, what source it came from, whether someone verified it and when it should be reconsidered. That difference is critical once agents are allowed to take action. A support chatbot can survive an occasional stale answer. An agent granting production access cannot. 9. Sometimes the Knowledge Is the Calculation, Not the Number Attested Computation extends this idea further. Consider a finance agent asked for monthly active enterprise accounts. It could search for the last reported number, but that value will become stale almost immediately. The more durable knowledge is the approved calculation: which accounts count as active, how internal tenants are excluded, what date boundary is used, and which source system is authoritative. The knowledge might therefore be closer to: Use the billing ledger as the source of record. Count enterprise tenants with at least one billable event during the calendar month. Exclude internal and suspended accounts. Use UTC month boundaries. That instruction is more valuable than last month’s result because it tells the agent how the organization expects the number to be established. The source article describes Attested Computation in similar terms: a knowledge artifact can describe a sanctioned computation, how it should execute and how the resulting receipt can be verified. This is especially relevant in finance, risk, compliance and operations, where two technically valid queries can still produce different answers because the business definition is not the same as the database schema. 10. OKF Sits Between Knowledge Producers and Knowledge Consumers OKF becomes easier to understand when it is placed beside the technologies it does not replace. RAG helps an agent find relevant information. Agent Skills describe how a task should be performed. MCP exposes resources and tools. OKF deals with the representation and exchange of the knowledge itself. The source article makes this separation explicitly. A useful way to picture the relationship is: AI agent workflow connecting skills, tools, retrieval, and verified knowledge. The important question is not whether organizations already have Markdown, YAML, Git or search infrastructure. They obviously do. The question is whether knowledge producers and knowledge consumers can agree on a small enough contract that the same knowledge can move between them without each integration starting from zero. THE STRATEGIC CONCLUSION The immediate value of OKF is not that it introduces a new document format. Its value is that it separates organizational knowledge from the system currently used to store or retrieve it. That separation matters more as agents become active participants in engineering, operations, support and analytics. A coding agent needs the product rule behind the function it is changing. An operations agent needs the approval policy behind the command it is about to execute. A finance agent needs the approved definition behind the metric it is calculating. Search alone does not solve those problems. Tool access does not solve them either. The difficult part is giving the agent a dependable knowledge object that tells it what the rule is, where the rule belongs, what other rules it depends on, where it came from and whether it is still valid. That is why the most interesting part of OKF is not Markdown. It is the attempt to create a small, portable contract around organizational knowledge. If that contract proves useful, the benefit will not be another knowledge platform. It will be something more practical: the same policy, business rule or operational concept can be read by an engineer, indexed by a search system, consumed by an agent and moved to a different serving platform without being rewritten for each one. For agentic systems, that is a much more concrete problem than “better knowledge management.” It is the difference between an agent that can reach the right system and an agent that understands enough context to work in that system without inventing the missing rules.

EXECUTIVE ABSTRACT

AI agents are becoming capable of working directly inside software environments. They can inspect repositories, invoke APIs, search internal documents and execute multi-step tasks. What they still lack is a dependable way to understand the business and operational knowledge surrounding those systems.

That gap is easy to miss. A coding agent may correctly identify the function that changes a user’s permissions but still not know that privileged access requires a second approver. A support agent may retrieve a policy document but have no way of knowing that the document was superseded last quarter. A data agent may produce a perfectly valid SQL query while using a calculation that finance does not recognize as the approved definition.

Google’s Open Knowledge Format, or OKF, is interesting because it focuses on this layer directly. It does not attempt to replace search, RAG, MCP or agent workflows. Instead, it provides a portable way to package knowledge so that humans, agents and software systems can work with the same artifact. The specification uses familiar components—Markdown, YAML frontmatter, directories and links—but the goal is broader: making knowledge independent of the platform that happens to store or serve it.

1. Reading the System Is Not the Same as Understanding the System

Consider a coding agent working on an internal access-management service. It can inspect the repository and find the function that grants elevated permissions. It can trace the API call and understand which database table is updated. From the code alone, however, it may not know that production access requires approval from both the application owner and security, or that access to one regulated environment expires automatically after 24 hours.

Those rules may be documented somewhere else. One may live in an IAM policy. Another may be in an architecture decision record. A third may exist in an operations runbook. A fourth may only be understood by the security engineer who designed the process.

Coding agent access-decision workflow showing why code alone is insufficient.

This is the problem the source article identifies when it says that the codebase is only part of the system and that the rest of the knowledge may be scattered across wikis, product documents, APIs, shared drives, issue trackers and people’s heads.

For a human engineer, this fragmentation is inconvenient but familiar. People learn which document matters, which colleague to ask and which policy is outdated. An agent has no such instinct unless the organization gives it a structured way to discover that context.

The issue, then, is not simply whether the agent has access to more documents. It is whether the relevant knowledge is represented in a form the agent can navigate, interpret and evaluate.

2. Why the File Format Is the Least Interesting Part

At first glance, OKF looks almost ordinary. A knowledge bundle can be a collection of Markdown files arranged in directories, with YAML metadata attached to individual concepts.

A project might contain something like:

Portable knowledge bundle connecting structured files with humans, AI agents, and search.

A concept can then carry a small amount of structured metadata while keeping the actual knowledge readable in plain Markdown.

YAML policy metadata for privileged access approval.

There is nothing particularly novel about Markdown or YAML themselves. The value is that the artifact is not tied to a particular knowledge-management product, vector database or agent framework. A security engineer can edit the file. A coding agent can read it. A retrieval pipeline can index it. Another system can export or transform it. The knowledge does not have to be rewritten simply because the serving technology changes.

That producer-consumer separation is the important part of OKF. The specification is deliberately independent of a specific model, agent framework or serving system.

The closest comparison is not another document platform. It is an interface contract. OpenAPI did not invent APIs; it gave different tools a common description they could interpret. OKF is exploring a similar idea for knowledge.

3. A Knowledge Bundle Gives the Agent Somewhere to Start

Once the amount of organizational knowledge becomes large, representation alone is not enough. The agent also needs a way to navigate it without loading everything into context.

That is where Knowledge Bundles, Concepts and index.md files become useful.

Imagine a cloud-platform repository with the following structure:

Platform knowledge repository structure with networking, identity, deployment, and compliance files.

If an agent is asked to modify workload identity for a production service, it does not need to read every file in the bundle. It can begin with the root index.md, move into identity/index.md, open workload-identity.md, and follow links to audit-logging.md only if the deployment touches a regulated environment.

The source article refers to this pattern as progressive disclosure: the agent discovers the knowledge one level at a time rather than loading the entire bundle at once.

That design matters because retrieval systems often reduce knowledge to isolated chunks. A hierarchy preserves something retrieval alone may miss: where a concept belongs, what sits next to it and which related concepts should be consulted before acting.

4. RAG Finds the Material; OKF Defines the Material

RAG and OKF are often easy to conflate because both sit close to the knowledge layer, but they solve different problems.

RAG answers a retrieval question: Which piece of information should the system fetch for this task?

OKF answers a representation question: What does that knowledge look like once it exists, and how is it organized so different systems can understand it?

The source makes this distinction explicitly. RAG concerns how relevant knowledge is retrieved, while OKF concerns how that knowledge is represented, organized and exchanged.

The two can sit in the same flow:

Agent workflow for searching knowledge, building context, and applying policies.

The search layer finds the right entry point. The knowledge structure tells the agent what the concept means and where to look next.

This is especially useful in environments where the answer depends on more than one policy. A network rule may only make sense when read alongside a data-residency requirement or a security exception. Similarity search can surface the files; structure helps preserve the relationships between them.

5. Agent Skills Should Not Become Policy Dumping Grounds

The same separation is useful when thinking about Agent Skills.

A Skill might tell a cloud-operations agent how to process a deployment request:

Validate the target environment.
Check the deployment window.
Verify required approvals.
Confirm rollback readiness.
Execute or escalate.

That is procedural knowledge. It describes the order of operations.

It should not also contain every deployment rule, security exception, business continuity policy and regional constraint. If those details are embedded directly inside the Skill, the workflow becomes difficult to maintain because every policy update now requires the Skill itself to be changed.

A cleaner structure is:

Deployment agent structure with skill and knowledge folders for environments, changes, rollback, and compliance.

The Skill tells the agent what sequence to follow. The knowledge bundle contains the rules it should consult during that sequence. The source article draws the same line: Skills describe how an agent performs work, while OKF provides the knowledge needed while doing that work.

This matters because the owners are often different. Platform engineering may own the workflow, security may own the approval policy, and compliance may own the regional restriction. Keeping those concerns separate reflects how the organization actually operates.

6. The Most Useful Knowledge May Sit Beside the Code

The most practical use of a portable knowledge format may not begin with a company-wide knowledge platform. It may begin inside a single repository.

Take a SaaS billing service:

Billing service repository with architecture, business rules, security, and operations knowledge.

Suppose a coding agent is asked to add a new enterprise entitlement. It can inspect the implementation, but it can also read the entitlement rules, check whether the change crosses the PCI boundary and review the deployment constraints before modifying anything.

The source article argues for this type of project-local knowledge because production software cannot always be understood from source code alone. Business and product knowledge often defines the behaviour the code is expected to preserve.

This also changes the relationship between code and documentation. If the agent modifies a rule that affects entitlements, the corresponding knowledge file can be updated in the same pull request. The reviewer sees the code change and the knowledge change together.

That is far more useful than documentation that is updated weeks later, if at all.

7. Some Knowledge Belongs With the Project; Some Belongs With the Company

Not everything should be copied into every repository.

A billing service may need local knowledge about entitlements, event contracts and deployment behaviour. But identity standards, regulatory controls and architecture principles apply across many services.

An agent may therefore consult two scopes:

AI agent connecting project-specific and shared knowledge.

The first answers: What do I need to know about this service?

The second answers: What company-wide rule applies to this service?

The source article makes the same distinction between project-local and organization-wide knowledge, and notes that the central layer may be distributed through Git, object storage, metadata indexes, search or MCP without changing the underlying knowledge format.

This is an important boundary. Distribution is an infrastructure decision. Knowledge representation is a content contract. Combining the two too tightly makes every platform migration unnecessarily expensive.

8. The Real Problem Appears When Two Documents Disagree

Portability is useful until two portable files say different things.

Suppose an agent finds two documents describing production access. One was generated yesterday from the current security policy and approved by the IAM owner. The other was created seven months ago before the approval process changed.

Both are readable. Both may appear internally consistent.

The agent still needs to decide which one should influence an action.

This is where the newer OKF work becomes more consequential. The specification begins treating provenance, verification, freshness, lifecycle and attestation as first-class information.

The metadata might look something like:

Security policy metadata showing its source, verification, status, and expiry.

Now the consumer can inspect more than the text. It can ask who produced the concept, what source it came from, whether someone verified it and when it should be reconsidered.

That difference is critical once agents are allowed to take action. A support chatbot can survive an occasional stale answer. An agent granting production access cannot.

9. Sometimes the Knowledge Is the Calculation, Not the Number

Attested Computation extends this idea further.

Consider a finance agent asked for monthly active enterprise accounts. It could search for the last reported number, but that value will become stale almost immediately. The more durable knowledge is the approved calculation: which accounts count as active, how internal tenants are excluded, what date boundary is used, and which source system is authoritative.

The knowledge might therefore be closer to:

Use the billing ledger as the source of record. Count enterprise tenants with at least one billable event during the calendar month. Exclude internal and suspended accounts. Use UTC month boundaries.

That instruction is more valuable than last month’s result because it tells the agent how the organization expects the number to be established.

The source article describes Attested Computation in similar terms: a knowledge artifact can describe a sanctioned computation, how it should execute and how the resulting receipt can be verified.

This is especially relevant in finance, risk, compliance and operations, where two technically valid queries can still produce different answers because the business definition is not the same as the database schema.

10. OKF Sits Between Knowledge Producers and Knowledge Consumers

OKF becomes easier to understand when it is placed beside the technologies it does not replace.

RAG helps an agent find relevant information. Agent Skills describe how a task should be performed. MCP exposes resources and tools. OKF deals with the representation and exchange of the knowledge itself. The source article makes this separation explicitly.

A useful way to picture the relationship is:

AI agent workflow connecting skills, tools, retrieval, and verified knowledge.

The important question is not whether organizations already have Markdown, YAML, Git or search infrastructure. They obviously do.

The question is whether knowledge producers and knowledge consumers can agree on a small enough contract that the same knowledge can move between them without each integration starting from zero.

THE STRATEGIC CONCLUSION

The immediate value of OKF is not that it introduces a new document format. Its value is that it separates organizational knowledge from the system currently used to store or retrieve it.

That separation matters more as agents become active participants in engineering, operations, support and analytics. A coding agent needs the product rule behind the function it is changing. An operations agent needs the approval policy behind the command it is about to execute. A finance agent needs the approved definition behind the metric it is calculating.

Search alone does not solve those problems. Tool access does not solve them either.

The difficult part is giving the agent a dependable knowledge object that tells it what the rule is, where the rule belongs, what other rules it depends on, where it came from and whether it is still valid.

That is why the most interesting part of OKF is not Markdown. It is the attempt to create a small, portable contract around organizational knowledge.

If that contract proves useful, the benefit will not be another knowledge platform. It will be something more practical: the same policy, business rule or operational concept can be read by an engineer, indexed by a search system, consumed by an agent and moved to a different serving platform without being rewritten for each one.

For agentic systems, that is a much more concrete problem than “better knowledge management.” It is the difference between an agent that can reach the right system and an agent that understands enough context to work in that system without inventing the missing rules.