Skip to content

Getting Started

Install KB and run your first query locally. For shared team setups, see Team Deployment.

Install

curl -fsSL https://knowledgebroker.dev/install.sh | sh

This downloads the latest kb binary for your platform (macOS or Linux) and places it on your PATH.

All runtime dependencies are managed automatically on first run.

Build from source

Requires Go 1.24+:

git clone https://github.com/alecgard/knowledge-broker.git
cd knowledge-broker
make install

make install builds the kb binary and adds it to your PATH.

Ingest

Point KB at your sources. Descriptions help agents understand what each source contains:

kb ingest --source ./my-project --description "Payment processing service"
kb ingest --git https://github.com/acme/platform --description "Platform services"
kb ingest --confluence ENGINEERING --description "Engineering wiki"
kb ingest --slack C0ABC123DEF --description "Platform engineering channel"

KB walks each source, chunks files at semantic boundaries (headings for markdown, functions for code), embeds them locally, and stores everything in a single SQLite database.

Ingestion is incremental, so re-running the same command only processes new or changed files. Set this up as a cron job or CI step to keep the knowledge base current.

Query

Raw mode (no API key needed)

Raw mode runs the full retrieval pipeline (embedding, hybrid search, confidence scoring) entirely locally. No external API key required.

kb query --raw "how does authentication work?"

Returns ranked fragments with content, source metadata, and per-fragment confidence scores.

Synthesis mode (requires an LLM provider)

For synthesised answers with cross-fragment confidence assessment and contradiction detection. Configure an API key for your preferred provider:

# Save to your persistent config (recommended — survives new shells)
mkdir -p ~/.config/kb
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.config/kb/config

# Or export for the current session
export ANTHROPIC_API_KEY=sk-ant-...

Other providers work too:

# OpenAI
KB_LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

# Local model via Ollama (no API key needed)
KB_LLM_PROVIDER=ollama

kb query "how does authentication work?"

Returns a natural-language answer with an overall confidence score, source citations, and any contradictions between sources.

Human-readable streaming

kb query --human "how does authentication work?"

Streams the answer to the terminal as it's generated.

Tell your agents about KB

If you use an AI coding agent (Claude Code, Cursor, etc.), add a prompt to your project config telling it when and how to use KB. Without this, agents won't know the knowledge base exists.

We provide ready-made prompt templates you can drop into your CLAUDE.md, .cursorrules, or equivalent — see Agent prompts.

What requires an API key

KB works entirely locally out of the box. An LLM provider (Claude, OpenAI, or local via Ollama) unlocks additional capabilities but is never required for core retrieval.

Capability Local only With API key
Ingestion, embedding, hybrid search
Raw retrieval with confidence signals
Chunk enrichment (entity/keyword annotations)
Multi-query expansion
Answer synthesis
Cross-fragment confidence assessment
Contradiction detection

Run kb config at any time to see where your settings are coming from. See CLI Reference — Configuration for the full search path.

Next steps