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*.

```bash
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](okf-interop.md) 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.

```bash
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.

```bash
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](https://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".

```bash
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](okf-interop.md)
- [Journey 3 — Memory & Knowledge](../reference/03-memory-and-knowledge.md)
- [Publishing packages](publishing-packages.md)