---

✨ Check out our autogenerated wiki✨

---

KB is a local-first knowledge layer for development workflows.

It gives you a CLI and runtime that capture what your project learns over time — so decisions, fixes, and context don't disappear into chat history or PR threads.

Instead of re-deriving the same answers, KB lets you:

• 📝 Record decisions and facts as you work
• 🔍 Query past context before making changes
• 🗑️ Invalidate stale facts before they mislead future work

All of it lives alongside your code, versioned in Git, and queryable like a lightweight memory system.

🧠 What it actually does

KB turns day-to-day development into a feedback loop:

• 📥 Capture — Save facts, decisions, and discoveries as you go
• 🔁 Recall — Query relevant context when you need it
• 🔧 Repair — Replace or remove stale knowledge before it drifts

⚡ Quick Start

1) Install KB

Install the latest published release:

pnpm add -g https://github.com/rosenjcb/kb/releases/latest/download/kb-cli-node22.tgz
command -v kb

Or build and install from this checkout:

pnpm install
pnpm run check
pnpm run install:global
command -v kb

KB expects Node 22+ in the shell that runs kb. Both install paths prepare KB's native runtime automatically. If you later switch Node versions, rerun kb sync or pnpm run install:global.

2) Configure ~/.kb/config.json

Provider is auto-detected from whichever key is present. To set one explicitly:

kb config set llm.provider openai

Fact retrieval method

KB supports two strategies for how facts are retrieved during query, chat, and document generation:

Method	Config value	Description
Query expansion (default)	query_expansion	Expands the query with synonyms and graph context, searches the index, and ranks results. Efficient and focused.
All facts	all_facts	Loads every fact in the KB into the prompt. No search or ranking — the LLM sees everything. Best for small KBs or exhaustive coverage.

# Switch to all-facts mode
kb config set fact_retrieval_method all_facts

# Switch back to the default
kb config set fact_retrieval_method query_expansion

# Or unset to use the default
kb config unset fact_retrieval_method

In all_facts mode, facts are dumped once per session context — multi-turn agent loops (docs generate, chat) load all facts on the first retrieval and then skip redundant dumps for the remainder of the session.

3) Initialize your KB base

Walk through the chat-based wizard to create your knowledge base.

cd ~/{{YOUR_AWESOME_REPO}}
kb && /init --base dogfood

Refresh an existing base after README or docs changes:

kb scan --base dogfood
kb && /base use dogfood
kb && /scan

kb scan reuses content hashes to skip unchanged collected docs and source files where possible, so routine rescans stay incremental.

4) Start using KB intents

kb submit "Document writer now supports sqlite index sync"
kb query "sqlite index sync behavior" --limit 5
kb invalidate "kb use should persist across sessions" "kb base use is session-scoped; use kb base use --default to write a persistent default"

� Troubleshooting

Native module bindings error on global pnpm install

If you see Could not locate the bindings file for better-sqlite3 when running kb after installing globally:

Option 1: Uninstall and reinstall (recommended)

pnpm remove -g kb
pnpm add -g https://github.com/rosenjcb/kb/releases/latest/download/kb-cli-node22.tgz

Option 2: Force rebuild from global store

pnpm add -g --force https://github.com/rosenjcb/kb/releases/latest/download/kb-cli-node22.tgz

This happens because pnpm skips build scripts by default for security. KB's global installation requires the native SQLite bindings to run. Reinstalling with the commands above ensures the native module is built.

�📖 CLI Reference

🎯 KB intents

One read intent:

kb query "<topic>" [--base <name>] [--limit <n>] [--type decision] [--discovery shallow|deep] [--session] [--verbose] [--debug] [--output human|json]

Two mutation intents:

kb submit "<fact>" [--base <name>] [--domain ops] [--source runbook] [--include-session-logs] [--output human|json]
kb invalidate "<old-fact>" ["<replacement-fact>"] [--base <name>] [--apply] [--output human|json]

📂 Documents

kb docs list [--base <name>] [--limit <n>] [--output human|json]
kb docs view <document-id> [--base <name>] [--output human|json]
kb docs view --title "<exact title>" [--base <name>] [--output human|json]
kb docs generate "<prompt>" [--type howto|introduction|reference|decision|runbook] [--limit <n>] [--base <name>]
kb docs rename <document-id> "<new title>" [--base <name>]
kb docs delete <document-id> [--base <name>] [--force]

🛠️ Other commands

kb base use <base>             — switch the active base for the current session
kb base use --default <base>   — save persistent default to ~/.kb/config.json
kb base use --show             — show active base and config default
kb base delete <base>          — delete a base and all its data (prompts unless --force)
kb config get
kb config set <key> <value>
kb config unset <key>
kb init [--base <name>] [--detach | --resume] [--stop-after <cycle>]
kb scan [--base <name>] [--non-interactive]
kb facts list|search|show ...
kb graph ...
kb logs list|show|compare ...
kb skill install|uninstall
kb sync
kb publish <notion|jekyll> [options]

Interactive session commands (type while in kb):

Command	Effect
/query, /submit, /invalidate	Run the core KB intents inline
/base, /docs, /facts, /graph, /publish, /sync, /config, /logs, /skill	Use the same command families you get in the CLI
/clear	Wipe screen, reset fact pool and full conversation history — start fresh
/exit	Leave the session
/help	List all in-session commands
/docs generate "<prompt>"	Guided doc-draft wizard
/init [args] / /scan [args]	Build or refresh the KB without leaving the session
/session	Show turn-by-turn token, cost, and timing stats

How chat retrieval works:

• Each turn fetches facts via the research orchestrator (up to 5 iterations, 3 graph hops, 40-concept frontier).
• The LLM can call the query tool mid-answer to fetch additional facts when it needs more depth.
• Facts retrieved in earlier turns are excluded from subsequent retrieval — they remain available in the LLM's conversation history. Use /clear for a completely fresh start.
• If a follow-up introduces 2+ new topical terms (e.g. "What about AST? How do I add Python support?"), those new terms drive retrieval instead of being appended to the previous topic.

🔄 Keeping kb up to date

kb sync

kb sync installs the latest published kb-cli-node22.tgz release from GitHub Releases, refreshes KB's native runtime in ~/.kb, and does not use your current project directory. It will complain early if the current shell is not running Node 22+.

Verify

kb submit "SQLite hybrid search enabled for this workspace"
kb query "hybrid sqlite retrieval" --limit 5

If hybrid retrieval is unavailable or exceeds the latency budget, KB automatically falls back to lexical markdown query.

🗓️ Daily Workflow

kb query "topic"
kb submit "new fact"
kb invalidate "old fact" "replacement fact"

🤖 Agent skill: use KB while you develop

• Found here: skills/kb-dev-workflow/SKILL.md

The skill is self-contained (workflow + full command shapes). The CLI Reference section above stays the in-repo quick reference for humans.

🗄️ Swapping and deleting bases

kb base use foo            # switch the active base for this session
kb base use --default foo  # save a persistent default
kb base use --show             # show active base and config default
kb base delete bar --force # delete a base and all its data
kb scan --base foo              # refresh KB updates incrementally from changed docs/source files
kb sync                           # install the latest published GitHub release
kb && /base use foo
kb && /scan
kb && /sync

Base resolution order (both live in ~/.kb/config.json):

1. activeBase — current working base from kb base use <base>
2. defaultBase — persistent default from kb base use --default <base> (or kb default <base>)

Named bases store their SQLite data under ~/.kb/sessions/<base>/.

🧪 Development Commands

pnpm run test
pnpm run type-check
pnpm run lint
pnpm run build

🗺️ Project Map

src/core   — provider abstraction, intent loop, agent loop, runtime types
src/cli    — CLI entrypoint, KB intent parsing, base selection, kb init
src/tools  — write/query tools, markdown + sqlite index integration