OpenKB: knowledge that compiles

Every "chat with your docs" tool I've built lands in the same place: I embed a pile of chunks, retrieve the top-k at question time, and let the model improvise an answer over whatever came back. It works, but it never really knows anything. Two documents about the same topic stay two disconnected piles of vectors, and the model re-derives the connection between them on every single query. Nothing accumulates.

So I spent a session with OpenKB — an LLM knowledge base powered by PageIndex — because it makes the opposite bet, and I wanted to feel the difference on real inputs rather than argue about it in the abstract. This is the concept, with a two-document knowledge base as the worked example.

The bet: compile knowledge, don't retrieve it

Classic RAG does its synthesis at read time. OpenKB does it at write time. When you run openkb add, a pipeline runs once per document — summarise, plan the concepts, generate them, then rewrite the summary to point at what it learned — and the output is not an opaque index. It's a Markdown wiki: one summary per document, cross-document concept pages, and an index.md table of contents, all linked with [[wikilinks]]. You can open it, read it, grep it, and put it under version control.

One detail I didn't expect and now really like: the raw PDF never reaches the model. A converter runs the file through markitdown locally first, and only the extracted text is sent to the LLM. That makes ingestion text-in, text-out — cheaper, provider-agnostic, and no vision model in the loop. Your binary never leaves as pixels. (Image-only scans are the exception; those need a separate image path.)

What happens on the second document

Here's where the bet pays off. My first handbook was a fictional camping brand, Meridian Outdoor Co.; it compiled into a summary plus three concepts. Then I added a second one — a climbing brand, Summit Supply Ltd. — deliberately written to overlap on warranty, shipping, and sustainability. I wanted to see whether OpenKB would append or merge.

It merged. Three existing concept pages were rewritten to cite both sources, and two new single-source concepts appeared — including take-back-schemes, which only the climbing brand had. That's the important nuance: the planner does entity resolution, not blind appending. It recognised that Summit's warranty content belonged on the existing warranty-policies page, but judged the take-back idea distinct enough to earn its own. The synthesis is a diff against the wiki, not a dump onto it.

One honest caveat I hit: concepts are created forward-only. Both handbooks had a product catalogue, but the first ingest never abstracted "product catalog" as a concept, so it only appeared — as single-source — when the second document introduced it. Earlier documents aren't re-mined. Ingest order shapes the graph.

Reading beats asking

Because the wiki is just Markdown routed by a table of contents, retrieval gets cheap in a way that surprised me. The bundled skill's first instinct is to read: scan index.md, open the one concept page that matches, follow a wikilink or two, and answer — with the reasoning staying in its own context and zero extra model calls. openkb query exists, but it's the last resort: it spins up OpenKB's own agent and spends a second round-trip, re-injecting wiki text into another model.

There's a security reason to prefer reading, too. The skill treats every wiki body as data, not instructions — concept and source text is LLM-synthesised from documents that could carry prompt injection. Routing an answer through a second query call is exactly where an "ignore previous instructions" buried in an ingested PDF gets a chance to compound. Reading the page keeps that text inert.

From wiki to installable skill

The payoff step turns the wiki into an Anthropic Skill. openkb skill new read my concept pages and compiled a skill I could drop straight into Claude Code — and it didn't just dump the facts. It wrote a decision procedure: classify the case, map the product category to its warranty tier, check return eligibility, then advise. It even compiled a "Known gaps" section that enumerates what the sources never state and instructs the skill not to fabricate it.

Then I graded it. openkb skill eval generates should-trigger and should-not-trigger prompts and scores two axes: does the description fire on the right questions, and can the body actually answer what the description promised? Mine scored 12/12 and 6/6. The test I care about most was a negative one — "does this brand warranty the Patagonia jacket?" carries the word "warranty" but names a brand not in the KB. A naive trigger fires and hallucinates; the compiled description stayed quiet because it had written its own boundary.

A knowledge base you can install

The last thing that clicked: the repo is a one-skill marketplace. OpenKB writes a manifest alongside the skill, so the whole thing installs with one command.

npx skills@latest add zakariahere/openkb-outdoor-kb

Two fictional handbooks became a merged Markdown wiki, a graded skill, and a shareable GitHub artifact — each step legible and correctable, none of it hidden in a vector store. That's the whole idea: knowledge that compiles, and travels. The full knowledge base, the compiled skill, and the deck these figures are drawn from live in the repo.