Implementation guide · OKF v0.2

Choose retrieval by bundle size, not fashion.

OKF makes knowledge portable and connected. It does not prescribe a search engine. This guide turns a bundle into a retrieval plan without pretending that one index fits every corpus.

Decision guide

Start with the smallest system that answers the query.

Small bundle

Traverse first.

Read index.md, follow direct links, then load the selected concept. Filename search and ordinary text search are usually enough.

Good default: repository files

Growing bundle

Filter, then search.

Scan frontmatter into a compact catalog. Filter by type, status, freshness, or tags before lexical search. Preserve links and backlinks for neighborhood expansion.

Good default: metadata plus full text

Large or mixed corpus

Build an external index.

Use lexical, vector, or hybrid retrieval based on measured query quality. Keep each result tied to its source concept and use graph links for a second retrieval hop.

Good default: benchmark two candidates

Agent reading order

Spend context in stages.

Do not load the whole bundle before you know which concepts matter.

01

Read the index

Use index.md as the bundle map and identify likely concept paths.
02

Inspect metadata

Check type, description, status, stale_after, sources, and verification before trusting a candidate.
03

Load selected content

Read the relevant concept or section, then follow only the links needed to resolve the question.
04

Return evidence

Keep the concept path and source IDs with the answer so another consumer can inspect the same trail.

Ranking policy

Trust signals should affect rank, not erase history.

Prefer stable, current, human-reviewed concepts when relevance is otherwise equal. Mark stale or deprecated results clearly and lower their rank when a current replacement exists.

Do not silently delete an unverified or deprecated concept from retrieval. It may explain an old decision, provide a migration trail, or be the only relevant evidence. Let the consumer see why it ranked lower.

Measure it

A benchmark you can reproduce.

1. Write 20 to 50 real questions. Include exact-name lookup, multi-hop questions, stale-policy traps, and questions with no answer.
2. Label acceptable concepts. Record which files contain enough evidence, not a single preferred wording.
3. Compare candidates. Measure recall at a fixed result count, evidence quality, latency, and tokens loaded for lexical, vector, and hybrid approaches.
4. Test lifecycle behavior. Confirm that current material outranks stale or deprecated material without making historical knowledge undiscoverable.
5. Publish the corpus and settings. A retrieval claim has little value without the bundle, questions, index settings, and scoring method.

No universal threshold makes embeddings necessary or unnecessary. Add complexity when your own evaluation shows a meaningful improvement.

Download benchmark kit

Choose retrieval by bundle size, not fashion.

Start with the smallest system that answers the query.

Traverse first.

Filter, then search.

Build an external index.

Spend context in stages.

Read the index

Inspect metadata

Load selected content

Return evidence

Trust signals should affect rank, not erase history.

A benchmark you can reproduce.

Mathias Onea