# Weknora RAG Search

> Use when retrieving from or asking questions against a WeKnora knowledge base via the `weknora` CLI — and especially when unsure whether to use `chat`, `session ask`, or `search chunks` for a given goal.

- Skill: `tencent/weknora-rag-search` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tencent/weknora-rag-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencent/weknora-rag-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tencent (https://skillmd.com/u/tencent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencent/weknora-rag-search

---


# WeKnora — retrieval & RAG queries

**REQUIRED BACKGROUND:** read the `weknora-shared` skill first (auth, `--kb`
resolution, the JSON envelope, exit codes, streaming/NDJSON output).

WeKnora gives you several ways to "ask about a knowledge base." Picking the wrong
one wastes turns or returns the wrong shape. Use the decision table.

## Pick the command by your goal

| Your goal | Command | LLM synthesis? | Returns |
|---|---|---|---|
| Natural-language **answer** grounded in a KB | `chat "<q>" --kb <kb>` | yes | bounded answer events; `--reference` adds citations; `--verbose` adds execution detail |
| Answer via a **custom agent** (its own KB scope, tools, web search) | `session ask --agent <id> "<q>"` | yes (+ tools) | bounded answer events; `--reference` adds citations; `--verbose` adds execution detail |
| **Raw context chunks** to reason over yourself (no answer) | `search chunks "<q>" --kb <kb>` | no | ranked chunk list |
| Which **documents** match a keyword (title/filename) | `search docs "<q>" --kb <kb>` | no | document list |
| Find a **knowledge base** by name | `search kb "<q>"` | no | KB list |
| Find a past **session** by title | `search sessions "<q>"` | no | session list |

### The three decisions that matter

1. **Answer vs raw context.** Want a written answer → `chat` / `session ask`.
   Want chunks to feed into your *own* reasoning (e.g. you'll synthesize across
   sources) → `search chunks`. Don't call `chat` just to read source text.
2. **`chat` vs `session ask`.** `chat` = plain KB RAG Q&A. `session ask --agent
   <id>` = invoke a *configured custom agent* (it may scope its own KBs, call
   tools, do web search). If the user set up an agent for this, prefer it
   (`weknora agent list` to find ids); otherwise `chat`.
3. **One-shot vs multi-turn.** Both `chat` and `session ask` return a
   `data.session_id` in default JSON output. Pass `--session <id>` on the next
   call to continue the conversation. In NDJSON mode, read it from `init`.

## Safety / Gotchas

- `chat`, `search chunks`, `search docs` need a KB: pass `--kb <id-or-name>`, or
  set `WEKNORA_KB_ID`, or `weknora link` the directory (resolved in that order).
  If none resolves it's exit 1 (`local.kb_id_required`); a bad name is exit 1
  (`local.kb_not_found`). Resolve names with `weknora kb list` / `search kb`.
  (`search kb` / `search sessions` are tenant-wide and take no `--kb`.)
- `chat` / `session ask` return one buffered JSON envelope with answer
  events by default. Add `--reference` for indexed citations and `--verbose`
  for execution detail; use `--format ndjson` for raw events or `--format
  text` for the live human-readable projection.
- A stalled stream is not stopped by Ctrl-C (that just drops your local
  connection; the server keeps generating + billing). Stop it server-side:
  `weknora session stop <session-id> --message <message-id>` (session_id from
  `data.session_id`, or from `init` under `--format ndjson`).
  Re-attach to a stream with `weknora session resume <session-id>
  --message <message-id>`.
- `search chunks --limit` defaults to **8** (tuned for an LLM context window);
  the `search docs/kb/sessions` lists default to 30. Tune retrieval with
  `--vector-threshold` / `--keyword-threshold`, or `--no-vector`/`--no-keyword`
  to disable a channel. Details: `references/search-chunks.md`.

## Quick examples

```bash
# raw retrieval to reason over
weknora search chunks "retry backoff policy" --kb engineering --limit 12

# grounded answer (human transcript)
weknora chat "How do we handle retries?" --kb engineering --format text

# continue the conversation (session id from data.session_id above)
weknora chat "And the max attempts?" --kb engineering --session sess_abc

# answer via a custom agent
weknora session ask --agent ag_123 "Summarize this quarter's incidents"
```