@amsterdamdatalabs/enact-docs-search

Hybrid BM25 and vector search over a repository's docs/, .plans/, and .specs/ knowledge trees.

Install

npm install -g @amsterdamdatalabs/enact-docs-search

Verify the installed version:

enact-docs-search --version

Node.js 22 or newer is required. The first semantic query downloads the local Xenova/all-MiniLM-L6-v2 embedding model into the target repository's .cache/docs/models/ directory. The search index is stored alongside it under .cache/docs/index/.

Semantic search uses hnswlib-node, a native Node addon compiled with node-gyp during installation. The machine installing the CLI therefore needs Python 3 and a C/C++ build toolchain: Xcode Command Line Tools on macOS, make/GCC on Linux, or Python plus Visual Studio Build Tools with the Desktop development with C++ workload on Windows. For a global install with npm's lifecycle-script policy enabled, use:

npm install -g @amsterdamdatalabs/enact-docs-search \
  --allow-scripts=hnswlib-node,onnxruntime-node,sharp,protobufjs \
  --foreground-scripts

Check the native installation without downloading the embedding model:

enact-docs-search doctor
enact-docs-search doctor --json

For a project-scoped install, put the lifecycle approvals in the consuming project's root package.json (npm does not accept --allow-scripts on a project-scoped install), then rebuild the native packages:

{
  "allowScripts": {
    "hnswlib-node": true,
    "onnxruntime-node": true,
    "sharp": true,
    "protobufjs": true
  }
}

npm rebuild hnswlib-node onnxruntime-node sharp protobufjs --foreground-scripts

Usage

Run inside a target repository:

enact-docs-search query "how crate boundaries are defined?"
enact-docs-search index
enact-docs-search index --force
enact-docs-search prepare

Queries automatically provision a missing model and refresh missing or stale indexes incrementally. If keyword-only indexing leaves semantic vectors stale, the next hybrid or semantic query repairs them automatically before searching. prepare performs the model bootstrap and a complete semantic index build explicitly. Use enact-docs-search --help for advanced scope, mode, JSON, and exclusion controls.

The package is also usable through npx or bunx:

npx @amsterdamdatalabs/enact-docs-search query "conversation vs tasks"
bunx @amsterdamdatalabs/enact-docs-search query "conversation vs tasks"