yvgude--lean-ctx/docs/guides/okf-interop.md

Portable Knowledge with OKF

The Open Knowledge Format (OKF) is a vendor-neutral way to carry a project's knowledge as plain Markdown. lean-ctx can export its knowledge base to an OKF bundle and read one back — so your accumulated project facts are never locked inside lean-ctx's private store.

An OKF bundle is a directory of Markdown files:

kb-okf/
├── index.md                 # overview (categories + counts)
├── log.md                   # consolidated-insight history (if any)
├── architecture/
│   ├── auth.md              # one concept per file
│   └── db.md
└── patterns/
    └── naming.md

Each concept file has a small YAML frontmatter (only type is required by OKF) and a Markdown body. lean-ctx-specific fields ride along as producer-owned leanctx_* keys so an export → import round-trip is lossless.

Export

lean-ctx knowledge export --format okf --output ./kb-okf

Or from an MCP agent:

ctx_knowledge(action="export", format="okf", path="./kb-okf")

A single concept file looks like this:

---
type: "architecture"
title: "auth"
description: "Auth uses JWT RS256 tokens verified against Redis sessions."
tags:
  - "architecture"
timestamp: "2026-06-24T10:00:00+00:00"
leanctx_archetype: "architecture"
leanctx_category: "architecture"
leanctx_confidence: 0.9
leanctx_key: "auth"
leanctx_source_session: "s1"
---

Auth uses JWT RS256 tokens verified against Redis sessions.

## Relations

- depends_on: [architecture/db](db.md)

The ## Relations section renders the knowledge graph: each edge becomes a Markdown link to the target concept, labelled with the relation (depends_on, related_to, supports, contradicts, supersedes).

Edit by hand, review in git

Because a bundle is just Markdown, you can:

• fix a fact by editing its body,
• add a relation by adding a - depends_on: [category/key](path.md) line,
• review changes in a pull request like any other docs change.

Exports are deterministic — the same knowledge always produces byte-identical files (fixed frontmatter key order, stable filenames, sorted relations). Diffs show only what actually changed, and re-exporting never churns your history.

Import

lean-ctx knowledge import ./kb-okf --merge append

ctx_knowledge(action="import", path="./kb-okf", merge="append")

Merge strategies match the JSON importer: append, replace, skip-existing (default). Import reconstructs facts first, then relations — an edge is only created when both endpoints are current facts, so a bundle can never leave dangling links in your graph.

Importing a foreign bundle

OKF only mandates type. A bundle written by another tool imports cleanly even with nothing but a type and a body:

---
type: architecture
---

We run everything on Kubernetes.

lean-ctx maps the OKF type to its nearest archetype (unknown types become plain fact), derives the category from tags (or imported), and uses the body as the value. Unknown frontmatter keys are tolerated, never fatal.

Check a bundle before importing

Import surfaces non-fatal lint warnings (missing type, empty body, unreadable file). They never block the import — a partially malformed bundle still imports everything it can, and the warnings tell you what to fix.

When to use OKF vs other formats

OKF is the portable, hand-editable format. For a lossless machine backup use native JSON; to ship or sell a signed pack use ctxpkg. See Knowledge Formats — which one, when for the full map.

Notes

• OKF export/import is a local feature — free on every plan.
• The bundle is rendered from the same KnowledgeSnapshot as a ctxpkg export, so the two never disagree on the project's knowledge.