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.

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 block carries a 1,491-character version of it into each harness's global instruction file; the gno skill 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.

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 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 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.

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.

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.

• 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.
• 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.