yvgude--lean-ctx/docs/guides/knowledge-formats.md

Knowledge Formats — which one, when

lean-ctx can move a project's knowledge in and out through several formats. That is deliberate: they serve genuinely different jobs, and no single format is best for storage and distribution and hand-editing. This guide is the map, so you never have to guess — and so the choice never fragments into "which export did I use again?".

One model, many renderings. Every outbound format is rendered from the same in-memory KnowledgeSnapshot (facts + patterns + insights + relations). They can differ in packaging, never in what the project knows.

TL;DR decision table

I want to…	Use	Command	Signed	Portable / hand-edit	Where it goes
Keep the durable, lossless store	native JSON	knowledge export --format json	–	–	knowledge.json (the store)
Back up / move between machines, full fidelity	native JSON	knowledge export --format json --output kb.json	–	–	one file
Hand-edit in git, share vendor-neutrally, no lock-in	OKF (Markdown bundle)	knowledge export --format okf --output ./kb-okf	–	✅	a directory of .md
Interop with a simple, community fact list	SimpleFact JSON / JSONL	knowledge export --format simple / jsonl	–	✅ (flat)	one file
Distribute / sell a curated pack, verifiable	ctxpkg	pack create … → pack publish	✅	–	.ctxpkg → ctxpkg.com
Give an agent standing instructions	editor rules	init --agent <name>	–	✅	AGENTS.md / CLAUDE.md

Everything above is local and free except publishing a ctxpkg to the hosted registry. Nothing here is deprecated — pick by the job, not by recency.

The formats in one line each

native JSON — the source of truth

knowledge.json is the durable store: every field, full history (superseded facts included), byte-for-byte lossless. Export it with --format json for a backup or a machine-to-machine move where fidelity matters more than readability. This is the only format that round-trips everything.

lean-ctx knowledge export --format json --output kb-backup.json
lean-ctx knowledge import kb-backup.json --merge skip-existing

OKF — the portable, human-editable format

The Open Knowledge Format is a directory of Markdown files, one concept per file, each with a tiny YAML frontmatter and a Markdown body; relations are ordinary Markdown links. It is vendor-neutral, git-diffable, and editable by hand or by any other tool that speaks OKF. Use it when the knowledge should live in a repo, be reviewed in a PR, or leave lean-ctx without lock-in.

lean-ctx knowledge export --format okf --output ./kb-okf
lean-ctx knowledge import ./kb-okf --merge append

OKF exports are deterministic (byte-identical for the same snapshot), so they diff cleanly and never churn your git history.

SimpleFact JSON / JSONL — the lowest common denominator

A flat [{category, key, value, confidence?, source?, timestamp?}] list (or one JSON object per line for JSONL). No relations, no archetypes — just facts. Use it to import a community fact list or to feed facts into a tool that only understands a flat array.

lean-ctx knowledge export --format jsonl --output facts.jsonl
lean-ctx knowledge export --format simple --output facts.json

ctxpkg — the signed, versioned distribution unit

A .ctxpkg is a signed, versioned bundle (manifest + content layers) built for distribution: share a curated knowledge/graph pack with a teammate, pin it in .lean-ctx/ctxpkg.lock, or publish it to ctxpkg.com where consumers verify its signature before installing. This is lean-ctx's distribution and monetization rail — the answer to "ship this knowledge to others, provably".

lean-ctx pack create @me/auth-kit --version 1.0.0     # → .ctxpkg
lean-ctx pack verify @me/auth-kit-1.0.0.ctxpkg        # check integrity/signature
lean-ctx pack publish @me/auth-kit-1.0.0.ctxpkg       # → ctxpkg.com (token required)

editor rules — standing instructions, not a knowledge store

AGENTS.md / CLAUDE.md blocks are how agents get their behavioural rules (tool preferences, conventions), generated by lean-ctx init. They are not a knowledge export — they tell the agent how to act, not what the project knows. Listed here only so it's clear where the boundary is.

OKF vs ctxpkg — the two you'll actually weigh

They look similar ("a bundle of knowledge") but sit on opposite ends of one axis:

	OKF	ctxpkg
Shape	directory of Markdown	single signed archive
Audience	humans, git, any OKF tool	consumers who install/verify
Editable by hand	yes	no (signed)
Integrity / provenance	git history	Ed25519 signature + manifest
Distribution	copy the folder	registry (ctxpkg.com)
Best for	openness, review, no lock-in	shipping / selling a pack

Rule of thumb: OKF to open it up, ctxpkg to lock it down and ship it. Both render from the same snapshot, so exporting one never invalidates the other.

Related

• OKF interop walkthrough
• Journey 3 — Memory & Knowledge
• Publishing packages