Contributing

Thanks for contributing to Knowhere. The project is split across several repositories — make sure you're working in the right one.

Ecosystem

Repository	Description
knowhere	This repo. Backend API and worker — document ingestion, parsing, graph construction, and retrieval.
🖥️ knowhere-dashboard	The web UI. Connects to the API for the full product experience.
🐳 knowhere-self-hosted	Docker Compose stack for self-hosted deployments. Packages the API, worker, and dashboard together.
🐍 knowhere-python-sdk	Official Python SDK for the Knowhere Cloud API.
🦕 knowhere-node-sdk	Official Node.js SDK for the Knowhere Cloud API.

Open or confirm an issue before starting significant changes.
Keep changes scoped and reviewable.
Do not commit real secrets, deployment credentials, or environment-specific private data.

Do not push directly to main or staging.
Start from the agreed source branch for the work.
Use a dedicated feature or fix branch for each change.
Name branches as <type>/<user>/<description>.
Use a lowercase type, preferably one of feat, fix, refactor, chore, docs, test, perf, ci, build, or revert.
Use the human owner or contributor name for user; do not use a generic tool name such as codex.
Keep description short, lowercase, and kebab-case, for example refactor/alice/extract-chunk-converter.
If you are working on publication cleanup, keep migration-only changes on the dedicated migration branch instead of flowing them back into normal private development by default.

Sync the Python services and shared package:

cd packages/shared-python && uv sync
cd ../../apps/api && uv sync
cd ../worker && uv sync

Start the local services:

cd deploy/local-dev && ./start-dev.sh