---
title: Knowledge Q&A
description: Ask how your team works with venom ask, the console's Ask page or Slack, and get an answer cited from org memory, the team library, session summaries and your repo's docs.
section: reference
order: 160
audience: [user, operator, builder]
sources: [docs/knowledge-qa.md, cli/src/ask.ts, services/nodejs-cloud/lib/knowledge]
features: [reference.doc-knowledge-qa]
---

Ask a question about how your team works and get an answer with its sources. Three ways in, one set of sources:

| Way in | Sources | Who pays |
|---|---|---|
| `venom ask "<question>"` | Cloud sources your key may read, plus the markdown docs of the repository you are in | your key |
| Console, Ask page | Cloud sources only | an internal key owned by you, made on first use |
| Slack, `/venom ask <question>` | Cloud sources only, with your own view when your Slack user is linked | your linked key, else the Slack service key |

```bash
venom ask "how do we cut a release?"
venom ask --local-only "where is the retry policy documented?"   # calls nothing
```

## Sources {#sources}

| Source | What is searched | Rule |
|---|---|---|
| Org memory | Approved facts | The scope of the asker's key group. |
| Team library | Published prompts and skills, never drafts | The scope of the asker's key group. |
| Session summaries | Summaries that match the question | Only when the org collects them, and only for a member whose role can read logs. A shared or service key gets none. |
| Docs in your checkout | Tracked `*.md` files, split at headings | `venom ask` only. The best few passages go with the question for that one answer; `--cloud-only` sends none, `--local-only` calls nothing. |

The answer says when a source could not be used. Another organisation's data is never searched.

## How an answer is made {#how}

1. Candidates are read with the asker's permissions and ranked by BM25 (a word in the title counts three times).
2. If the org serves an embedding model, the top 16 are re-ranked by similarity blended with the keyword score. No vectors are stored.
3. At most 8 passages (1,400 characters each, 9,000 in all) go to the model as sources `S1`, `S2`, ..., with an instruction to answer only from them, cite them, and treat them as data, not instructions.
4. The model is the summary role of the gear (the request's, else the org's default), at most 700 output tokens, through the normal path: routing, filters, model access and budgets apply.
5. A question nothing matches is answered without a model call, at no cost.

## API {#api}

`POST /v1/knowledge/ask` with a client key, body `{question, gear?, local?: [{path, heading?, text}]}`, answers:

```json
{"object": "venom.knowledge.answer", "question": "...", "answer": "... [S1]",
 "sources": [{"id": "S1", "kind": "memory", "title": "...", "link": "/memory#<id>", "cited": true}],
 "mode": "keyword", "searched": {"memory": 12, "library": 4, "summaries": 3, "local": 0},
 "gear": "quick", "model": "...", "usage": {"prompt_tokens": 0, "completion_tokens": 0}}
```

Errors: `400` (no question, over 600 characters, a bad `local`), `404 gear_not_found`, `409 no_gear`. Admins can ask through `POST /api/admin/v1/knowledge/ask`. The generated reference is at `/docs/api/cloud`.

## Related

- [Glossary](/docs/reference/glossary.md)
- [Error codes](/docs/reference/errors.md)
