OKF export & import

OKF (Open Knowledge Format, version 0.2) is a plain-files format for knowledge: a folder tree of markdown files, each with a small YAML header. Hive can export any brain as an OKF .zip bundle and import a bundle as a new brain. Because it is just markdown, a bundle is readable in any editor, diffable in git, and understood by other tools that speak OKF.

Self-service export and import

• Export is for the brain's owner (co-owners included). It includes every neuron the owner can read, including neurons under advanced-security types. Brains in your Library cannot be exported by anyone; export the source brain instead (see Marketplace & Library).
• Import creates a new brain owned by you. It counts against the licence like any other brain, and the 50 MiB upload limit applies. Only two imports can run on the Hive at once and each user can have one in flight; if you are told the import is busy, retry shortly.

Exporting a brain

As an administrator, on Admin → Brains, click the zip icon (Export OKF (.zip)) in a brain's row, or open the brain and click Export OKF. The download is named <brain-name>-okf.zip.

The bundle has one top-level folder containing:

File and folder names are lowercase, ASCII-only versions of the type and neuron names (a clash gets -2, -3…). They are presentation only: ids inside the files, not filenames, drive a re-import.

Importing a bundle

You can also seed a brand-new brain from a bundle in one step: New brain on the same page lets you choose the owner, name the brain and attach an optional .json export or OKF .zip. It checks the licence's brain allowance first and tells you if additional licences need to be purchased.

As an administrator, on Admin → Brains, click Import OKF bundle and fill in the dialog (users importing for themselves use Brains → New brain and need no owner field):

• OKF bundle (.zip) — the file to import.
• Brain name (optional) — defaults to the name in the bundle's manifest, else the zip file name. If the name is taken, Hive makes it unique.
• Owner (required) — the active user who will own the new brain. The admin session is not a user, so you choose one.

An import always creates a new brain. It never merges into or updates an existing one. It is all-or-nothing: if anything fatal is found, nothing is written and you get a single message saying why. Embeddings are not part of the bundle; Hive starts generating them as soon as the import finishes, as with the JSON import, so semantic search for the new brain may lag briefly on a large bundle.

Bundles from other tools

A generic OKF bundle (no Aiqbee keys) also imports:

• Each .md file becomes a neuron. Its neuron type comes from the type header, else the folder name, else Concept.
• The neuron name is the title, else the first # heading, else the file name. Duplicate titles are allowed.
• Markdown links between files become synapses; the text after a * [Title](link) - description list item becomes the synapse description. Links inside code blocks, to websites, or that do not resolve are not synapses (unresolved ones are reported as broken links).
• index.md and log.md are ignored.

What round-trips

Exporting an Aiqbee brain and importing the bundle recreates the following exactly:

• Brain name (before any uniqueness suffix), description and the MCP-editing setting.
• Neuron types — names, descriptions, the file-type flag, empty types and types with duplicate names.
• Neurons — name, content byte-for-byte (including empty vs. none), content date, metadata, and created time.
• Synapses — direction, description, and duplicate or self links.
• The metadata field registry.

Deliberately not carried across:

• Access control — brain, user, group and service-account grants, neuron-type access, advanced security and audit settings. Users and groups belong to one Hive; the new brain gets defaults and the chosen owner.
• Row ids (new ones are generated), version counters and embeddings.
• Attachments. Hive stores no file blobs, so only text content is exported; any non-markdown file in an imported bundle (images, HTML) is skipped and listed.

The import report and warnings

A successful import shows a result page with a link to the new brain, counts of neuron types, neurons, synapses, metadata fields and ignored files, and grouped warnings. Warnings never block the import; they tell you what was adjusted:

Limits and rejected bundles

These checks run before anything is written. A bundle that breaks one is rejected outright:

• Upload up to 50 MiB; at most 25,000 zip entries and 20,000 concept files; each .md file at most 8 MiB, and 256 MiB of markdown in total. Frontmatter is limited to 512 KiB per file and 32 MiB overall, and a bundle may define at most 500,000 synapses.
• Paths that escape the bundle (../), absolute paths, symlinks, encrypted entries, over-long or over-deep paths, and two entries whose names differ only by case.
• Files that are not zip archives.
• A bundle with no concepts to import.

The export applies the same limits: a brain too large to import again is not exported to OKF (you are told so and pointed to the JSON export), so a bundle you download can always be re-imported. Each import form can be submitted only once, so reloading the result page never creates a second brain.

Nothing is extracted to disk, and YAML headers are parsed safely (no tags, anchors or aliases), so a hostile bundle cannot run code or write files.

The import also counts against your licence: the brain limit and the pooled neuron cap are checked against the size of the bundle, and an expired licence (read-only mode) refuses the import. The message names the limit hit. See Licensing & tiers.

Metadata and the licence

Declaring a metadata field is a paid feature (see Neuron metadata). What an import does depends on the licence of the Hive receiving it:

• With the metadata entitlement — the field registry is created and each neuron's metadata is validated against it.
• Without it — the registry is not created, but neuron metadata values are still stored. They are inert (visible, but not usable as filters) until the fields are declared, exactly as after a licence lapse. The report carries a warning saying so.

As always, metadata is labelling, not access control. It travels with the bundle to anyone who can open the zip.