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.

Authoring concept documents. Each concept document is a markdown file with YAML frontmatter at the top:

---
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

type

Document type (a short free-form label)

title

Human-readable title

description

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.

One bundle, many terminals. In a multi-user deployment every web terminal whose login configures facility_knowledge.bundle_path gets the deployment’s bundle bind-mounted, read-write. There is one directory, not a copy per user: a concept drafted in one terminal is the same file the next terminal opens, and the same file the search sidecar indexes.

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 exist

  • read_concept — retrieve a document by its concept ID (its bundle path minus the .md extension, 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 types

  • draft_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 report differs, use --force.

  • File present, body differs, --force set — overwrite and report overwritten.

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.

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.