kbx

kbx is a local-first knowledge base CLI that makes workspace files searchable by AI assistants.

It stores workspace data under .kbx/, runs locally, and exposes retrieval through CLI commands and a stdio MCP server. Downloaded or offline-loaded model files are cached under the user-level kbx directory.

kbx is alpha software. The core CLI and MCP retrieval flow are usable, but the public package is still early and may change before a stable v1.

Project Status

• Current release line: 0.1.x alpha.
• License: MIT. See LICENSE.
• Changes: CHANGELOG.md and GitHub Releases generated by antfu/changelogithub.
• Contributing: CONTRIBUTING.md.
• Security reports: follow SECURITY.md, not public issues.
• Support and questions: SUPPORT.md.

Install

npx -y @lord007tn/kbx --help
npx -y @lord007tn/kbx setup --model minilm
npx -y @lord007tn/kbx init --model minilm
npx -y @lord007tn/kbx ingest
npx -y @lord007tn/kbx search "your query"

Requires Node.js >=20.19.0. The npm/npx package is the supported distribution path for this alpha.

Quick Smoke Test

From a workspace you want to index:

npx -y @lord007tn/kbx init --model minilm
npx -y @lord007tn/kbx ingest
npx -y @lord007tn/kbx search "project decisions"
npx -y @lord007tn/kbx doctor

Development

npm install
npm run typecheck
npm test
npm run build
npm run bench:projects -- --roots D:\Work --limit 3 --variants hash,minilm
npm run release:preflight
npm run smoke:pack
npm run smoke:install

Use the deterministic hash embedder during development to avoid downloading model weights:

$env:KBX_EMBEDDER='hash' # PowerShell

Basic Usage

kbx init
kbx init --choose-model
kbx init --model minilm
kbx init --git-root --model nomic
kbx setup --model minilm --client codex
kbx ingest
kbx ingest docs --include "**/*.md" --exclude "drafts/**" --no-gitignore
kbx ingest docs --watch
kbx search "workspace registry"
kbx search "workspace registry" --graph
kbx context "workspace registry"
kbx search "workspace registry" --fresh
kbx search "workspace registry" --global
kbx search "workspace registry" --reranker model
kbx watch
kbx watch --background
kbx watch --stop
kbx status --fresh
kbx doctor --repair
kbx memory add "Decision: keep v1 retrieval-only." --type decision --tag retrieval --retention-days 30
kbx memory list
kbx memory prune
kbx config set sessions.capture full
kbx session start --client codex --name "implementation session"
kbx session replay <session-id>
kbx graph build
kbx graph query "startSession"
kbx rewind preview <session-id>
kbx stats --fresh
kbx config set chunk.strategy sentence
kbx config set watch.auto enabled
kbx config set dev.report enabled
kbx dev report add --task "fix retrieval" --summary "Used kbx context and updated tests" --good "Relevant chunks were easy to cite"
kbx config set init.root_preference git-root --global
kbx model list
kbx model benchmark
kbx model load ./nomic-embed-text-v1.5 --as nomic
kbx model use

Supported ingest inputs include Markdown, plain text, PDF, DOCX, PPTX, XLSX, EPUB, images (.png, .jpg, .jpeg, .webp, .gif, .tif, .tiff, .bmp), common source-code files, and structured text formats such as JSON, YAML, TOML, XML, SQL, HTML, and CSS.

Ingest respects .gitignore plus an optional root .kbxignore file. Use .kbxignore for files that should stay in the repo but not become searchable context, such as large dumps, screenshots, generated declarations, or exported artifacts.

Inside Git workspaces, workspace-file chunks are tagged with the checked-out branch and commit at ingest time. Search defaults to the current branch when that branch has indexed content, so the same path can have separate indexed content on main and a feature branch. Identical chunk text across branches is embedded once and reused through branch/path aliases. Non-Git workspaces keep the original path-based behavior.

Image ingest indexes embedded PNG text metadata and can run OCR when tesseract is available. To plug in a different OCR engine, set KBX_OCR_COMMAND to a command that writes extracted text to stdout; use {file} as the image path placeholder:

KBX_OCR_COMMAND='my-ocr --input {file}' kbx ingest screenshots

External paths are rejected unless explicitly snapshotted into the workspace:

kbx ingest C:\Users\you\notes --allow-external

Alpha Limitations

• Distribution is npm/npx only; standalone binaries, signed platform archives, and Homebrew are not part of this alpha.
• Embeddings run on CPU. GPU acceleration is not selected automatically.
• kbx retrieves cited chunks; it does not generate answers, run chat, or act as an LLM.
• The first real embedding run may download model files unless you choose an already cached or offline-loaded model.
• Supported platforms depend on published @zvec/zvec Node bindings. Windows ARM and macOS Intel are not covered by the current alpha support target.
• Image OCR requires tesseract or a configured KBX_OCR_COMMAND; otherwise image ingest is limited to extractable metadata/text.

MCP

Run the stdio MCP server from an initialized workspace:

kbx mcp

Claude Desktop / Cursor style config:

{
  "mcpServers": {
    "kbx": {
      "command": "kbx",
      "args": ["mcp"]
    }
  }
}

Generate client-specific snippets:

kbx mcp config --list
kbx mcp config claude
kbx mcp config cursor
kbx mcp config codex
kbx mcp config zed
kbx agent guide
kbx agent hooks claude-code
kbx agent plugin claude-code

Claude Code can use either direct MCP/hook snippets or the packaged plugin under plugins/claude-code/kbx. The plugin includes MCP server config, a PostToolUse refresh hook, a kbx-dev-mode skill, and a /kbx:kbx-status command. Test it locally with:

claude --plugin-dir ./plugins/claude-code/kbx

Install it through the repository marketplace from inside Claude Code:

/plugin marketplace add ./
/plugin install kbx@kbx-tools

Claude Desktop / Claude MCP config and Codex CLI use MCP snippets:

kbx mcp config claude
kbx mcp config codex

Other clients can integrate with the generic file refresh hook when they expose a stable post-edit lifecycle hook:

printf '{"paths":["src/app.ts"]}' | kbx hook files refresh

Tools exposed:

• kbx_search
• kbx_context
• kbx_search_global
• kbx_search_many
• kbx_list_sources
• kbx_get_chunk
• kbx_index_status
• kbx_file_context
• kbx_inspect
• kbx_agent_guide
• kbx_watch_status
• kbx_session_handoff
• kbx_session_list
• kbx_session_show
• kbx_session_events
• kbx_session_record_event
• kbx_session_checkpoint
• kbx_session_replay
• kbx_rewind_preview
• kbx_graph_build
• kbx_graph_query
• kbx_graph_stats
• kbx_memory_add
• kbx_memory_history
• kbx_memory_list
• kbx_memory_verify
• kbx_refresh_index
• kbx_refresh_file
• kbx_mcp_config
• kbx_dev_report_add
• kbx_dev_report_list
• gated destructive tools: kbx_remove_source, kbx_reset_index, kbx_forget_workspace, kbx_delete_workspace_kb, kbx_rewind_apply

kbx_context returns a bounded, grouped markdown context bundle for task-level use. kbx_search returns compact previews, chunk IDs, source citations, scores, match type, and bounded freshness metadata. It also supports progressive disclosure: call kbx_search again with expand_ids to fetch full text for several returned chunks, or use kbx_get_chunk for one specific result. They opportunistically refresh changed indexed content when the change count is small, so the search tools are not advertised as read-only to MCP clients. Use kbx_refresh_index, kbx watch, or kbx config set watch.auto enabled for larger continuous updates. The MCP server also exposes initialization instructions, a kbx_usage prompt, and a kbx://usage resource with agent guidance.

kbx_file_context returns indexed context and retained memories linked to specific files for active edit or review work. Active search and file context omit superseded retained notes by default; pass --include-superseded-memories in the CLI or include_superseded_memories=true in MCP when auditing memory history. kbx_inspect returns a read-only local summary of sources, freshness, retained-memory counts, graph status, and recent indexed files.

kbx_session_handoff returns a compact workspace/index summary for session start or handoff. Durable session capture is opt-in through sessions.capture; session events, checkpoints, and rewind snapshots are stored in .kbx/sessions.db. kbx_memory_add lets an agent save explicit compact decisions, preferences, architecture notes, bug lessons, workflows, facts, handoffs, or events with a required retention period. Retained notes support typed metadata, relevant files, tags, supporting chunk IDs, supersession links, and deterministic retention scores; when a new note supersedes an older one, the old note is marked as not latest rather than deleted. kbx_memory_verify checks whether a retained note's supporting chunk IDs still resolve to indexed source context, and kbx_memory_history returns the supersession chain for audit workflows. Retained notes are stored under .kbx/sessions and become searchable after indexing.

CLI equivalents are available for local inspection:

kbx search "supporting decision" --json
kbx search "old decision" --include-superseded-memories --json
kbx file-context src/search.ts --term graph
kbx inspect --json
kbx memory verify <memory-id> --json
kbx memory history <memory-id> --json

kbx_dev_report_add and kbx dev report add save short local Codex/kbx feedback reports under .kbx/debug/reports only when dev.report=enabled. Use this for opt-in development-mode notes about issues, findings, good behavior, and follow-ups from a kbx-assisted agent run.

Search uses deterministic hybrid retrieval by default. Optional graph-expanded candidates can be included with kbx search --graph or MCP use_graph=true after kbx graph build; this remains opt-in until retrieval evals prove it should be part of the default path. Optional model or LLM reranking can be layered in with an external command:

kbx search "session timeout" --reranker local
kbx search "session timeout" --reranker model
kbx search "session timeout" --reranker command --reranker-command "node rerank.mjs"

local uses kbx's built-in deterministic source, phrase, proximity, and match-type reranking. model loads an opt-in Transformers.js feature-extraction reranker (Xenova/all-MiniLM-L6-v2 by default, override with --reranker-model or KBX_RERANK_MODEL). The command mode reads one JSON object from stdin (query plus candidates) and writes either { "scores": { "<chunk-id>": 0.9 } } or an array of { "id", "score" }.

Retrieval quality can be measured before and after reranker changes with a JSON eval corpus:

kbx eval retrieval evals/retrieval.json -k 5

A tiny example corpus lives under examples/retrieval-eval/.

npm Release

kbx is distributed as the scoped npm package @lord007tn/kbx and is intended to run directly through npx -y @lord007tn/kbx ... or an npm-installed kbx binary. npm run smoke:pack verifies the npm package stays small and only contains the CLI build, Claude Code plugin metadata, package metadata, README, and license. npm run smoke:install packs the project locally, installs that tarball through npm exec, and runs kbx --version from outside the repository. The release workflow validates the package, publishes it to npm with secrets.NPM_TOKEN, and creates a Conventional Commits changelog release with antfu/changelogithub.

See docs/release.md for the release checklist.

Public releases start at v0.1.0. The package version, src/version.ts, and Git tag must match exactly before a release tag is pushed.

Destructive MCP tools are disabled by default. Enable them only when you want agents to perform delete/reset operations:

kbx config set mcp.destructive_tools enabled

See docs/agent-usage.md for Claude/Codex/Cursor style usage guidance.

Current Scope

This is alpha scope. The CLI is usable through npm/npx for local development, smoke testing, and MCP-backed retrieval workflows.

Implemented:

• workspace init, registry list/forget/delete
• ingest/search/stats/reset/doctor/config
• guided kbx setup, readable kbx status, and grouped kbx context
• global search across registered workspaces with kbx search --global
• doctor repair flow with kbx doctor --repair
• explicit search freshness with kbx search --fresh
• hot indexing with kbx ingest --watch, kbx watch, or kbx config set watch.auto enabled
• source list/remove
• external import snapshots
• explicit retention-bound session memory source under .kbx/sessions with typed metadata, citation verification, supersession history, and latest-only active retrieval
• MCP retained memory tools, file-focused context, workspace inspection, and compact session handoff summaries
• opt-in durable sessions with checkpoints, replay, and retention pruning
• session rewind preview/apply from captured file snapshots
• deterministic graph knowledge build/query/stats over indexed chunks
• PDF and DOCX text extraction during ingest
• ingest policy overrides with --include, --exclude, and --no-gitignore
• root .kbxignore support in addition to .gitignore
• Git branch-scoped workspace indexing, branch-aware search defaults, and vector storage dedupe for identical chunk content
• heading-aware Markdown, fixed text/code, and sentence chunking
• Zvec-backed local vector collection
• hybrid vector and SQLite FTS5 lexical retrieval
• deterministic retrieval enhancers with post-fusion reranking and query-centered snippets
• built-in local reranker mode plus optional external command reranker
• Transformers.js embeddings with a hash test embedder
• model catalog list/use/benchmark, benchmark cache, installed status, and offline load from a local model directory
• init-time model selection with --model, --choose-model, git-root prompts, and user-level root preference
• interactive model switch reindex prompt
• stdio MCP server
• expanded MCP read, session, graph, maintenance, watch status, config, opportunistic freshness, and gated destructive tools
• MCP adapter config validation through doctor
• local agent guidance through kbx agent guide
• Claude Code hook adapter for refreshing kbx after Write/Edit/MultiEdit
• CI and npm release workflow with package dry-run validation, install smoke test, and npm provenance publishing
• conservative default secret/key/env-file exclusions during ingest
• generated-file exclusions and local project benchmark tooling
• example retrieval eval corpus

Non-goals:

• answer generation, ask mode, or chat; kbx stays a retrieval layer
• standalone binaries, platform archives, signing/notarization, and Homebrew packaging; npm/npx is the supported distribution path