Get started

Use a release binary

Select the archive for your operating system and CPU in GitHub Releases. Downloads follow the source repository's access policy. Check the archive against SHA256SUMS, then extract it. Add the extracted directory to your PATH and run the commands from that directory. The Windows archive contains knowledge.exe, which also runs as knowledge on PATH.

knowledge -c configs/reference.yml init-security
knowledge -c configs/reference.yml check-server
knowledge -c configs/reference.yml index
knowledge -c configs/reference.yml search "sensor calibration" --mode lexical
knowledge -c configs/reference.yml serve

The reference profile uses the included OKF example, encrypted SQLite, and read-only HTTPS and MCP. Select an encoder in the YAML when you want vector search. Reference YAML

Build from source

In the monorepo, work from apps/knowledge. After building, install the binary into a directory on your PATH, or add the workspace’s target/release directory to PATH for this shell.

Start with knowledge.yml, which targets the original sample OKF folder. Read configuration before changing paths or model roles.

python3 scripts/fetch-model.py
python3 scripts/build.py --backend metal # Apple silicon. Use cpu on CPU-only hosts.
export PATH="$(cd ../.. && pwd)/target/release:$PATH"
knowledge --validate-config
# Run once per local profile.
knowledge init-security
knowledge index
knowledge models
knowledge search "sensor calibration" --mode hybrid --rerank mmr
knowledge serve

The fetch script explicitly downloads the sample models. No startup action silently downloads weights. Default inference uses EmbeddingGemma 2 and its projector for vectors and Qwen2.5 1.5B Instruct for answers. Transcription and image-to-text are separate optional roles, not outputs of the embedding model.

CPU deployments must set gpu_layers: 0 for both native model roles; build with --backend cpu. HTTP-only deployments use --backend http and configure compatible model servers. On Windows, run the Python build helper in Developer PowerShell and add the workspace’s target\release directory to Path. See deployment.

init-security refuses existing credentials. It creates private, independent database/API secrets, TLS material and derived YAML/JSON configs. Keep source, state and keys on protected storage. On another knowledge base use another config, database, credentials and API port. Explicitly opt into URL origins, HTTP model policies and source writes. Initialization preserves selected model roles and server settings while provisioning fresh TLS/credentials.

serve binds https://localhost:8443 by default and starts the folder watcher/worker. Use the generated local CA and bearer credential; security shows clients. No service is installed by setup. watch runs ingestion without HTTP; index scans and drains currently available jobs once. Failed jobs remain visible in status; correct the error and use retry/work or the watcher.

To try the additional media fixture, install FFmpeg and Poppler, then initialize the separate profile once:

knowledge -c configs/formats.yml init-security --output .knowledge-formats
knowledge -c configs/formats.yml index
knowledge -c configs/formats.yml search "a blue circle" --mode vector --representation native_video_frame

The fixture folder, policies and results are documented in formats and the evidence report. The sample config expects decoder executables on PATH; set their paths when necessary.

Read Markdown →