A fast, private, local knowledge base for Markdown. kb indexes directories into SQLite FTS5, provides deterministic lexical search, and retrieves the original source without requiring embeddings, inference, a daemon, or a hosted service.
- Named directory collections with glob and ignore rules
- Incremental indexing that avoids rereading unchanged files
- Weighted BM25 full-text search with phrases and explicit prefixes
- Collection filters, snippets, path context, human output, and JSON output
- Retrieval by virtual path or stable content-derived ID
- One-based line ranges and numbered output
- Versioned configuration snapshots with atomic import
- SQLite integrity, FTS consistency, cleanup, and status commands
- Bounded indexing memory and transaction sizes
- No symbolic-link traversal, background service, or inference dependency
brew install akonwi/tap/kb
kb versionHomebrew packages are available for macOS and Linux on arm64 and amd64. Prebuilt archives and checksums are also available from GitHub Releases.
Building requires Ard 0.44 or newer and Go 1.27 or newer:
cd /path/to/kb
ard build main.ard --out kb
mkdir -p ~/.local/bin
install -m 755 kb ~/.local/bin/kbSee Getting started for installation details and your first collection.
# Register a Markdown directory
kb collection add notes ~/Notes
# Build its index
kb update notes
# Search it
kb search sqlite migrations --collection notes
# Retrieve original Markdown
kb get notes/projects/database.mdkb does not watch directories. Run kb update after source files change; an update without a collection name refreshes every collection.
kb search sqlite migrations # implicit AND
kb search '"schema migration"' # phrase
kb search 'migrat*' # prefix
kb search sqlite --collection notes --limit 20
kb search sqlite --jsonResults include a virtual path such as notes/projects/database.md and a stable 16-character content ID.
kb get notes/projects/database.md
kb get 4ef077069afe4fef
kb get notes/projects/database.md --lines 10:20 --number
kb get notes/projects/database.md --jsonLine ranges are one-based and inclusive.
| Command | Purpose |
|---|---|
kb version |
Print the build version |
kb collection add NAME PATH |
Register a directory |
kb collection list |
List collections |
kb collection show NAME |
Show collection settings |
kb collection remove NAME |
Remove the index entry, never source files |
kb update [NAME] |
Incrementally refresh one or all collections |
kb update --verify |
Rehash every matching file |
kb search QUERY |
Search indexed Markdown |
kb get ID|COLLECTION/PATH |
Retrieve original Markdown |
kb status |
Show collection and document counts |
kb doctor |
Check database, FTS, and collection health |
kb cleanup [--vacuum] |
Remove stale data and optionally reclaim pages |
kb config export FILE |
Export collection configuration |
kb config import FILE |
Import collection configuration |
Run kb help or read the complete CLI reference.
All indexing and search run locally. The SQLite database is stored under the platform-native per-user data directory:
| Platform | Default database |
|---|---|
| macOS | ~/Library/Application Support/kb/index.sqlite |
| Linux/Unix | $XDG_DATA_HOME/kb/index.sqlite, otherwise ~/.local/share/kb/index.sqlite |
| Windows | %LOCALAPPDATA%\\kb\\index.sqlite |
Set KB_DATABASE to override the complete path. kb reads source Markdown but never modifies or deletes it.
- Getting started
- CLI reference
- Data, backup, and recovery
- Markdown indexing behavior
- Lexical search behavior
- Filesystem edge behavior
ard format .
ard format --check .
ard check main.ard
ard test
go test ./...
ard build main.ard --out kbGenerated files are written under ard-out/ and are not committed.