The OKF Bundle#
The Open Knowledge Format (OKF) bundle is the on-demand tier of
Facility Knowledge: a directory of Markdown
concept documents that the osprey_facility_knowledge MCP server serves to
the agent only when a task calls for them. This page covers what OKF is, how to
structure a bundle, and how to author, validate, and serve it.
What Is the Open Knowledge Format?#
The Open Knowledge Format is a convention for representing a body of knowledge as cross-linked Markdown files with YAML frontmatter, so the same files can be read by a person, tracked in version control, and navigated by an agent. It was introduced by Google; see the Google Cloud blog post for the original description.
OSPREY uses OKF for facility narrative knowledge — the descriptive,
human-authored context that does not belong in the channel database (that is the
Channel Finder) or the logbook (that is
ARIEL). A bundle of OKF documents is served to the agent on
demand by the osprey_facility_knowledge MCP server.
The Core Ideas#
OKF rests on four ideas.
1. Typed documents. OKF calls each file a concept — “a single unit of
knowledge, represented as one Markdown document.” Every concept is a Markdown
file with a YAML frontmatter block whose type field is what makes the corpus
machine-navigable: it lets indexes group documents and lets the agent tell
what kind of document it is. See the full frontmatter schema under
Structure & Config below.
2. Progressive disclosure. Every directory carries an auto-generated
index.md that summarizes its contents. This lets the agent browse the index
to discover what exists and then read only the document it needs, instead of
loading the whole bundle. Regenerate these indexes with
osprey knowledge regen-index after adding or removing documents.
3. Cross-links. Documents reference each other with bundle-relative Markdown links, so the agent can follow references from one document to related ones:
See [Personnel Safety System](/subsystems/pss.md) for the interlock hierarchy.
Facility links. A document names a channel, a device or a place of the
facility file with a facility: link to its address, device id or place id. Wrap the whole
destination in angle brackets when the address holds a space:
Read [the X position](facility:SR:DIAG:BPM:01:POSITION:X) of [BPM 01](facility:SR/BPM01).
Check [the gauge](<facility:SECTOR 1 GAUGE>) first.
A place is linked as facility:place/<id>, as in facility:place/SR/S01;
a channel or device whose id is literally place/<id> takes the link first.
osprey build warns link-dangling for each link the facility file does not
hold. The KNOWLEDGE panel shows the linked record when you hover over the link;
a click opens it in the panel’s Graph view when the deployment has one
(Browsing the Graph).
4. Validation levels. OKF distinguishes two strictness levels, so
half-finished stubs and finished documents can coexist. Consuming validation
requires only a type (a tolerant reader check); authoring validation also
requires title and description. osprey knowledge validate checks
your bundle at the authoring level. It also fails when an index.md no longer
matches its directory; osprey knowledge regen-index fixes that.
Working with a Bundle#
There is no required layout beyond the top-level directory — organize
sub-directories in whatever structure suits your facility, from a single
flat folder to a deep tree. The server discovers whatever is present;
the index.md files are generated by the CLI (run
osprey knowledge regen-index after adding or renaming documents). A
conventional starting shape groups documents by kind:
data/facility/knowledge/
├── index.md ← bundle root index (CLI-generated)
├── subsystems/ ← how the major systems work (vacuum, timing, safety…)
│ ├── index.md ← sub-directory index (CLI-generated)
│ ├── power-supply-system.md
│ └── timing-system.md
├── devices/ ← device classes and families (BPMs, ion pumps…)
│ ├── index.md
│ └── magnet-power-supply.md
├── procedures/ ← operational checklists and recovery steps
├── physics/ ← calibrations, beam-behavior notes
└── references/ ← glossaries, standards, safety rules
The demo preset ships an Example Research Facility bundle
you can read as a worked example, then replace with your own.
Author the bundle in your profile (data/facility/knowledge/ in the deployment repository),
not in the built project: each build copies the profile’s data/ tree
over the project’s, so an edit made in the project is lost on the next
rebuild. See Build Profiles.
---
type: Subsystem
title: Power Supply System
description: DC power supplies for all storage-ring magnets.
tags: [magnets, power-supplies, PSS]
---
# Power Supply System
...document body...
Required frontmatter fields (authoring level):
Field |
Description |
|---|---|
|
Document type (a short free-form label) |
|
Human-readable title |
|
One-sentence summary used in indexes and search |
Optional fields: tags (list of strings). Documents cross-reference
each other with bundle-relative Markdown links, as shown in
The Core Ideas above.
Pointing the server at the bundle. Add a facility_knowledge block
to config.yml:
facility_knowledge:
bundle_path: data/facility/knowledge
Relative paths are resolved against the project root — the deployment
repo, not the build/ render inside it, which every osprey build
re-creates. For the demo preset the example bundle is
scaffolded into data/facility/knowledge/ automatically.
Two consequences are worth knowing before you debug either of them.
The mounted bundle hides the one baked into the image. Each build copies
the profile’s data/ tree into the terminal image, so the image ships a
bundle of its own — and the mount covers it. That is intended: the bundle is
operational knowledge that changes between image builds. Edit the
deployment’s bundle to change what a running terminal sees; edit the
profile’s to change what a fresh deployment starts from.
Sharing works through a group, and ``osprey up`` sets it up. On each
deploy the bundle directory is made setgid and group-writable, and each
terminal is added to that directory’s group (compose group_add). Both
halves are needed — the setgid bit decides which group owns a newly
written file, while group_add is what makes a container a member of
that group. The group itself is never invented: it is whichever group the
directory already has, so you can retarget it with one chgrp and a
re-deploy. osprey up reports the group it used.
One limit follows from how Unix works rather than from OSPREY: setgid fixes
who owns a new file, not its permission bits, which come from the writing
process’s umask (normally rw-r--r--). So one terminal can always read
and index another’s drafts, but cannot overwrite another’s file in place.
The osprey_facility_knowledge MCP server reads the OKF bundle at
startup and exposes it to the agent through five tools:
list_concepts— browse the index to discover what topics existread_concept— retrieve a document by its concept ID (its bundle path minus the.mdextension, e.g.subsystems/timing-system)search— ranked search across all concept documents (see Searching the Bundle)capabilities— report the bundle’s path, size and concept typesdraft_concept— author a new concept document (requires human approval)
Each of the three read tools also names a url per concept — the link
that opens it in the KNOWLEDGE panel. It is relative to the page the
operator is on, so the agent can cite a concept as a markdown link on a
single-user deployment and behind a per-user mount alike. In the operator
chat, clicking such a link opens the KNOWLEDGE panel in
the workspace at that concept.
The facility-knowledge subagent. When it is enabled in a project’s
config, the main OSPREY agent delegates facility knowledge questions to this
dedicated specialist rather than handling them inline. The subagent has
access only to the three read-only tools (list_concepts,
read_concept, search) and follows a fixed retrieval strategy: list
first to orient, search to narrow, read to synthesize, then submit the
result.
It is enabled by default in the demo preset. To enable or
disable it in a generated project, set the agent’s enabled flag under
claude_code.agents in config.yml:
claude_code:
agents:
facility-knowledge:
enabled: false # disable the subagent (omit to keep it enabled)
Note
The subagent never writes to the bundle. Authoring new concept
documents is done via the draft_concept MCP tool in the main agent
session, or directly via osprey knowledge seed-from-ttl (see the
CLI).
The osprey knowledge command group provides three operations from the
terminal, all of which manage an OKF bundle. The graph store has no verb
of its own: osprey up seeds it from the build’s graph view (see
Container Deployment). osprey knowledge --help prints:
Usage: osprey knowledge [OPTIONS] COMMAND [ARGS]...
Manage OKF facility knowledge bundles.
Options:
--help Show this message and exit.
Commands:
regen-index Regenerate index.md files throughout an OKF bundle.
seed-from-ttl Seed OKF stub documents from the build's graph view.
validate Validate all OKF documents in a bundle.
regen-index — regenerates index.md files throughout the bundle. Run
this after adding or removing concept documents:
$ osprey knowledge regen-index data/facility/knowledge
When called without an argument the bundle path is read from
facility_knowledge.bundle_path in config.yml. Or via the Python
API:
from osprey.services.facility_knowledge.okf.index import regenerate_indexes
from pathlib import Path
regenerate_indexes(Path("data/facility/knowledge"))
The root index.md includes an okf_version frontmatter key;
sub-directory indexes contain no frontmatter (they are consumed by the
server, not the agent directly). The command is idempotent — a second run
produces bit-identical output — and never touches concept documents, only
index files.
validate — validates every *.md file in the bundle and reports all
failures in one pass (collect-all, never aborts on the first error):
$ osprey knowledge validate data/facility/knowledge
All files in data/facility/knowledge are valid.
Concept documents are checked at the authoring level (type,
title, and description must be present and non-empty). Index files
are checked for frontmatter compliance (OKF §6/§11) and must match what
regen-index writes, so a page added, removed or retitled without
regenerating fails validation. The command exits 0 on a clean bundle, 1
if any file fails.
seed-from-ttl — seeds one OKF stub document per device of the build’s
graph view, build/data/graph/facility.ttl in the deployment repo
(--ttl names another Turtle file):
$ osprey knowledge seed-from-ttl data/facility/knowledge
Idempotency rules applied per stub:
File absent — write and report
written.File present, same body — skip and report
unchanged.File present, body differs, no
--force— skip and reportdiffers, use --force.File present, body differs,
--forceset — overwrite and reportoverwritten.
Use --force only when you want to reset hand-edited stubs to the
auto-generated content.
Warning
--force overwrites existing stubs. Omit it to protect hand-edited
documents.
Each stub carries a device_id key in its frontmatter: the facility
file’s device id. Under data/facility/knowledge, that key links the
page to a facility device:
osprey build and osprey facility validate warn, once per page,
when the value is no device id in facility.json, and go on building.
A page without the key is not linked and never warns.
Searching the Bundle#
OKFBundle.search backs both the KNOWLEDGE panel and the MCP search
tool. It has two backends and picks between them by itself:
Ranked search, when the qmd search sidecar is deployed. Hybrid keyword-plus-semantic, so a question phrased in the operator’s own words can find a document that never uses those words.
Substring search, when it is not. No ranking, no scores, no excerpts — a document matches only if it literally contains the string.
You do not choose; a deployment without the sidecar simply gets the fallback. Retrieval Paths shows both branches in context, and the sidecar section diagrams what a ranked query does internally.
Tuning ranked search#
facility_knowledge:
bundle_path: data/facility/knowledge
search:
rerank: false # default
candidate_limit: 40 # omit to use qmd's own default
Both keys are optional and the whole search: block can be left out. A key
that is present but has the wrong type is refused at startup rather than
quietly defaulted — silently ignoring rerank: "false" would leave the
deployment on the path it explicitly asked to leave.
``rerank`` defaults to ``false`` here, and to ``true`` on the ARIEL side.
That split is deliberate. qmd’s reranker improves ranking quality at a real
latency cost — an LLM reviews each candidate before the results come back,
measured p95 3927 ms with it against 811 ms without, on a 135,000-document
corpus — and that cost barely changes with corpus size, so no bundle is small
enough to outrun it. The OKF surfaces are interactive and hold a sub-second
budget that reranking does not fit in. ARIEL’s hybrid module keeps the
quality path instead: one key there serves both the agent tool and the search
panel, and the panel absorbs the wait by showing the fast ranking first and
replacing it when the reranked one arrives.
Set rerank: true if you would rather have the ranking than the latency.
candidate_limit is how many candidates the reranker considers. Lowering it
trades recall for latency.
Note
The score on a ranked hit orders the results; it is not a calibrated
relevance probability. With rerank: false qmd derives it from rank alone
(1.0, 0.5, 0.33 …). Render it or ignore it, but do not threshold it against
a fixed number and do not compare scores across queries.
How well does it retrieve?#
Honestly measured, on a small and deliberately hostile fixture bundle: over 19 concept documents and 14 paraphrased queries — questions worded so that the answer document does not contain the query’s words — ranked search puts the expected document in the top 3 for 10 of the 14. Substring search scores 0 of 14 on the same queries, which is the whole point of the exercise.
Three of the four misses return instead a document written specifically to contain the query verbatim, which is a reasonable thing for a search engine to do. This is the only retrieval-quality measurement this feature has, on a fixture corpus rather than a facility one; treat it as evidence that ranked search beats substring search on paraphrases, not as a benchmark of your own bundle.
Known limitation — concept IDs that normalise together
qmd normalises the document paths it reports: _ and % both become
-, runs collapse, and a leading one is dropped. Two concept IDs that
differ only in those characters therefore look identical to it. The bundle
handles this by matching hits on a normalisation-invariant key rather than
on the reported path — and when that is genuinely ambiguous it drops the hit
and logs a warning rather than guessing at which document you meant. If a
document you expect never appears in results, check the log for that
warning, and prefer hyphens over underscores in file names.
See also
- Facility Knowledge
How the on-demand bundle relates to the always-in-context rules.
- Build Profiles
How to assemble facility-specific OSPREY projects with their own data trees.
- MCP Servers
MCP servers provided by the framework, including
osprey_facility_knowledge.