# Knowledge protocol

> The retrieval ladder and the writing contract an agent follows over your collections: which GNO command answers which kind of question, what each rung returns and where it stops, and when a write is an edit, a capture, or a remember.

Section: Guides  
Canonical: https://gno.sh/docs/protocol  
Markdown: https://gno.sh/docs/protocol.md

A knowledge protocol is the routing contract between an agent and your indexed collections: which command answers which kind of question, in which order to try them, and what a write is allowed to be. This page is the generalized contract. The [gno agents](https://gno.sh/docs/agents-install) block carries a 1,491-character version of it into each harness's global instruction file; the [gno skill](https://gno.sh/docs/skills) carries the workflows and recipes. Everything here applies to any collection layout: the protocol names commands, never folders.

## Ground rules

- **Source files are the truth.** The index is derived, machine-local, and disposable; a rebuild changes no source.
- **Scope first.** Pass `--collection` before reformulating a query. Most misses are scope misses.
- **Cite by URI.** Retrieved material is cited by its `gno://collection/path` identifier, with a line span when quoting, never by a paraphrased filename.
- **A question is read-only.** Answering never writes; a write needs an explicit request or a documented rule.

## The retrieval ladder

Seven rungs, cheapest and most exact first. Each one is a different question shape, and each stops at a stated boundary.

| Question shape                                           | Command                                             | Returns                                                       |
| -------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------- |
| 1. Exact term, identifier, quote, filename, error string | `gno search "<text>"`                               | BM25 hits with URIs and matching spans                        |
| 2. What do we know or believe about X                    | `gno recall "<query>" --scope <scope>`              | Current facts only, cited, under a budget, with a receipt     |
| 3. An entity or a document you know exists               | `gno query "<question>" --fast -n 10`               | Hybrid ranking over documents, fast preset                    |
| 4. Evidence across several documents for one goal        | `gno context build "<goal>" --budget 12000`         | A Context Capsule: exact spans, hashes, budget, declared gaps |
| 5. What changed, what differs, what depends on this      | `gno changes`, `gno diff <doc>`, `gno impact <doc>` | Bounded change history and dependency projections             |
| 6. A generated factual answer                            | `gno ask "<question>" --verify`                     | A cited answer, or an abstention                              |
| 7. A document you expected is missing from results       | `gno query diagnose "<query>" --target <doc>`       | The stage at which the target dropped out                     |

### 1. Exact search

`gno search` is lexical: a term, an identifier, a quoted phrase, an error message. It runs without models and returns the matching spans with their URIs. When the wording is known, this rung settles the question and nothing further runs.

### 2. Recall

`gno recall` reads memory-managed collections only and returns current facts: a fact replaced by a supersede is excluded in the query itself. The budget defaults to 8 facts under 512 estimated tokens; each fact carries its `gno://` URI, scopes, caller, session, and content hash. An empty result carries a hint naming the write path, so a fresh agent learns `remember` from the empty read. Recall runs the lexical leg always and adds the vector leg when the collection's embedding model is already cached; the response reports `mode: lexical` or `hybrid` with the reason, and it never downloads a model. Lexical-only recall matches every query term, so a question-shaped query can miss a fact the vector leg would find; embed the memory collection to close that gap. The full contract is on the [memory](https://gno.sh/docs/memory) page.

### 3. Query

`gno query` fuses lexical and semantic retrieval over documents. `--fast` skips query expansion, graph expansion, and reranking, which is the right trade when the entity or document is known and ranking quality matters less than latency. Drop `--fast` for a vaguer question. Structured syntax, tag, date, and author filters, backlinks, and similarity are in the [query syntax](https://gno.sh/docs/syntax) reference.

### 4. Context build

`gno context build` compiles a Context Capsule for one goal: exact source spans with hashes, deduplicated under one token budget, with every retrieval gap declared in the Capsule itself. It is the handoff for a decision that rests on more than one document, and it is the input to a verified answer. See [Context Capsules](https://gno.sh/docs/context-capsules).

### 5. Changes, diff, impact

Change and dependency questions are a different shape from content questions. `gno changes` lists what moved in a window, `gno diff` shows how one document changed, and `gno impact` projects which documents a change may affect, all from GNO's bounded, metadata-first history. See [Knowledge Delta](https://gno.sh/docs/knowledge-delta).

### 6. Verified ask

`gno ask --verify` generates an answer against one closed Capsule and classifies each substantive claim against its supporting spans. Complete support returns the answer with citations; anything less withholds the draft and reports the failing claim. Abstention is a valid result of this rung, and an agent treats it as one.

### 7. Diagnose before grep

When a document you know exists is absent from results, `gno query diagnose` reports stage by stage whether the target appeared in lexical retrieval, vector retrieval, fusion, graph expansion, and reranking, so a candidate-generation miss is told apart from a ranking miss. Re-check the collection scope in the same step. A scoped grep or a direct file read is the fallback after that diagnosis, not before it.

## The writing contract

Retrieve first. A write starts from what already exists, and the three write paths are distinct operations, chosen by what kind of thing is being written.

| The thing being written                                | Path         | How                                                                       |
| ------------------------------------------------------ | ------------ | ------------------------------------------------------------------------- |
| An existing canonical note that is wrong or incomplete | **edit**     | Change the source file directly: editor, Web UI, `PUT /api/docs/:id`      |
| A genuinely new note: a meeting, an idea, a source     | **capture**  | `gno capture` with collection, title or path, source kind, and provenance |
| A standalone fact that may change later                | **remember** | `gno remember "<fact>" --scope <scope>`, then `--add` or `--supersede`    |

- **Capture is creation, never an update API.** It creates a new document with provenance. Its receipt proves the mechanical write and nothing more: cross-links, index notes, and hub updates that your own conventions require are separate edits.
- **Remember proposes; the agent decides.** A fact is one or two sentences, at most 4096 bytes; longer text is a document and belongs in capture. With no flag, `remember` reports likely matches from the scope and writes nothing. `--add` stores it beside them; `--supersede <uri> --predecessor-hash <hash>` replaces one, and the hash check refuses a stale predecessor. Both values come from a recall.
- **Recalled spans are context, not new facts.** Every recall carries a content-free receipt; passing it back as `--receipt` lets `remember` refuse a recalled span replayed as a new fact. A submission that declares a `gno://` origin is refused for the same reason. The fence is exact span plus declared origin: a paraphrase presented without receipt or origin is stored as an original fact, so the receipt is part of the agent's contract, not a security boundary.
- **After a write: reindex, then verify.** Reindex the affected collection and confirm the title and one distinctive claim with `gno search` or `gno get`. A write that cannot be retrieved is not finished.

## Configuring the protocol for your setup

The commands are fixed; the knowledge they run over is yours to shape.

- **Collections** are the scope boundary the ladder climbs within: one per source root, each with its own matching, context hints, and egress policy. See [configuration](https://gno.sh/docs/configuration).
- **Memory scopes** are strings you choose (a project, a team, a domain), one to eight per call, up to 64 characters each. Recall and remember both require them; a call without scopes is refused. One collection marked `memoryManaged: true` holds the facts.
- **Harnesses** receive the block by detection or by `--target`; extra config directories by `--extra-dir`. Your own conventions, naming rules, and filing ceremonies live outside the markers, in the same file, and the installer leaves them byte-identical.
- **Context hints** attached globally, per collection, or per path prefix steer ranking. They guide retrieval; they are never presented as evidence.

## Where the protocol stops

- It is delivered by instruction text and a skill. There is no per-prompt hook: the agent follows the ladder because its instructions say so, and a behavioral check after install is a manual practice.
- Nothing writes on its own. Every edit, capture, and remember is an explicit call by the agent; recall injected into a turn by a harness adapter stores nothing.
- Verification is per claim, not per fact. `gno ask --verify` checks an answer against a Capsule; it does not check whether the source documents are themselves true.
- The ladder is a default order, not a gate. An agent that already knows the wording starts at rung 1 and stops; one asked for a decision starts at rung 4.