Overview
BioOKF is a format and toolchain for turning any biomedical source (a paper, preprint, bench note, slide deck, CSV, figure, or tweet) into a structured, interlinked, version-controlled knowledge base that compounds over time and can be queried as a graph.
It is a biomedical profile of Google Cloud's Open Knowledge Format (OKF), itself a formalization of Andrej Karpathy's LLM Wiki pattern. BioOKF keeps OKF's portable substrate, a Git-shippable tree of Markdown with YAML frontmatter, and adds the one thing OKF leaves open: a closed, controlled universe of meaning, with 28 node types, 35 edge predicates, and node-based provenance on every claim.
The repository ships both the format (the spec) and the toolchain that implements it: a Rust core, the
bokf CLI, the bokf-mcp server, and the BioOKF Studio desktop visualizer,
distributed as a notarized app plus Claude Code and Codex plugin manifests.
bokf-core and share an active-base pointer, so a script, an agent, and a human can curate the same base.Install
Install the notarized Studio first, then add the plugin to Claude Code or Codex. You never compile
anything. BioOKF Studio 0.3.1 is published as BioOKF.Studio_0.3.1_aarch64.dmg for
Apple Silicon and BioOKF.Studio_0.3.1_x64.dmg for Intel Macs. The first time a tool runs,
the shared launcher downloads any missing prebuilt binaries for your platform and caches them under
~/.local/share/biookf.
Requirements. Claude Code or Codex, plus curl and tar, on macOS (Apple Silicon
or Intel), where a self-contained .app is downloaded for you. Linux and Windows builds are produced
by the release pipeline as they become available; until a prebuilt asset exists for your platform you can
build from source and point the plugin at your binary with BIOOKF_MCP_BIN.
Override the version, cache location, or download source with BIOOKF_VERSION, BIOOKF_HOME,
and BIOOKF_REPO.
The bundle
A BioOKF bundle is a Git-shippable directory tree of Markdown.
| Path | What it holds |
|---|---|
raw/ | Immutable ingested sources. You never edit these; they anchor provenance to bytes. |
knowledge/<type>/<slug>.md | The typed concept documents you author. These are the graph. |
index.md | The catalog: identifier registry, by-type list, and subtypes in use. |
log.md | Newest-first dated change history. |
SCHEMA.md | The agent-facing operating doc, dropped at the bundle root. |
Each concept document is YAML frontmatter plus a Markdown body. Only type and identifier
are mandatory. An agent-coined subtype carries finer granularity and is never validated against a
fixed list. Three rules make it BioOKF rather than plain OKF: a closed set of node types, a closed set of edge
predicates, and node-based provenance on every edge.
Node types (28)
Every document's type is exactly one of 28: twenty biomedical entity types plus
eight provenance and context types, with Other as the closure. Studio colors each node by its type.
Definitions follow SPEC.md section 5.
member_of.note field explaining why.Edge predicates (35)
Relationships are first-class frontmatter edges: entries: 24 positive
predicates (forward-only, no inverses) plus 11 negative not_<X> predicates
for the negatable effect predicates. Direction is always this-document to object. Definitions follow SPEC.md section 6.
24 positive predicates
is_aSubject is a more-specific kind or instance of object. The ontology backbone for type hierarchy and inheritance.part_ofA structural or compositional part relationship. Structural genomic partonomy (exon, intron, CDS, codon to gene) lives here.member_ofSubject belongs to a class, family, or group. Typical for molecule to drug-class, gene to gene-set, protein to family.derives_fromMaterial or data lineage: sample from donor, cell from tissue, metabolite from parent, dataset from study, structure from molecule.located_inSubject is positioned or found in object: anatomically (disease in organ), genomically (variant in gene), or geographically.expressed_inA gene or molecule is expressed, abundant, or present in an anatomical or cell context. Carries optional direction, effect_size, p_value.encodesA gene encodes, or is transcribed and translated into, its product. Forward-only, with no encoded_by inverse.interacts_withA physical or functional interaction (protein-protein, gene-gene, drug-drug, host-pathogen). Symmetric.bindsDirect binding with measurable affinity (drug-target, transcription-factor to DNA, antibody-antigen). Carries optional Kd, Ki, or IC50.regulatesSubject increases or decreases the activity, abundance, or expression of object. Requires a direction, optionally an aspect.catalyzesAn enzyme or complex catalyzes a reaction. Subject is the catalyst; object is the reaction.converts_toSubject is chemically transformed or metabolized into object. A molecule-to-molecule conversion.participates_inSubject takes part in, enables, or is an input or output of a pathway, process, or function.causesSubject brings about, induces, or drives object: etiology (pathogen to disease), somatic drivers, drug to adverse event.predisposes_toSubject raises the risk or likelihood of object without being a sufficient cause. Carries odds_ratio, hazard_ratio, or relative_risk.treatsSubject (drug, procedure, device, intervention) cures, manages, ameliorates, or palliates the object condition. Carries optional clinical_phase.preventsSubject stops, hinders, or reduces the onset risk of the object condition.contraindicated_inSubject (drug or procedure) must not be used in the object condition or context.affects_response_toSubject (gene, variant, biomarker) modulates response, sensitivity, resistance, or metabolism of the object drug. The pharmacogenomics edge.has_phenotypeSubject (disease, organism, variant) presents or manifests the object phenotype, sign, or symptom. Carries optional frequency, onset, severity.measuresSubject ascertains the value of, or is diagnostic for, object. Includes diagnoses. Carries optional sensitivity, specificity, auc, unit.associated_withA statistical or co-occurrence association that is neither causal nor mechanistic (GWAS hit, eQTL, correlation, comorbidity). Symmetric. The quantitative umbrella edge.reported_inThe universal provenance edge. The subject node, or a reified claim, is reported, curated, or evidenced in a Publication, Study, Dataset, or Agent.used_to_studyAn investigative resource (method, study, dataset, device, model organism, cell type, sample) is used to study, model, or probe the object entity.11 negatable predicates
For the negatable effect predicates, a not_<X> form records a refuted relationship. Studio
renders these struck-through and reddish, so a contradiction reads at a glance.
not_bindsA refuted binding claim: subject does not bind object with measurable affinity.not_interacts_withA refuted interaction: subject has no physical or functional interaction with object. Symmetric.not_causesA refuted causation: subject does not bring about object.not_predisposes_toA refuted risk claim: subject does not raise the likelihood of object.not_preventsA refuted prevention: subject does not reduce the onset risk of object.not_treatsA refuted treatment: subject does not cure, manage, ameliorate, or palliate object.not_affects_response_toA refuted pharmacogenomic claim: subject does not modulate response to the object drug.not_associated_withA refuted association: no statistical or co-occurrence link between subject and object. Symmetric.not_expressed_inA refuted expression claim: the gene or molecule is not expressed in the anatomical or cell context.not_regulatesA refuted regulation: subject does not change the activity, abundance, or expression of object.not_has_phenotypeA refuted phenotype claim: subject does not present or manifest the object phenotype.not_<X> edge records a negative finding stated in the
source, for example "drug A does not bind target B". It is the only canonical way to negate. Asserting both
<X> and not_<X> for the same subject and object is a contradiction the linter
flags. Structural and provenance predicates (is_a, part_of, encodes,
measures, reported_in, used_to_study) cannot be negated.Provenance model
Quantitative claims go on edges, never prose, and every edge says where it came from.
Each edge carries three provenance fields:
| Field | Values |
|---|---|
knowledge_level | knowledge_assertion · statistical_association · prediction · observation · not_provided |
agent_type | manual_agent · automated_agent · text_mining_agent · data_analysis_pipeline · computational_model · not_provided |
primary_source | Names a source node by its identifier (a Publication, Study, Dataset, or Agent in the bundle), never a bare CURIE, plus a reported_in edge. |
Ingested-document sources anchor to the immutable bytes under raw/ via raw_source;
external references record their CURIE in xref. The full normative format is in the spec; the
agent-facing operating doc (conventions plus the ingest, query, and lint workflow) is in the schema.
BioOKF Studio
Studio is a Tauri desktop app and a pure visualizer; every operation delegates to bokf-core.
Registry-driven sidebar
Knowledge bases are tracked by a registry of links, so a bundle can live anywhere on disk; there is no fixed directory. Each entry shows its name, node and edge counts, and last-updated date. Delete or move a folder and it drops from the sidebar; register one elsewhere and it appears, with no restart. + New base opens a native folder picker that validates the folder as a real BioOKF bundle before registering it.
Interactive graph canvas
A force-directed, type-colored graph with pan, zoom, drag, fit-to-view, hub emphasis, hover tooltips, and
neighbor-focus dimming. The lower-right graph controls provide zoom in, zoom out, fit-to-view, and export to
a self-contained HTML graph with embedded data and clickable details. Negative not_<X> edges
render struck-through; synthesized provenance edges render faint; symmetric edges are styled distinctly. A
type-family legend covers all 28 types plus the light "External" swatch.
Detail panels
Click a node for its type badge, frontmatter (subtype, xref, synonyms, tags chips,
raw_source, description, notes), outgoing edges grouped by predicate, incoming "referenced by" edges,
the rendered Markdown body, and, for source nodes, a Source and Provenance block with credibility tier, venue,
DOI, PMID, or arXiv links, and ingested figures. Click an edge for its provenance triplet, direction,
publications, and quantitative attributes. Citations open a side preview of the cited source.
In-app editing and terminal
Edit a concept doc's full Markdown, a per-node notes section, or a per-edge note. Each writes live to disk and
appends a dated log.md entry; a reveal-in-Finder button opens the file. A multi-tab real PTY terminal
(xterm.js) runs your $SHELL in a resizable panel, so you can drive bokf
without leaving the app. A toolbar lint pill opens a grouped findings popup; the search box filters and highlights
the graph live (Cmd-K or Ctrl-K); the change-log drawer renders log.md.
The live loop
The CLI, the MCP server, and the GUI are wired together so an agent and a human can work on the same base at the same time.
- One active base, shared. All three surfaces read and write a shared
.active-kbpointer and aregistry.yamlof bundle links. Selecting a base in the GUI updates the pointer for the agent; an agent changing the pointer is mirrored back into the GUI as a focus marker, without yanking your view. - The agent drives the GUI. The
bokf_studio_*tools open the Studio and steer it:select,search, andreloadnavigate the graph,stateandgraphobserve it. The control channel is a Unix socket that only listens whenBIOOKF_STUDIO_CONTROL=1, set automatically when the agent opens the app. - Status without screenshots.
bokf_studio_statereturns the GUI's complete status as structured JSON (active base, counts, search query, current selection, which panels are open, lint summary, and the last agent action), so an agent reads what the app is doing instead of interpreting a screenshot. - The human sees the agent work. Every agent action is narrated in real time in an in-app
activity banner, and
bokf_studio_narratelets the agent post a custom status line.
CLI commands
The same operations the agent runs are available as the bokf CLI (23 subcommands)
and as MCP bokf_* tools.
| Command | What it does |
|---|---|
scaffold | Create an empty bundle; commit, register, activate. |
convert | Convert a file, folder, or zip, --text, or --url(s) into raw Markdown under raw/. |
validate | Validate a single concept-document file without writing it. |
get | Look up a node by exact identifier. |
index | Regenerate index.md, or --check it. |
lint | Lint against the BioOKF v0.5 conformance rules (--json). |
verify | Deterministic gate: lint plus structure checks; exits 1 on any error. |
graph | Derive the render-ready graph (nodes plus directional edges). |
search | BM25 full-text search over concept documents. |
stats | Node and edge counts by type and predicate. |
predicates | Print the controlled vocabulary (28 types, 35 predicates, enums). |
export | Export a self-contained bundle JSON (graph plus per-node detail) for the GUI. |
log-sync | Append a dated log.md entry and commit, atomically. |
commit | Lower-level stage-all plus commit (a non-logged lifecycle commit). |
log | Show commit history, newest-first. |
restore | Forward-only restore to a prior commit. |
register | Register, --list, or --unregister a known bundle under a root. |
set-active / get-active | Set or read the active base under a root. |
merge-raw | Relocate a secondary base's raw/ into a main base's raw/ (dedup by content). |
merge-snapshot | Snapshot the main base before a merge, or --verify after. |
name-figure | Rename a provisional figure to a content caption and rewrite every reference. |
install-pdfium | Install PDFium so PDF pages render to images for vision (one-time). |
A typical curation workflow
MCP tools
bokf-mcp exposes 33 tools in three groups. It ships an operating brief on
initialize, so an agent knows the BioOKF rules before it acts.
Curation, 17 tools
Analysis, 6 tools
Studio GUI control, 10 tools
bokf_studio_state returns the complete GUI
status as JSON, the recommended way for an agent to know what the app is showing.Build from source
The toolchain is a Cargo workspace under app/ (the Studio desktop source is in
app/studio/). For development, or for a platform without a prebuilt release:
Binaries land in app/target/release/, and the app under
app/target/release/bundle/. To make the plugin use a local build instead of downloading a release,
set BIOOKF_MCP_BIN=/path/to/app/target/release/bokf-mcp.
app/.claude-plugin: 8 biookf-* curation skills plus 4 guardrail hooks. Add
app/ as a marketplace to use them while working inside the repository. The published plugin at
plugins/biookf includes side-by-side Claude Code and Codex manifests over the same MCP launcher.