kb-search

CLI knowledge base with hybrid search (full-text + semantic vector search).

Install

pipx install kb-search

Quickstart

# Initialise (downloads embedding model ~90MB)
kb init

# Add documents
kb add ~/docs/manual.pdf --tags admin
kb add ~/notes/ --recursive
kb add --note "Always restart nginx after config changes" --tags ops

# Search
kb search "how to install git"
kb search "deploy process" --tags ops --type pdf
kb search "authentication" --format human

# Manage
kb list --format human
kb tags
kb status

How it works

• Ingestion: Documents are chunked (PDFs via Docling, markdown by headers, code by AST/functions) and embedded locally
• Storage: Everything in a single SQLite database (~/.kb/kb.db) using FTS5 for keyword search and sqlite-vec for vector search
• Search: Hybrid retrieval combining BM25 keyword scoring and vector similarity via Reciprocal Rank Fusion
• Output: JSON (for LLM tool use) or human-readable terminal format

Configuration

Optional YAML config at ~/.kb/config.yaml. Works with zero configuration.

kb config                              # View current config
kb config set chunking.pdf.max_tokens 2048  # Change a value

ENV overrides: KB_DATA_DIR, KB_MODEL, KB_DEFAULT_TOP, KB_DEFAULT_FORMAT

Claude Code Skill

This tool is designed to be wrapped as a Claude Code skill. See SKILL.md for the skill definition.