Metadata-Version: 2.4
Name: llmkb
Version: 0.1.0
Summary: Local, folder-first LLM knowledge bases: format spec, CLI, MCP server, and agent skills.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mcp<2,>=1.28; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.28; extra == 'mcp'
Description-Content-Type: text/markdown

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