okf

In 2026 Google published the Open Knowledge Format (OKF), an open way to write knowledge down so that people and AI models read the same files. This project is research into an implementation of OKF that works in real life, and above all inside a company, where the material is messy, the readers are many, the rules change each year, and a wrong answer has a cost.

It tries to answer the questions an organization asks before it lets an AI model answer for it:

• Which knowledge, and for whom?
• Where does each answer come from, and can a person check it?
• Who confirmed it, and is it still true?
• What happens when two documents disagree?
• How does a correction found by a user reach the knowledge?
• Who may see what?

The result is three skills for AI coding agents, in a version for Claude Code and a version for Pi: a producer that writes the knowledge and keeps it current, a validator that checks it against the specification, and a consumer that answers questions from it.

• Why this project
• The Open Knowledge Format
• Compared with other approaches
• Where OKF stops, and where real organizations struggle
• The angle
• The feedback loop
• What this project is made of
• The techniques
• Using the skills
• Installing
• The design in detail

An organization keeps its knowledge in thousands of documents, spreadsheets and databases, in many formats. People want to ask a question in plain words and get an answer they can act on.

Language models answer fluently. They also invent facts, cannot say where an answer comes from, and cannot tell a current rule from one that was replaced years ago. In an organization, an answer that cannot be traced to its source cannot be used.

This project is an implementation of OKF that closes this gap. It reads the material of an organization, agrees with its owner on what the knowledge is for, writes it in the Open Knowledge Format with a source behind each claim, checks it, and keeps it current as the material changes. When a person asks a question, the answer comes with a reference after each claim, the trust level of what it rests on, and a warning when a fact is not yet reviewed, has expired, or changed after its check. When the knowledge does not cover a question, the answer says so.

OKF is an open specification from Google. It gives a standard form to a pattern many teams found on their own, the LLM wiki: the knowledge an AI agent needs is kept as a folder of Markdown files, each with a small block of YAML at the top.

OKF is a documentation convention, nothing more. It has no service, no database, no runtime and no required software. In the words of the specification: "If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it."

A collection of knowledge in this format is a bundle. Each Markdown file of a bundle, apart from its index and log files, is a concept: a table, a metric, a rule, a procedure, a role. The YAML block at the top of the file, the frontmatter, holds the few fields a reader uses to decide about a concept before reading it. The Markdown body holds the content.

Version 0.2 of the specification lets a reader answer five questions about a concept from its frontmatter:

OKF makes it easy to connect a language model to the knowledge of an organization, without the usual flaws of these models, such as invented facts (hallucinations). The model works from knowledge prepared, sourced and checked in advance, and not from its memory. OKF settles the questions of trust in a deterministic way. The trust tier is read from the verified field by a fixed rule. Staleness is a comparison of two dates. A figure comes from a computation written in advance, and code with no model in it checks that the computation ran as written.

The sources:

• The specification: github.com/GoogleCloudPlatform/open-knowledge-format, file SPEC.md. Google's blog posts point to the okf folder of github.com/GoogleCloudPlatform/knowledge-catalog for the specification, the samples and the reference implementations.
• Introducing the Open Knowledge Format, Google Cloud blog, June 2026.
• Open Knowledge Format v0.2 tackles agentic trust, Google Cloud blog, July 2026.

Language models read well today, and a large context window holds a long document whole. The knowledge of a company is larger than that. Take 40 MB of text, the procedures, contracts and reports of a single department. At about four characters per token, a common estimate for English text, that is some ten million tokens, far more than a model reads at once. To answer from it, a model searches the files, opens the ones that look relevant, reads them, and builds its answer from what it happened to find.

Now multiply by the people who ask. Each employee asks in a session of their own, and each session starts the same work again from nothing: the same search, the same reading, the same tokens spent. The understanding the model built is lost when the session ends. Two employees who ask the same question can get two different answers, depending on the files each model opened, and nobody checked either of them.

A bundle does the reading once. The producer reads the material, writes what it means with a source behind each claim, and independent readers check the result. Each later question starts from the overview and the index, opens the few concepts it needs, and follows a footnote to the passage when it needs proof. The work of understanding the material is done once, checked once, and shared by everyone who asks. The same question is answered from the same checked concepts, and a correction made once reaches all the readers.

Retrieval-augmented generation (RAG) is the common way to give a model access to a large set of documents. The documents are cut into passages, each passage is turned into a vector that captures its meaning, and the vectors go into a search index. At each question, the system finds the passages closest to the question and gives them to the model.

OKF is often compared with RAG, and the comparison misses the point. RAG is a way to fetch text at the moment of a question. OKF is a format for knowledge that was already understood, written down and checked. RAG answers "which passages look like my question?". A bundle answers "what does the organization know about this, where does it come from, and how far can it be trusted?". One is a search method, the other is the content.

A bundle needs no search system to be useful. Its index files and its frontmatter let a model find its way one step at a time: the overview, then a folder, then the description of a concept, then the concept. This is a cheap and light alternative: a folder of files read by an agent, with no vector index, no embedding pipeline and no server to run. It works in the environments most people use, such as a coding agent or a desktop assistant, and that covers most of the scope we expect for this project.

It does not replace RAG. When the material is very large (millions of documents), changes by the hour, or must be searched in its raw wording (each email that mentions a supplier, each contract with a given clause), a search index is the right tool. Reading indexes step by step does not scale to that size, and a bundle covers the angle it was made for, not the whole of the raw material.

In the end, the two are complementary. A bundle is a better source for RAG than raw documents:

• Each concept is a complete unit of meaning with a one-sentence description. The index holds whole ideas, not passages cut in the middle of a table.
• The frontmatter becomes a set of filters. A search can keep only the concepts a person reviewed, leave out the deprecated and stale ones, and return each passage with its source.
• The conflicts between documents are settled before anything is indexed. The search no longer returns two contradicting statements side by side.
• The index is smaller: it holds the knowledge, not the copies and drafts of the documents.

Combining the two techniques would improve both the speed of the search and the quality of what it returns.

OKF defines how knowledge is written down. The specification leaves out, on purpose, how knowledge gets into a bundle, how it is judged and how it is served. A system that serves an organization needs these answers, and real material makes them hard:

• What to extract. The same material serves readers who need very different things, and a bundle that tries to serve all of them serves none well. See the angle.
• How to read real material. Material comes as scanned PDFs, spreadsheets, databases with no file to point at, earlier knowledge bases, and documents that cite other documents. See reading the material.
• How to judge a bundle. A bundle can conform to the format and still be wrong. The format proves that the files can be read, not that the claims match their sources, nor that the bundle answers the questions it was made for. See quality metrics and delivery.
• How to stay current. Policies are revised, a database changes, a new document replaces an old one. The format records that a concept changed, not how an update finds what changed and corrects the old statement. See the feedback loop.
• Where trust comes from. Documents state their own trust: "checked by the finance team in March", "to be verified". The format records who confirmed a concept, not how the words of the material become those fields, nor who may confirm. See trust, conflicts and lifecycle.
• Conflicting sources. Two documents state different facts about the same thing, and the format gives no rule to settle them. See trust, conflicts and lifecycle.
• Running a computation. The format names the executor and the attester of a computation as interfaces. Nothing writes or runs them. See derived answers, checks and computations.
• Learning from use. When a user finds a correction or a new fact, nothing carries it back to the writer of the bundle. See the feedback loop.
• Confidentiality. Material names companies and people, gives codes to its own readers, and sometimes may not leave the organization at all. See confidentiality.
• Many bundles and many readers. A question can need several bundles, and the format describes one. See the consumer.
• Long work. A large set of documents takes several working sessions, and a session can end at any moment. See updates, pause and resume.

Show the same photograph to five people and ask each one to describe it. A child names the dog chasing a ball. A photographer talks about the light, the framing and the depth of field. A painter talks about the colors, the warm foreground against a cold sky. A detective notes the number plate of the parked car and reads the time of day from the shadows. An estate agent describes the house behind the garden. Each description is right, and none of them serves the other four readers.

The material of an organization works the same way. Take the quality documents of a company: its policies, procedures, forms and records.

• An employee needs day to day answers: who approves a purchase order, what to do after a near miss, which form to fill in for a supplier complaint.
• A consultant needs to see how the company meets the requirements of a standard such as ISO 9001: which procedure covers which clause, what evidence the company keeps, and where a requirement is not covered.
• A documentation officer needs the form of the set itself: the kinds of documents, their mandatory clauses and the order of those clauses, the numbering, the layout, the approval block and the revision table.

Three readers, three bundles, from the same documents. Beauty is in the eye of the beholder: the angle is as important as the data. This project keeps the angle as a companion to each bundle. The angle is written in the context of the bundle, approved by its owner, and summarized in the overview that each reader of the bundle opens first.

Could one bundle serve all the angles? It could, at a cost. A bundle made for all readers is larger, takes longer to write and to check, and makes each reader search through what does not concern them. This project creates one bundle per angle from the same sources. This saves time when the bundles are written and saves the readers' time. Above all it saves tokens each time a question is answered, because the model reads a smaller bundle made for its reader.

The angle is agreed with the owner of the material before any concept is written, and its questions become the test of the bundle. The conversation itself is described in the angle conversation.

The folder sample-bundles/ shows three angles on the same Wikipedia pages about Greek mythology: the family tree, the stories by theme and the words from the myths, each with questions to try.

Knowledge in a company does not stand still. A procedure is revised, a supplier changes, a regulation comes into force, a figure in last year's report turns out to be wrong. An answer drawn from knowledge that is out of date is worse than no answer, because people act on it.

Most knowledge systems treat knowledge as something written once and read many times. This project treats it as an exchange between the people who use the knowledge and the people who own it.

When a question leads a user to something new (a correction, a fact the bundle did not hold, a result checked against live data), the consumer offers to write it up as a report, with its evidence. Nothing is written without the user's approval. At the next update, the producer reads the report, checks the evidence, and brings the bundle up to date. The owner of the knowledge keeps the final word. The next person who asks the same question gets the answer from checked knowledge, with no new search.

The material itself feeds the loop too. When new documents arrive, the producer recognizes what it has already read, reads only what changed, and corrects or retires the old statements, which stay on record with their dates. An expiry date marks a fact that must be checked again, and the consumer warns about a fact past that date.

The technical side is in reports to the producer and updates, pause and resume.

The figure shows the proposed cycle of a bundle, from the material to the answers and back. This project aims a real life anwser to the OKF implementation that goes beyond its raw mechanics.

• okf-produce writes a bundle from material and keeps it current. Most of its work is a model following written instructions: reading the material, agreeing the angle with the owner, writing the concepts. A few deterministic commands do the listing, the counting and the comparing. A run ends with the validator.
• okf-validate checks a bundle against the text of the specification. It is deterministic Python, and it also runs as a plain command in a pipeline, with no AI agent.
• okf-answer answers questions from one bundle or several, with a reference and the trust signals for each claim. It runs the computations a bundle carries, and it sends the findings a user confirms back to the producer as reports.

The three skills exist in two versions with the same behavior: skills-claude/ for Claude Code and skills-pi/ for the Pi coding agent.

Explainability and reproducibility are basic requirements for AI in an organization. A person must be able to see why an answer was given and check it against its source. The same input must give the same result.

This project meets both in two ways. First, each claim of a bundle and of an answer points to the passage it comes from. Second, each step that needs no judgment is done by deterministic Python: listing and hashing files, reading a structured source, writing the index files, counting footnotes and coverage, checking a bundle against the specification, checking that a computation ran as approved, deriving trust tiers and comparing dates.

Code gives the same result each time, and it costs no tokens. A model asked to compare the hashes of thousands of files would spend tokens on it, and could still miscount. The model keeps the steps that need meaning: reading prose, agreeing the angle, writing the concepts, answering a question.

• A bundle holds knowledge, not answers. The test of a bundle is a reader with nothing but the bundle, who answers the questions of its angle. Some questions are held out: their answers are kept out of the bundle. A right answer to such a question shows that the bundle holds the knowledge to derive it.
• Independent readers. Separate model instances, which did not write the bundle, check each concept against the passages its footnotes name, answer the test questions, and compare the answers with the expected ones. The verdict of a reader is never the writer's, and a judgment the writer makes alone is marked as such in the review file.
• Trust comes from people. A concept counts as reviewed by a person only when a person confirmed it. The model never marks its own work as checked.
• Conflicts settled by a written rule. When two sources disagree, a written rule decides which statement holds, and both stay on record. A conflict the rule cannot settle is shown as an open question.
• A memory of production. Beside each bundle, this project keeps the record of its making: the angle, the rules, the quality bars, each source with its fingerprint (a hash), and each run. An update reads only what changed.
• Gradual reading. The consumer reads the bundle named in the question, its overview first, the frontmatter of a concept before its body. It asks before it opens another bundle. The model's context stays free for the question.
• Sanctioned computations. A figure comes from a computation written in advance, not from a query the model makes up on the spot. A separate agent runs it. A script the producer writes with the bundle, the attester, then checks that the query that ran is the approved one, with the values the question asked for.
• Confidentiality. The angle decides what may leave the organization, how people are named, and which values stay out. Secrets never enter a bundle, and the operating system decides who reads what.
• Strict compliance. The bundles of this project pass a validator built from the text of the specification, with no error and no warning. Each addition uses the room the specification gives for extra fields and types. Any OKF reader can read these bundles.

A bundle is a folder of text files, and so is the context beside it. Both are ready for git by nature, and the specification recommends git to distribute a bundle, for its history, its record of who changed what, and its diffs. Each run of the producer adds to this: a line in the log of the context, a line in the log of the bundle for each concept it changed, a record of the run, and the saved reports of its checks.

The producer checks its own output, and independent readers check the producer. In a company, a team can add one more layer with git, a person between a change and the clients. Each run, a creation or an update, then ends as a pull request: a proposed change to the bundle, not yet published. A lead reviewer reads the changes concept by concept, with the review file of the run beside them. When the changes make sense, the reviewer merges them, and the clients read the new version. When they do not, the reviewer rejects them, and the published bundle stays as it was.

Around this review, the usual tools of git apply:

• A pipeline runs the validator with --strict on each pull request and blocks a merge that fails.
• The rules of the repository give each folder its owners. A change to the finance metrics then also needs the approval of the finance team.
• The history answers the questions of an audit: what the bundle said on a given date, what changed, and who approved it. A change that went wrong after its merge is reverted.

The skills are used in a conversation with the agent. The producer is called by a sentence that names the material and the output folder:

produce a bundle from ~/material/quality-system into ~/bundles/quality

The producer then looks at the material, agrees the angle with you one topic at a time, shows one sample concept of each type for your approval, writes the bundle and checks it. At the end it points to a review file in the context, with the test questions, the answers of a fresh reader and what the checks found. You read it after the run.

Later runs update the bundle, with new material, your notes on the review, or the reports of the consumers:

update the bundle in ~/bundles/quality with ~/material/new-procedures/
update the bundle in ~/bundles/quality: I read the review and accept the run

A long run stops and goes on in another session:

pause
resume the run of the bundle in ~/bundles/quality

The consumer runs in the folder that holds the bundle folders, and the question names the bundle:

/okf-answer quality who approves a purchase order above the delegation limit?
give the same answer in JSON
quote the passage of the source
save this answer
based on this new finding, create an update report

The validator checks a bundle, or the context beside it:

validate the bundle in ~/bundles/quality/quality-bundle

In a pipeline, with no agent, the validator is a command. The exit code is 1 when the bundle fails:

skills-claude/okf-validate/okf-validate ~/bundles/quality/quality-bundle --strict

In Pi, a skill is called as /skill:okf-answer, and the sentences are the same.

These examples call the skills in a conversation with a coding agent, which suits a team that builds and tests its bundles. A production system can hide this layer behind an application of its own: a page where the owner of the material adds documents and answers the questions of the angle, a screen to review each run, and a chat where employees ask their questions, with the sources one click away. The agent and its skills would run behind the application, on a server.

• An AI coding agent: Claude Code or Pi.
• Python 3.10 or later, with PyYAML.
• Tools that read the formats of the material, such as those below.

Claude Code loads personal skills from ~/.claude/skills/, where a skill can be a link to a folder elsewhere. The commands clone the repository and link the three skills there. The three skills are installed together, because the producer calls the validator in the folder beside its own.

git clone https://github.com/wmahfoudh/okf.git
cd okf
mkdir -p ~/.claude/skills
for skill in okf-produce okf-validate okf-answer; do
  ln -s "$(pwd)/skills-claude/$skill" ~/.claude/skills/$skill
done

Pi loads skills from ~/.pi/agent/skills/. The commands clone the repository and link the three skills there:

git clone https://github.com/wmahfoudh/okf.git
cd okf
mkdir -p ~/.pi/agent/skills
for skill in okf-produce okf-validate okf-answer; do
  ln -s "$(pwd)/skills-pi/$skill" ~/.pi/agent/skills/$skill
done

The readers of the producer and the runner of the consumer work in a context of their own, through the subagent tool. The tool comes from an example extension shipped with Pi, which Pi does not load by default. Copy its two files from the package of the running Pi, then link the agents:

PI_PKG="$HOME/.pi/agent/install/releases/$(cat ~/.pi/agent/install/current-version)/node_modules/@earendil-works/pi-coding-agent"
mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents
cp "$PI_PKG/examples/extensions/subagent/index.ts" "$PI_PKG/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/
for agent in okf-produce/agents/okf-derivation-reader okf-produce/agents/okf-comparison-reader \
             okf-produce/agents/okf-faithfulness-reader okf-produce/agents/okf-writer \
             okf-answer/agents/okf-runner; do
  ln -sf "$(pwd)/skills-pi/$agent.md" ~/.pi/agent/agents/$(basename "$agent").md
done

For Pi installed with npm, the package is "$(npm root -g)/@earendil-works/pi-coding-agent". The two files are copied, not linked, because pi update removes the folder of an old release. Copy them again after an update. Without the extension, the consumer runs a computation itself, under the same rules. The producer needs the extension for its independent readers.

Each skill folder installs with pip and gives its command on the path, for CI and pipelines:

git clone https://github.com/wmahfoudh/okf.git
cd okf
python3 -m venv .venv
.venv/bin/pip install skills-claude/okf-validate
.venv/bin/okf-validate <bundle-folder> --strict

Each suite runs on its own, from the repository root, with pytest installed:

python3 -m pytest skills-claude/okf-validate
python3 -m pytest skills-claude/okf-produce
python3 -m pytest skills-claude/okf-answer

The suites of skills-pi/ run the same way.

• pdftotext (Poppler) reads the text of a PDF.
• tesseract reads the text of a scanned PDF or an image, with the language data of the material.
• pandoc converts Word, OpenDocument, HTML and EPUB files to text.
• LibreOffice converts older Office files and spreadsheets, with no window.
• openpyxl lets a Python script read an Excel workbook.
• psql queries a PostgreSQL database. Version 16 or later has the \bind command, which a run instruction of a bundle can use.
• sqlite3 queries a SQLite database.

The parts of the system, the files it writes, each step of a run and the reason behind each rule are described in DESIGN.md.