Architecture overview

knowledge is built around three pieces that each do one job :

• Ingestion job: builds and updates the knowledge base by collecting and processing the source data.
• API: exposes the knowledge base through a API
• MCP server: makes the knowledge available to coding agents through the Model Context Protocol (MCP).

Repository layout

The ingestion job and the API are two independent services, built into two images and deployed apart. They share no code — not a configuration module, not a utility package. What they do share is the Qdrant collections they agree on: the job writes them (ingestion/clients/vectordb.py), the API reads them (api/clients/vectordb.py), and the end-to-end suite runs both against one Qdrant so a drift between the two fails a test.

Each service has the same shape: general things at the root, and folders for the rest.

api/                          ingestion/
├── bin.py    entry point     ├── bin.py    entry point
├── main.py   the app         ├── main.py   the pipeline
├── config.py                 ├── config.py
├── logger.py                 ├── logger.py
├── routes.py                 ├── chunkers/    one per file type
├── schemas.py                │   ├── line_locator.py
├── services/  what it does   │   ├── markdown.py, javascript.py, …
│   ├── retrieval.py          ├── pipeline/    what the job does
│   └── security.py           │   ├── workspace_clone.py   fills the workspace
└── clients/   what it talks  │   ├── workspace_scanner.py files git tracks
    ├── llm.py     to         │   ├── change_detection.py  digests, what moved
    ├── embeddings.py         │   └── commit_history.py    commit history
    └── vectordb.py           └── clients/     what it talks to
                                  ├── embeddings.py
                                  └── vectordb.py

services/ holds what a service does, clients/ what it talks to, and pipeline/ the steps of one ingestion run.

Run them with python -m api.bin and python -m ingestion.bin.