Journey: Portable Knowledge: OKF & ctxpkg

A knowledge base that only one tool can read is a knowledge base you will lose. LeanCTX keeps everything your agent learned — facts, patterns, relations — in a portable form you can diff, hand-edit, review in a pull request, and hand to a completely different tool. The same in-memory KnowledgeSnapshot is rendered two ways: OKF, a vendor-neutral Markdown + YAML bundle, and the signed .ctxpkg archive for distribution.

One snapshot, two portable formats

Both formats read from a single source of truth — the KnowledgeSnapshot — so they always describe the same facts, patterns and relations. You pick the format by what you need to do with it.

	OKF (--format okf)	.ctxpkg (lean-ctx pack)
Shape	a directory of Markdown files	one signed, versioned archive
Made for	humans, git, code review, other tools	machine distribution & install
Editable by hand	yes — it’s just Markdown	no — treat as an artifact
Integrity	git history	Ed25519 signature + digest
Best when	you want to read, edit or share knowledge	you want to ship a knowledge pack

OKF is the format you reach for day to day; .ctxpkg is how you publish a curated pack for others to install.

Export — lean-ctx knowledge export --format okf

lean-ctx knowledge export --format okf --output ./knowledge-okf
# → OKF bundle exported: ./knowledge-okf (12 concepts, 0 patterns, 0 relations)

The bundle is a plain directory you can commit straight into your repo:

knowledge-okf/
├── index.md                     # human-readable table of contents
├── log.md                       # provenance / export log
├── code-health/
│   └── rust-src-tools-ctx-search-rs-handle.md
├── finding/
│   └── auto-import.md
└── pattern/
    └── auto-tmp628-test-ts.md

Facts are grouped into one directory per category; each concept becomes one Markdown file with a filesystem-safe slug derived from its key.

What a concept file looks like

Standard OKF frontmatter (type, title, description, tags, timestamp) sits on top; LeanCTX-specific fields are namespaced under leanctx_*, so a foreign OKF reader can ignore them and still get the content:

---
type: "fact"
title: "rust/src/tools/ctx_search.rs#handle"
description: "cognitive complexity 97 (line 79)"
tags:
  - "code_health"
timestamp: "2026-06-30T07:28:25Z"
leanctx_archetype: "fact"
leanctx_category: "code_health"
leanctx_confidence: 0.9
leanctx_sensitivity: "public"
---

cognitive complexity 97 (line 79)

Relations between facts are written as ordinary Markdown links under a ## Relations heading, pointing at the other concept files — so the graph survives even in a tool that knows nothing about LeanCTX.

Import — lean-ctx knowledge import <dir>

Point import at any OKF directory. Preview first with --dry-run, then choose how it merges with what you already have:

lean-ctx knowledge import ./knowledge-okf --merge append --dry-run
# → OKF import: 12 added, 0 skipped, 0 replaced, 0 patterns, 0 relations

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

--merge takes append (add everything), replace (overwrite facts with the same key) or skip-existing (keep yours on conflict). Relations are only re-linked when both endpoints exist in the imported set, so an import never leaves dangling edges.

Foreign bundles just work

Because OKF is an open shape, import accepts a bundle that some other tool wrote. Files without the leanctx_* fields are mapped to plain facts using their standard type/title/description; unknown type values fall back to fact. Non-conforming files produce non-fatal warnings instead of aborting the import — you get as much as the bundle can honestly give you.

Deterministic by design

Re-exporting the same knowledge produces byte-identical files: keys are ordered, floats use their shortest form (0.9, never 0.8999999…), and there are no timestamps or counters in the output body. That is what makes OKF safe to commit — a git diff shows only what actually changed — and it keeps provider-side prompt caches warm.

From the MCP tool

Everything above is also available to your agent through ctx_knowledge, no shell required:

// export
ctx_knowledge({ action: "export", format: "okf", path: "./knowledge-okf" })
// import
ctx_knowledge({ action: "import", path: "./knowledge-okf", merge: "append" })

Both the CLI and the MCP surface are local and free — portability is a property of the format, not a paid feature.

OKF is interop, not the search engine

Day-to-day retrieval over your knowledge is LeanCTX’s hybrid engine — lexical BM25 + learned-sparse SPLADE + local dense embeddings, fused with Reciprocal Rank Fusion and reranked with code-aware signals. OKF is the portability layer on top: the curated, structured memory your agent built while working — facts with provenance, confidence and typed relations — in a form anything can read, diff and hand-edit. It is not a vector store you dump documents into.

Want a heavier, external RAG across many repos and document types (PDFs, wikis, tickets)? That belongs in an addon, not in the always-local core. For the full trade-offs versus a classic embed-everything pipeline, see the lean-ctx vs naive RAG comparison.