# Method & delivery Knowledge injection has two independent knobs: * **`method`** — how the daemon retrieves: `bm25` (lexical), `vector` (semantic), or `none` (no daemon-side retrieval; the agent fetches knowledge itself). * **`delivery`** — how retrieved knowledge reaches the agent: `prompt`, `file`, `browse`, `search`, or `none`. They appear on a pipeline's [`knowledge:` block](/pipelines/config#knowledge) (or `defaults.knowledge` in `daemon.yaml`). The one-shot `/ask` endpoint and `bento ask` take `method` plus a `granularity` (they always return results to the caller, so they have no delivery axis — see [On `bento ask`](#on-bento-ask)). ```yaml knowledge: method: bm25 delivery: prompt # composable: prompt+search filter: categories: [conventions] ``` Defaults are `method: bm25`, `delivery: prompt`. ## Where content lands Two channels, fixed rule: * **System prompt** — delivery manifests (the browse listing, mount paths) and the delivery's default instruction. * **User message** — retrieved `` excerpts, and custom `instructions` when set. Setting `instructions` replaces the default system instruction. ## Method ### `bm25` (default) The trigger prompt is rewritten into a short search query (see [rewrite](/knowledge-base/config#rewrite)), qmd runs BM25 retrieval over the indexed sources, and the results feed the delivery. `topK` sets results per source, `maxTokens` caps the injection budget, `filter` drops chunks from non-matching docs after retrieval. Requires qmd installed and knowledge sources discovered. ### `vector` Same as `bm25` but retrieval uses qmd's vector search. Requires embeddings (`qmd embed`); errors loudly when missing. ### `none` The daemon retrieves nothing. Pair with a delivery the agent drives itself (`browse`, `search`) or with `file` to mount the whole corpus. ## Delivery ### `prompt` — retrieved excerpts inlined (default) The retrieved chunks land in the user message as `` blocks: ```xml Feature branches PR into develop; develop merges to main for release… ``` The run's retrieve task records method, query, and injected counts — visible in [`bento trace`](/pipelines/traces). Requires a retrieving method (`bm25`/`vector`). ### `file` — results on the filesystem `file` has two flavors, picked by `method`: * **Retrieved subset** (`method: bm25`/`vector`) — the retrieved `` blocks are written to `.bento/retrieved-knowledge.md` in the run checkout instead of inlined; the agent reads that one file. Keeps large result sets out of the prompt. `filter` applies. Works on host, docker, and podman. * **Whole corpus** (`method: none`) — knowledge dirs are bind-mounted read-only at `/knowledge/` (`/knowledge/wiki`, …), with `/knowledge/index.tsv` (one tab-separated row per doc: path, title, category, tags, summary) and `/knowledge/README.md` (the layout). The agent greps the index, then reads files with its normal tools. docker/podman only; `filter` is a config error (whole dirs are mounted). ### `browse` — listing, agent reads on demand The system prompt carries the filtered doc listing, grouped by URI scheme: ``` wiki:// - wiki://git-workflow — Git Workflow [git, process] recipe:// - recipe://setup-knowledge-base — Setting Up the Knowledge Base [knowledge, setup] ``` The agent reads whole docs via MCP resources when relevant. Use when docs are few enough to pick from a list and whole-doc context beats excerpts. Requires discovered docs and a local sandbox backend — the daemon's MCP endpoint is loopback-only, so remote backends like daytona can't reach it. Pairs with `method: none`. ### `search` — agent's MCP tool No content is injected. The system prompt nudges the agent toward the `ask_knowledge` MCP tool: > A team knowledge base is available through your MCP tools. Search it with the `ask_knowledge` tool before deciding questions of convention, architecture, or process. The agent searches when it decides it needs to. Requires the `ask_knowledge` tool (qmd installed, sources configured) and a local sandbox backend (same loopback constraint as `browse`). Pairs with `method: none`. ### `none` Nothing is injected. Use it on a pipeline to opt out of a delivery set by `defaults.knowledge`; with no `knowledge:` block and no defaults, runs get no injection anyway. ## Composing with search `prompt`, `file`, and `browse` compose with `search` as `prompt+search`, `file+search`, and `browse+search`: the primary grounds the agent up front, and `ask_knowledge` stays available as the escape hatch when that content doesn't cover the question. ```yaml knowledge: method: bm25 delivery: prompt+search topK: 3 ``` A composite run must satisfy both deliveries' prerequisites. `none` does not compose, and a delivery has at most one primary. ## Failure semantics A delivery whose prerequisites are missing fails the run at dispatch rather than spawning an agent without them. The error names the delivery, the missing capability, and the fix: ``` knowledge delivery "file" with method "none" mounts the whole corpus and requires host bind-mounts — sandbox backend is "daytona"; set sandbox.backend to docker or podman, or set a retrieval method ``` | Delivery | Checked at dispatch | |------|---------------------| | `search` | `ask_knowledge` registered; local sandbox backend; sandbox MCP bundle issued | | `browse` | docs discovered; local sandbox backend; sandbox MCP bundle issued | | `file` (`method: none`) | docker/podman backend; no `filter` set | | `file` (subset) | not daytona (the results file is written into the run checkout) | | `prompt` | checked at the retrieve step, not dispatch — unavailable retrieval errors the task and the run continues without context | ## On `bento ask` `bento ask` and `/ask` take `--method` (`bm25`, `vector`, `none`) and `--granularity` (`chunks` default, or `docs` to inline whole filtered docs — there is no MCP session to read them through). `--tag`, `--category`, `--top-k`, and `--instructions` mirror the pipeline fields. ```bash bento ask "how do we test the daemon" --granularity docs --category conventions bento ask "branch rules" --method bm25 --tag git --top-k 3 ```