knowledge User Manual

A standalone SQLite3-backed knowledge base for tracking projects, observations, concepts, decision records and narrative documents across independent experiments. cmd/kb is a single kb VERB ARGS binary (matching the git/go command model) covering the full API, plus a read-mostly interactive TUI.

Quick Start

Installation — build from source or install a release binary
Command Reference — the primary kb(1) man page: global flags, every verb, exit status

Run kb with no verb to launch the interactive TUI, or kb help / kb -h to see this same reference at the terminal.

Command Reference

kb follows the TOOL VERB PARAMETERS model — every verb below has its own man page, also reachable via kb help VERB or kb VERB -h.

Verb	Man page	Purpose
`init`	kb-init(1)	create a new, empty workspace
`project`	kb-project(1)	add, list, show, rename projects; set status/description; list a project’s concepts
`observation`	kb-observation(1)	add, list, show, update observations; list an observation’s sources
`concept`	kb-concept(1)	add, list, rename concepts — including scholarly identifiers (DOI, ORCID, ROR, Fundref) — and `suggest` candidate new ones from the corpus
`link`	kb-link(1)	link projects/observations to concepts
`source`	kb-source(1)	manage cited sources; check DOIs against Retraction Watch
`search`, `summary`, `format`	kb-search(1)	full-text search (FTS5) and assembled Markdown views
`ingest`	kb-ingest(1)	index a tree of decision records into the database
`record`	kb-record(1)	author and maintain decision records — new, list, show, set-status, supersede, fmt, concepts
`index`	kb-index(1)	generate a corpus’s `decisions/index.md`; `--check` for staleness, `--all` for a whole tree
`document`	kb-document(1)	ingest, draft, review and tag narrative documents (Markdown, Fountain, text) at graduated abstraction levels
`merge`	kb-merge(1)	reconcile two `knowledge.db` files that drifted independently (e.g. across machines)
`export`	kb-export(1)	write a portable JSON-L snapshot — the no-file-access alternative to `merge`
`import`	kb-import(1)	apply a JSON-L snapshot (from `export`) to the database
`topics`	kb-topics(1)	list every help topic, one man page per verb

Global flags

--db PATH — path to knowledge.db (default ./agents/knowledge.db)
--json — machine-readable output on stdout; errors always go to stderr in both modes, so scripts and other language-model harnesses can drive kb directly
--debug — write a JSONL trace of every knowledge-base call (and, in the TUI, every input event and view change) to ./kb-debug-<timestamp>.jsonl

Full detail on all three: kb(1), § GLOBAL FLAGS.

Interactive TUI

Bare kb (no verb) launches a read-mostly browser: project list → Enter drills into observations → c/o toggles to/from concepts → / opens a search prompt from any view → esc backs out, q quits. See kb(1) for the full description.

Background & Design

These documents record why kb is shaped the way it is — useful if you’re extending it, not required to use it:

decisions/index.md — the decision-record corpus: every architecture/UX decision this module has made, each with its rejected alternatives and the real bugs found along the way. It replaces the old flat DECISIONS.md, which was split into records when this module became the format’s first conversion pilot; kb search reaches the reasoning inside them, not just their titles
module-extraction-design.md / -plan.md — pulling this module out of harvey
cli-tui-design.md / -plan.md — the kb CLI and TUI
debug-logging-design.md / -plan.md — the --debug JSONL trace
jsonl-export-design.md / -plan.md — the export/import JSON-L format and identity/conflict rules
decision-records-design.md / -plan.md — ingest, record and index: decision records as first-class rows
records-portability-design.md / -plan.md — carrying records and their relations through merge, export and import
wikilink-tagging-design.md / -plan.md — [[Name]] inline tagging and frontmatter tags resolving to concepts at ingest time
concept-tag-retrieval-design.md / -plan.md — MatchConceptNames/RecallByConceptNames, an embedder-free retrieval path for small models
narrative-documents-design.md / -plan.md — the documents entity, graduated abstraction levels, and the summary review workflow

Can’t Find What You Need?

Run kb help <verb> or kb <verb> -h for the same reference at the terminal
About — project metadata, license, requirements
Getting Help, Reporting Bugs