llmkb — local, folder-first LLM knowledge bases

A template and toolkit for LLM knowledge bases that are just a git directory of markdown pages, in the style of Karpathy's LLM-wiki. An agent plus that directory is a complete system: agents ingest sources and file what they learn, the wiki compounds synthesis over time, and a small CLI keeps the bookkeeping honest. No server, no database, no proprietary format.

This repo ships the format spec, a CLI, an optional MCP server, and agent skills. Actual knowledge bases are separate directories stamped out per project — this repo never contains anyone's knowledge.

Install

uv tool install llmkb          # or: pipx install llmkb
# optional MCP server:
uv tool install "llmkb[mcp]"

Quickstart

llmkb init my-project-kb --description "notes for my project"
# drop sources into my-project-kb/raw/, then use the kb-ingest skill
llmkb reindex --kb my-project-kb
llmkb lint --kb my-project-kb
llmkb search "some query" --kb my-project-kb

What's in a KB

A knowledge base is a directory:

my-project-kb/
  kb.yaml           # identity + format version
  SCHEMA.md         # the writing discipline agents follow
  raw/              # curated sources, never modified
  wiki/
    summaries/  concepts/  entities/
    index.md        # derived catalog (llmkb reindex rebuilds it)
    log.md          # append-only operation record

See docs/FORMAT.md for the full versioned contract and examples/example-kb/ for a working example.

CLI

• llmkb init <dir> — scaffold a new KB.
• llmkb reindex — rebuild wiki/index.md from page frontmatter.
• llmkb lint — catch broken links, orphans, index drift, malformed frontmatter; exit code reflects health.
• llmkb search <query> — full-text search (SQLite FTS5, cached in .llmkb/).

All commands take --kb <dir> (repeatable; defaults to the current directory) and tag multi-KB output by name.

MCP server (optional)

llmkb-mcp --kb <dir> runs a read-only MCP stdio server exposing search, get_page, get_index, and list_kbs to any MCP-capable agent.

Skills

Four portable, dual-harness skills live in skills/ — kb-ingest, kb-query, kb-lint, kb-init. Install them once (user-wide or as a plugin); never copy them into a KB instance, so they evolve centrally.

License

Apache-2.0. See LICENSE.