Question: Recommended retrieval architecture for large OKF bundles

[madanshettys]

Recommended retrieval architecture for large OKF bundles

Hi OKF team,

First, thank you for publishing the Open Knowledge Format. I really like the idea of representing enterprise knowledge as portable, human-readable Markdown bundles. It provides a clean and interoperable way of organizing knowledge for both humans and AI agents.

I have a question regarding retrieval for large-scale deployments.

From my understanding, OKF is intentionally a knowledge representation format rather than a retrieval system. However, I'm curious about the recommended architecture when working with very large knowledge bases.

For example, consider an organization with hundreds of thousands (or even millions) of OKF concept files.

If an AI agent relies primarily on traversing index.md files or following Markdown links, could this introduce a "needle in a haystack" problem where the relevant information exists in the knowledge bundle but isn't selected as context for the LLM?

With Retrieval-Augmented Generation (RAG), semantic retrieval using embeddings helps identify the most relevant documents before generation.

I'd love to understand the intended architecture for OKF in these scenarios.

Some questions that came to mind are:

• Is it expected that OKF consumers build a vector or hybrid retrieval layer on top of OKF bundles?
• Or is the expectation that agents can navigate the knowledge graph directly without semantic retrieval?
• Are there any recommended best practices for deploying OKF at enterprise scale?

I'm asking because I find OKF very interesting and would like to better understand how it scales in enterprise environments.

Thank you!

[danielcdmconsultores]

Hi friend,

I’m not sure if this helps you, but your question reminded me of how I’m implementing OKF and also having an agent that automatically updates documentation + human input.
In the other agents I use, I configure my AGENTS.md with something similar to the following. What do you think?

_____ START AGENTS.md

Project Agent Guide
This document defines how any agent should work within this repository.

It does not contain project‑specific knowledge.
That knowledge lives exclusively in okf/.

Reading Order
Before starting any task:

Read README.md.
Read okf/index.md.
Read only the documentation related to the task.
Review the affected code.
Do not assume that all documentation is relevant for every task.

Source of Truth
Priority order:

Code
OKF
README
If you detect inconsistencies:

Use the code as the reference;
Update OKF as part of the task.
Never leave outdated documentation.

Knowledge Base
All technical documentation lives in okf/ and follows the OKF SPEC v0.2.

Each concept document in okf/ must include a YAML Frontmatter header with metadata (type, title, description, resource, tags, generated, verified, sources).

Example layout:

okf/

• index.md (Reserved file §3.1: Navigable index)
• log.md (Reserved file §3.1: OKF v0.2 update history)
• architecture/
• concepts/
• modules/
• decisions/
• interfaces/
• workflows/
• conventions/
• roadmap/
• changelog/
  Each document should describe a single topic.
  Avoid huge files; prefer many small, linked documents.

Workflow
For each task:

Understand.
Locate the relevant documentation.
Implement.
Verify.
Update OKF if the project knowledge has changed.
What to Update
Update OKF when any of the following change:

architecture
modules
interfaces
technical decisions
conventions
functional flows
relevant configuration
Do not update documentation for purely internal changes that do not affect project knowledge.

Quality
Changes should be:

Small
Coherent
Easy to review
Compatible with existing style
Avoid unrelated refactorings.

Validation
Before finishing:

Verify the code works.
Run relevant tests (if any exist).
Ensure the documentation remains correct.
Objective
Each change should improve at least one of:

clarity
maintainability
consistency
documentation
code quality
Never sacrifice simplicity for unnecessary sophistication.

_____ END AGENTS.md