OKF and RAG: What I Learned While Thinking Through Agentic Knowledge Systems

OKS and RAG Infographic

If you are short on time, go through this infographic, should give you most insights.

OKF and RAG Infographic

Introduction

I have been thinking more deeply about how knowledge should be structured for AI agents, especially in enterprise environments where information is spread across docs, wikis, dashboards, tables, runbooks, tickets, and tribal knowledge.

One concept I recently explored is OKF, or Open Knowledge Format, and how it compares with RAG, or Retrieval-Augmented Generation.

My initial question was simple:

Is OKF a replacement for RAG?

After thinking through it, my answer is no.

OKF and RAG solve different problems.

RAG helps an AI system retrieve relevant information.

OKF helps an AI system understand how knowledge is structured, connected, owned, and maintained.

That distinction is important.

The simple mental model

The easiest way I now think about it is this:

RAG = search and evidence retrieval

OKF = structure, metadata, and relationships

LLM = reasoning and response generation

Traditional RAG is like searching a library.

OKF is like having a map of the library.

RAG can find text that looks relevant to a question. OKF can help the system understand which page is official, which one is outdated, which dashboard is connected to which metric, who owns a dataset, what runbook applies to a failure, and which system depends on which service.

That makes OKF very useful in domains where knowledge is not just text, but a network of connected concepts.

What OKF actually gives you

The way I understand OKF is that it gives you a structured way to represent knowledge as small, readable pages.

Each page can describe one important object, such as:

A metric
A dashboard
A data table
A service
A policy
A product capability
A runbook
An incident
A decision record
An API

Each page can have metadata and links to other pages.

For example, a metric page may say:

id: metric_refund_volume
type: metric
title: Refund Volume
owner: billing-data-platform
tags:
  - finance
  - refunds
  - quickbooks

links:
  - target: table_refund_events
    relationship: computed_from
  - target: dashboard_refund_ops
    relationship: visualized_in
  - target: runbook_refund_anomaly
    relationship: troubleshooting

This is much richer than a random chunk of text sitting inside a vector database.

The page is not just saying, “Here is some information about refund volume.”

It is saying:

This is a metric.
This is the owner.
This is the source table.
This is the dashboard where it appears.
This is the runbook to use when something looks wrong.

That structure matters when building AI agents.

How does an LLM actually use OKF?

One thing that became very clear to me is this:

An LLM does not magically read 1,000 OKF pages and understand all of them at once.

You still need a retrieval and navigation layer.

The LLM uses OKF only when your system gives it tools to find and open relevant pages.

In a real system, I would imagine exposing tools like:

search_okf(query, filters)

read_okf_page(id)

get_linked_pages(id, relationship)

retrieve_supporting_chunks(query, filters)

The agent can then follow a controlled flow.

For example:

User asks a question
        ↓
Search relevant OKF pages
        ↓
Open the top matching pages
        ↓
Inspect typed links
        ↓
Follow only useful links
        ↓
Retrieve supporting evidence using RAG
        ↓
Generate the final answer

The important point is that OKF does not remove the need for search.

It improves what happens before and after search.

What happens if I have 1,000 OKF pages?

This was one of my main questions.

If I have 1,000 OKF pages, how will an LLM navigate them?

The answer is: it should not navigate them blindly.

The system should index those pages and use a controlled retrieval strategy.

A practical setup could look like this:

OKF repository
        ↓
Parse YAML metadata
        ↓
Parse Markdown content
        ↓
Extract links
        ↓
Create vector index
        ↓
Create keyword index
        ↓
Create graph index
        ↓
Use all three at runtime

The vector index helps with semantic search.

The keyword index helps with exact names, acronyms, owners, IDs, and systems.

The graph index helps with navigation across relationships.

That last part is where OKF becomes interesting.

With traditional RAG, I may retrieve the top 10 chunks that are semantically similar to the user’s question.

With OKF plus RAG, I can do something more intentional:

Find the relevant metric page.
Then follow computed_from to the source table.
Then follow visualized_in to the dashboard.
Then follow troubleshooting to the runbook.
Then use RAG to retrieve supporting evidence.

This gives the agent a path through knowledge, not just a bag of similar chunks.

Why typed links matter

A normal hyperlink is useful for humans, but it is not enough for agents.

A typed link is much more useful.

For example:

links:
  - target: table_customer_subscriptions
    relationship: source_of_truth

  - target: metric_active_subscribers
    relationship: related_metric

  - target: runbook_subscription_anomaly
    relationship: troubleshooting

  - target: incident_2026_06_renewal_pipeline
    relationship: known_issue

Now the agent can make better decisions.

If the user is asking a definition question, follow source_of_truth.

If the user is asking a debugging question, follow troubleshooting and known_issue.

If the user is asking an ownership question, follow owner.

If the user is asking a lineage question, follow computed_from.

This is where OKF starts to feel less like documentation and more like a knowledge map.

The agent should not wander

One mistake I would avoid is letting the agent follow every link it sees.

That can quickly become noisy and expensive.

I would define a navigation policy.

Something like:

Start with the top 5 OKF pages from hybrid search.

Expand only selected relationship types.

Limit traversal depth to 2.

Load a maximum of 10 to 12 OKF pages.

Prefer pages marked as current.

Ignore deprecated pages unless the user asks about history.

Stop when there is enough evidence to answer.

This keeps the agent focused.

It also makes the system easier to debug.

When an answer is wrong, you can inspect which OKF pages were retrieved, which links were followed, and which chunks were used as evidence.

That is much harder when everything is just unstructured chunks in a vector store.

A concrete example

Imagine a user asks:

Why did refund volume spike for QuickBooks users in India last week?

With traditional RAG, the system might search across docs and retrieve chunks from:

Refund policy docs
Dashboard notes
Support ticket summaries
Billing pipeline documentation
Incident reports

That may work.

But it can also miss key context.

For example:

Which refund metric is official?

Which table is the source of truth?

Does India mean billing country, user country, or tax entity?

Which dashboard should be trusted?

Was there a related incident?

Is there a runbook for refund anomalies?

With OKF plus RAG, the agent can follow a more reliable path.

It may first retrieve an OKF page like:

metric_refund_volume

That page says:

id: metric_refund_volume
type: metric
title: Refund Volume
source_of_truth: table_refund_events

dimensions:
  - billing_country
  - product_line
  - refund_reason

links:
  - target: table_refund_events
    relationship: computed_from
  - target: dashboard_refund_ops
    relationship: visualized_in
  - target: runbook_refund_anomaly
    relationship: troubleshooting

Then the agent opens the source table page:

id: table_refund_events
type: table
title: Refund Events
freshness_sla: hourly
owner: billing-data-platform

links:
  - target: incident_payment_gateway_duplicate_capture
    relationship: recent_incident

Then it opens the incident page:

id: incident_payment_gateway_duplicate_capture
type: incident
title: Payment Gateway Duplicate Capture Issue

affected_regions:
  - IN

affected_products:
  - QuickBooks

links:
  - target: runbook_refund_anomaly
    relationship: remediation

Now the agent has a much better path.

It knows the official metric, the source table, the dashboard, the related incident, and the runbook.

Then traditional RAG can retrieve supporting chunks from incident notes, dashboard annotations, ticket summaries, and SQL documentation.

The final answer becomes much more grounded:

Refund volume appears to have spiked because of a payment gateway issue that caused duplicate captures for some QuickBooks users in India. The official refund metric is computed from the refund events table using billing_country and product_line dimensions. The spike is visible in the Refund Ops dashboard and aligns with the incident window. Support tickets mentioning duplicate charges increased during the same period.

The difference is subtle but important.

Traditional RAG retrieves evidence.

OKF helps the agent know which evidence path to follow.

Should I use OKF or traditional RAG?

My current view is that most teams should not start by converting everything into OKF.

That can become over-engineering.

I would start with traditional RAG for broad document search.

Then I would add OKF for high-value knowledge objects.

For example:

Top business metrics
Critical services
Important data tables
Common runbooks
Frequently used dashboards
Product capabilities
Core policies
Major APIs
Recurring incidents
Decision records

That gives the best of both worlds.

Use RAG for broad coverage.

Use OKF for curated, reusable, high-signal knowledge.

When traditional RAG is enough

I would probably stick with traditional RAG when the content is mostly standalone.

For example:

FAQs
Help articles
PDFs
Legal documents
Policy documents
Meeting notes
General documentation

If users mostly ask direct questions and the answer usually lives in one or two documents, traditional RAG with good chunking, metadata, reranking, and citations may be enough.

Adding OKF in that case may not be worth the effort.

When OKF plus RAG is worth it

I would consider OKF when the domain has many connected objects.

For example:

Metrics connected to dashboards

Dashboards connected to tables

Tables connected to owners

Services connected to APIs

APIs connected to runbooks

Incidents connected to systems

Policies connected to products

Products connected to capabilities

In these cases, the problem is not just retrieval.

The problem is context.

The system needs to know what something means, where it comes from, what owns it, what depends on it, and what to do when it breaks.

That is where OKF can add real value.

The design I would use

If I were designing this system, I would not choose between OKF and RAG.

I would combine them.

My architecture would look something like this:

1. Keep traditional RAG for broad unstructured content.

2. Create OKF pages for important knowledge objects.

3. Index OKF pages using vector search and keyword search.

4. Store OKF links in a graph index.

5. At runtime, retrieve seed OKF pages.

6. Follow typed links with strict limits.

7. Retrieve supporting raw chunks using RAG.

8. Ask the LLM to answer from the retrieved context only.

9. Log which pages, links, and chunks were used.

The runtime flow could look like this:

def answer(question):
    seed_pages = hybrid_search_okf(
        query=question,
        top_k=5
    )

    linked_pages = follow_links(
        pages=seed_pages,
        relationships=[
            "source_of_truth",
            "computed_from",
            "visualized_in",
            "troubleshooting",
            "known_issue"
        ],
        max_depth=2,
        max_pages=10
    )

    okf_context = rerank(
        pages=seed_pages + linked_pages,
        query=question,
        top_k=8
    )

    evidence = rag_search(
        query=question,
        filters={
            "linked_okf_ids": [page.id for page in okf_context]
        },
        top_k=12
    )

    return generate_answer(
        question=question,
        okf_context=okf_context,
        evidence=evidence
    )

This feels like a practical middle path.

Not everything needs to be a curated OKF page.

Not everything should be a loose chunk in a vector database either.

My main takeaway

The biggest learning for me is this:

RAG helps the LLM find information.

OKF helps the LLM navigate knowledge.

That difference becomes very important when building enterprise AI systems.

As AI agents move from simple Q&A to deeper workflows, they will need more than semantic search. They will need maps, relationships, ownership, freshness, lineage, and trusted sources.

That is where OKF can complement RAG.

I would not use OKF everywhere.

But for the important parts of an enterprise knowledge system, especially metrics, data, services, dashboards, runbooks, and decisions, it can make the AI experience much more reliable.

My current mental model is:

Use RAG for reach.

Use OKF for structure.

Use both for trustworthy agentic knowledge systems.