klore 0.1.0

Compile documents into a living Obsidian wiki. Based on Karpathy's LLM Wiki pattern.

Turn documents into a living wiki. One command. Any AI agent.

---

Klore compiles raw sources into a structured, interlinked Obsidian-compatible wiki. Drop PDFs, articles, and URLs into a folder. Get a living knowledge base with concept pages, entity profiles, cross-references, and a continuously updated synthesis.

Based on Andrej Karpathy's LLM Wiki pattern, extended with a three-tier model architecture where a Director model replaces the human editorial role.

Why not RAG?

RAG:     query → search chunks → answer → forget
Klore:   sources → compile → wiki → query → save → richer wiki → better answers

RAG retrieves fragments at query time. Every question re-discovers the same relationships from scratch. Nothing accumulates.

Klore compiles your sources into a wiki. Concepts get their own pages. Pages link to each other. When you ask a question with --save, the answer becomes a new page. Your knowledge compounds over time.

Before: Read 3,200+ lines of raw files per session. After: Read the index + 2 topic articles (~330 lines). 90% context reduction.

Quick Start

Install

pipx install klore    # or: pip install klore

Set up your API key

Klore uses OpenRouter for model access. One key, any model:

export OPENROUTER_API_KEY="sk-or-v1-your-key-here"

Build your first wiki

klore init my-research
cd my-research
klore add ~/papers/attention-is-all-you-need.pdf
klore add https://en.wikipedia.org/wiki/Transformer_(deep_learning_model)
klore compile

Open wiki/ in Obsidian and explore. Or just read the markdown.

Agent Setup

Klore works with any AI coding agent. Run bash setup.sh to auto-configure all detected agents, or set up manually:

Agent	Setup	How it works
Claude Code	claude plugin marketplace add ./klore/plugin && claude plugin install klore	/wiki-init, /wiki-compile, /wiki-ask slash commands + SessionStart hook
Cursor	Open project in Cursor	Auto-loads .cursor/rules/klore.mdc
Windsurf	Open project in Windsurf	Auto-loads .windsurf/rules/klore.md via Cascade
Codex (OpenAI)	Open project with Codex	Auto-loads AGENTS.md
Gemini (Google)	Open project with Gemini	Auto-loads GEMINI.md
GitHub Copilot	Works automatically	Reads .github/copilot-instructions.md

After setup, your agent can run klore commands directly. In Claude Code, use /wiki-* slash commands. In other agents, just ask: "compile the wiki" or "ingest this article".

The Claude Code plugin also injects your wiki's index into every session via a SessionStart hook, so your knowledge base becomes ambient context.

Commands

klore init [name]            # Create a new knowledge base
klore add <file|url>         # Add a source (PDF, HTML, markdown, image, URL)
klore ingest <file|url>      # Add a source and compile in one step
klore compile                # Compile sources into the wiki (incremental)
klore compile --full         # Force full recompilation
klore compile --topic <name> # Recompile a specific concept only
klore ask "question"         # Ask a question against the wiki
klore ask --save "question"  # Ask and save the answer as a wiki report
klore watch                  # Watch raw/ for changes and auto-compile
klore lint                   # Run health checks (contradictions, broken links)
klore diff [--since 2w]      # Show wiki changes over time
klore status                 # Show source/concept counts, compilation state
klore config set <key> <val> # Configure models, API key

How It Works

Klore runs a 7-step director-driven compilation pipeline with three model tiers:

Tier	Default Model	Role
Director	Gemini 3 Flash (thinking)	Editorial judgment, quality review, synthesis
Strong	Gemini 3.1 Pro	Concept pages, entity pages, Q&A
Fast	Gemini 3 Flash	Source extraction, tag normalization

The Pipeline

1. Extract (fast, concurrent) — convert raw sources to markdown
2. Editorial Brief (director) — read each source against wiki state, decide what matters, flag contradictions
3. Tag Normalize (fast) — merge synonym tags into canonical forms
4. Build (strong, concurrent) — write source summaries, concept articles, entity pages, guided by editorial briefs
5. Review (director) — review changes for quality and accuracy
6. Index & Log — generate master index with [[wikilinks]], append to operation log
7. Overview (director) — update wiki/overview.md, the living synthesis of the entire knowledge base

The Director model makes the editorial decisions that matter: what's significant, what contradicts existing knowledge, what deserves its own page, and what doesn't. This replaces the human-in-the-loop from Karpathy's original pattern.

Cost

The three-tier architecture keeps costs low. The Director handles editorial judgment. The bulk of work runs on cheaper models.

Sources	Est. Cost	Per Source
5	~$0.30	~$0.06
10	~$0.60	~$0.06
25	~$1.50	~$0.06
50	~$3.00	~$0.06

Real-world example: compiled a 57,000-word book (11 chapters) into 20 concept pages, 2 entity pages, and a full synthesis for ~$0.50 using Gemini Flash 3.0 with thinking mode.

Incremental compiles are cheaper. Adding one source to an existing wiki costs ~$0.05-0.10.

Override models anytime:

klore config set model.director google/gemini-3-flash-preview:thinking
klore config set model.strong google/gemini-3.1-pro-preview
klore config set model.fast google/gemini-3-flash-preview

Architecture

my-research/
├── raw/                     # Your source files (never modified by Klore)
│   ├── paper1.pdf
│   ├── article.md
│   └── diagram.png
├── wiki/                    # Compiled output (Obsidian-compatible)
│   ├── index.md             # Master catalog with [[wikilinks]]
│   ├── log.md               # Append-only operation log
│   ├── overview.md          # Living synthesis (Director-maintained)
│   ├── sources/             # Per-source summaries
│   ├── concepts/            # Synthesized concept articles
│   ├── entities/            # Named entity pages (people, orgs, tech)
│   └── reports/             # Filed Q&A answers (feed back into wiki)
├── .klore/
│   ├── config.json          # Model and API configuration
│   └── agents.md            # Wiki schema (editable)
└── .git/                    # Auto-initialized, wiki changes tracked

Design Decisions

• Director-driven. A frontier model plays editor, deciding what matters and what contradicts. No human-in-the-loop required.
• No vector database. No embeddings. No RAG. The compiled wiki loads directly into the LLM context window.
• Entity pages. People, organizations, and technologies get their own pages, creating a rich relational graph.
• Living synthesis. wiki/overview.md is continuously updated as sources are added.
• Reports compound. Q&A answers filed back into the wiki update concept pages. Knowledge compounds.
• Obsidian-native. Plain .md files with [[wikilinks]]. Graph view, backlinks, and search all work.
• Incremental. Only new or changed sources are reprocessed. Prompt changes trigger full recompile.
• Git-tracked. Every compilation auto-commits. klore diff shows how knowledge evolved.
• Model-agnostic. Any OpenRouter model. Swap with one config change.

Inspired By

Andrej Karpathy's LLM Wiki pattern — extended with autonomous editorial judgment via a three-tier model architecture.

License

MIT