# README.md
---
β¨ Our autogenerated wiki for kb.β¨
---
**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 and verify
```bash
pnpm install
pnpm run check
npm run install:global
command -v kb
```
> KB expects `Node 22+` in the shell that runs `kb`.
For installed clients, the supported release path is GitHub Releases. CI builds a fresh `kb-cli-node22.tgz` package for every push to `main`, and you can install or upgrade it with:
```bash
npm install -g https://github.com/rosenjcb/kb/releases/latest/download/kb-cli-node22.tgz
```
### 2) Configure `~/.kb/config.json`
Provider is auto-detected from whichever key is present. To set one explicitly:
```bash
kb config set llm.provider openai
```
### 3) Initialize your KB base
Walk through the chat-based wizard to create your knowledge base.
```bash
cd ~/
kb && /init --base dogfood
```
Refresh an existing base after README or docs changes:
```bash
kb scan --base dogfood
kb scan --base dogfood --apply
kb && /base use dogfood
kb && /scan --apply
```
### 4) Start using KB intents
```bash
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"
```
## π CLI Reference
### π― KB intents
One read intent:
```
kb query "" [--limit 5] [--type decision] [--discovery shallow|deep] [--session] [--verbose] [--debug] [--output human|json]
```
Two mutation intents:
```
kb submit "" [--domain ops] [--source runbook] [--output human|json]
kb invalidate "" [""] [--preview|--dry-run]
```
### π Document browsing
```
kb docs list [--base ] [--limit ] [--output human|json]
kb docs view [--base ]
kb docs view --title "" [--base ]
```
### π οΈ Other commands
```
kb base use β switch the active base for the current session
kb base use --default β save persistent default to ~/.kb/config.json
kb base use --show β show active base and config default
kb base delete β delete a base and all its data (prompts unless --force)
kb config get
kb config set
kb config unset
kb init [--base ] [--detach | --resume] [--stop-after ]
kb scan [--base ] [--apply]
kb sync
kb publish [options]
kb chat [--verbose] [--debug] [--base ]
```
### π Keeping `kb` up to date
```bash
kb sync
```
`kb sync` installs the latest published `kb-cli-node22.tgz` release from GitHub Releases. It does not use your current project directory, and it does not build from source locally. It will complain early if the current shell is not running `Node 22+`.
### 1) Enable native SQLite dependency (if needed)
```bash
pnpm approve-builds --all
pnpm rebuild better-sqlite3
```
### 2) Verify
```bash
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
```bash
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`](skills/kb-dev-workflow/SKILL.md)
The skill is self-contained (workflow + full command shapes). The [CLI Reference](#cli-reference) section above stays the in-repo quick reference for humans.
## ποΈ Swapping and deleting bases
```bash
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 # preview KB updates from changed README-like files
kb scan --base foo --apply # apply planned scan updates
kb sync # install the latest published GitHub release
kb && /base use foo
kb && /scan --apply
kb && /sync
```
Base resolution order (both live in `~/.kb/config.json`):
1. `activeBase` β current working base from `kb base use `
2. `defaultBase` β persistent default from `kb base use --default ` (or `kb default `)
Named bases store their SQLite data under `~/.kb/sessions//`.
## π§ͺ Development Commands
```bash
pnpm run test
pnpm run type-check
pnpm run lint
pnpm run build
```
## πΊοΈ Project Map
```text
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
```