Knowledge Q&A
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.
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 |
venom ask "how do we cut a release?"
venom ask --local-only "where is the retry policy documented?" # calls nothingSources
| 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
- Candidates are read with the asker's permissions and ranked by BM25 (a word in the title counts three times).
- If the org serves an embedding model, the top 16 are re-ranked by similarity blended with the keyword score. No vectors are stored.
- 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. - 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.
- A question nothing matches is answered without a model call, at no cost.
API
POST /v1/knowledge/ask with a client key, body {question, gear?, local?: [{path, heading?, text}]}, answers:
{"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.