Knowledge Base AI

Personal knowledge management powered by LLMs. Drop documents into raw/, and the system compiles them into a structured, cross-referenced wiki — inspired by Andrej Karpathy's workflow.

raw/ documents → INGEST → COMPILE → wiki/
                                     ├── articles/   (summaries)
                                     ├── concepts/   (auto-extracted)
                                     └── outputs/    (Q&A, slides, charts)

The LLM owns the wiki. You provide raw data; it organizes, cross-references, and answers questions against it.

Quick Start

pip install -e .                  # CLI providers only (no API key needed)
pip install -e ".[anthropic]"     # + Anthropic SDK
pip install -e ".[openai]"        # + OpenAI SDK
pip install -e ".[all]"           # + all SDKs

# Build the wiki
cp my-document.md raw/
kb ingest url "https://example.com/article"
kb ingest run
kb compile

# Query
kb ask "What is X?"
kb search query "keyword"

LLM Providers

Provider	Install	Auth
claude-cli	Claude Code	CLI-managed
codex-cli	npm install -g @openai/codex	CLI-managed
copilot-cli	gh extension install github/gh-copilot	CLI-managed
openai	pip install -e ".[openai]"	OPENAI_API_KEY
anthropic	pip install -e ".[anthropic]"	ANTHROPIC_API_KEY
ollama	ollama serve	—

Set the default in config.yaml or override per-call with kb -p <provider> ….

Obsidian Integration

wiki/ is a complete Obsidian vault. Open it to get graph view, backlinks, wikilinks, and Marp slide previews (Marp plugin).

wiki/ is managed entirely by the LLM — don't edit manually to avoid conflicts during compilation.

CLI Summary

# Ingest
kb ingest scan | run                 # preview / ingest new raw files
kb ingest url URL [-n name]          # fetch + ingest a web page

# Compile
kb compile [--all]                   # full pipeline
kb compile-concepts [-s PATTERN]     # concepts-only fast path
kb index                             # rebuild index + catalog + graph
kb materialize-relations             # write typed relations into article bodies

# Q&A
kb ask "question" [-s file.md]       # save answer to wiki/outputs/
kb slides "topic" [-o file.md]       # Marp slide deck
kb visualize "topic" [-o file.png]   # matplotlib chart

# Search
kb search query "keyword" | reindex | serve [-p PORT]

# Maintenance
kb lint [--deep] | impute | stats | file-output NAME

# Global flags
kb -p PROVIDER … | -c config.yaml … | --json …   # agent-friendly JSON output

Full specification: spec/. Agent integration: AGENTS.md.

MCP Server

The project ships an MCP server so agents (Claude Code, Codex, …) can drive the wiki directly. Add to .mcp.json:

{
  "mcpServers": {
    "kb-ai": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/my-ai"
    }
  }
}

Exposes kb_ingest_*, kb_compile, kb_ask, kb_search, kb_lint, and more — see AGENTS.md.

Design Principles

• LLM-first — the wiki belongs to the LLM; you own the raw data.
• Plain markdown — .md + YAML frontmatter, no vendor lock-in.
• Provider-agnostic — swap LLMs via config or -p flag.
• Local-first — Whoosh keyword search + TF-IDF hybrid, no GPU or cloud required.
• Incremental — every operation is resumable; checkpoints per article.

License

MIT — see LICENSE.