@nzpr/kb

@nzpr/kb is a CLI for working with a GitHub-backed knowledge base that is synced into a vector database.

A knowledge entry is intentionally minimal:

• title
• text

The repo is the authority for approved knowledge. The vector database is a published search index built from that repo.

Install

npm install -g @nzpr/kb

Node.js 20+ is required.

Commands

kb init-repo [--interactive] [--layout repo-root|nested-kb] [--dir PATH] [--repo OWNER/REPO]
kb create --title TEXT --text TEXT [--path RELATIVE_PATH] [--repo OWNER/REPO]
kb edit --title TEXT --text TEXT [--path RELATIVE_PATH] [--repo OWNER/REPO]
kb search <query>
kb ask <question>
kb list
kb catalog [--json]
kb publish [--docs-root PATH] [--knowledge-root PATH]
kb doctor

Run kb <command> --help for exact runtime requirements.

Core Model

There are three separate surfaces:

• GitHub repo: the source of truth for approved knowledge documents
• GitHub issues and workflows: the proposal, review, approval, and materialization pipeline
• Vector database: the published retrieval index used by kb search and kb ask

That split matters:

• creators do not write to the default branch directly
• reviewers approve knowledge on the issue
• GitHub Actions writes the approved Markdown into the repo
• kb publish syncs the repo state into the vector DB

Knowledge Format

Knowledge is stored as Markdown in the knowledge repo under docs/ or kb/docs/.

Each document should just be:

# Title

Text that should be retrieved by search.

During publish, the title and body are extracted from the Markdown document and written into the database as one searchable document row.

Creator Workflow

Use kb create when you want to propose new knowledge.

export KB_GITHUB_REPO=owner/repo
export GITHUB_TOKEN=...

kb create \
  --title "How we manage knowledge" \
  --text "Write the exact knowledge text here."

What kb create does:

• works against the remote GitHub knowledge repo
• inspects existing remote documents
• computes semantic and lexical similarity against existing entries
• shows close matches
• lets you choose:
  • create new knowledge
  • switch to editing an existing matching entry
  • cancel

What this prevents:

• duplicate entries for the same topic
• creating a second knowledge document when an update to an existing one is the right move

If you already know the target path for the new document, pass --path.

Edit Workflow

Use kb edit when you are not satisfied with existing knowledge and want to revise it.

export KB_GITHUB_REPO=owner/repo
export GITHUB_TOKEN=...

kb edit \
  --title "Updated knowledge title" \
  --text "Write the revised knowledge text here."

What kb edit does:

• works against the remote GitHub knowledge repo
• finds the best existing matching document semantically
• lets you confirm which existing document should be edited
• reopens the prior proposal issue for that exact document path
• rewrites the issue body with the new title and text
• removes kb-approved so approval must be explicit and fresh

If you already know the exact document to revise, pass --path.

What this prevents:

• editing the wrong document by accident
• silently creating a second document instead of revising the real one
• preserving stale approval after the content has changed

Duplicate Handling

Duplicate protection is part of the authoring flow.

kb create:

• looks for semantically similar existing knowledge
• shows likely matches before creating anything
• lets you cancel or switch to editing one of those entries

kb edit:

• looks for the best existing matching knowledge
• asks you to confirm the edit target when more than one plausible match exists
• is anchored to the existing document path once selected

Approval is always path-specific:

• the issue body stores ### Relative Path
• the workflow materializes exactly that document path
• the publish step syncs the repo state that exists after merge

Review and Approval Workflow

Review happens on GitHub issues.

The standard review loop is:

1. creator runs kb create or kb edit
2. KB proposal issue is created or reopened
3. reviewer edits the issue if needed
4. reviewer manually adds kb-approved
5. GitHub Actions materializes the document change as a PR
6. the PR auto-merges
7. publish runs and syncs the repo into the vector DB

Important rule:

• approval is manual and explicit through the kb-approved label
• reopened edit issues do not keep approval; kb-approved must be added again

GitHub Actions Workflows

kb init-repo scaffolds two workflows into the knowledge repo:

kb-issue-to-pr

Triggered on:

• issue labeled

Behavior:

• runs only when the added label is kb-approved
• converts the approved issue into the target Markdown document
• creates a PR with that document change
• auto-merges the PR
• comments back on the issue with the PR number

kb-publish

Triggered on:

• push to main that changes docs/** or workflow files
• manual workflow_dispatch

Behavior:

• checks out the repo
• installs @nzpr/kb
• runs kb publish
• writes the live repo state into the vector DB

Vector Database and Publish

kb publish is the sync step from repo to retrieval index.

export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB

kb publish --docs-root ./docs

What publish does:

• reads every Markdown doc under the docs root
• extracts title and body
• computes embeddings for each document
• upserts documents into the database
• removes database rows for docs that no longer exist in the repo

The result is:

• repo state and database state stay aligned
• the vector DB reflects what is actually approved and merged

Semantic Search

kb search and kb ask query the vector database, not GitHub.

export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB

kb search "deployment rollback rule"
kb ask "How do we approve a knowledge proposal?"

How retrieval works:

• lexical search over document text
• semantic search over stored embeddings
• score merge of lexical and semantic signals
• weak matches are filtered out

kb ask currently returns the best retrieved guidance with sources. It is a retrieval wrapper, not a generative answer engine.

Embeddings

Authoring commands and publish use the same embedding runtime configuration when semantic matching is needed.

Supported modes:

• local-hash
• bge-m3-openai

Example remote embedding config:

export KB_EMBEDDING_MODE=bge-m3-openai
export KB_EMBEDDING_API_URL=https://embeddings.example.com/v1/embeddings
export KB_EMBEDDING_MODEL=BAAI/bge-m3
export KB_EMBEDDING_API_KEY=...

Use local-hash for cheap local matching. Use bge-m3-openai for higher quality semantic matching and search.

Consumer Workflow

For users or agents consuming knowledge, the common flow is:

export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB

kb search "deployment rule"
kb ask "How do we deploy safely?"
kb list
kb catalog --json
kb doctor

That is the normal read path. Most usage should be kb search and kb ask, not kb create or kb edit.

Repo Bootstrap

Use kb init-repo to scaffold a knowledge repo and configure the GitHub automation.

kb init-repo --interactive

It creates:

• issue template for KB proposals
• kb-issue-to-pr workflow
• kb-publish workflow
• docs directory scaffold

For remote bootstrap, kb init-repo --repo ... needs a GitHub token with repository admin access.

Notes

• kb publish does not need GitHub credentials.
• kb create and kb edit are GitHub-first authoring commands.
• The repo is the approved truth; the vector DB is the published index.
• If the repo and DB ever diverge, rerun publish from the repo state.