gno agents install keeps one versioned, marker-managed GNO protocol block in the global instruction file of every harness on the machine: which file each harness reads, what the markers and the version stamp guarantee, and what the block teaches.
An agent uses GNO when its instruction file tells it how, and a hand-pasted paragraph falls behind the CLI it describes. gno agents install writes one compact protocol block, bounded by stable markers and stamped with a version and a content hash, into the global (user-scope) instruction file of every harness it detects. verify compares the stamp against the installed release, update replaces an older block in place in files that already hold one, and uninstall removes block and markers. Everything outside the markers is yours and stays byte-identical.
The block is a knowledge protocol you configure, not a note-taking convention: it names the commands and their order, and it names no collection, no path, and no folder layout. Which collections exist, which scopes memory uses, and which harnesses receive the block are your settings.
gno agents install # every harness detected on this machine
gno agents verify # deterministic per-target checks
gno agents update # refresh existing blocks after a gno upgrade
gno agents uninstall # remove block and markers
# every verb: --target <harness|all>, --extra-dir <path> (repeatable), --json
# install, update, uninstall: --dry-run prints a unified diff and writes nothingDetection is the presence of the harness's standard config directory. Only documented locations are discovered; nonstandard and multi-instance layouts are served by --extra-dir.
| Harness | Target id | Global instruction file | Detected by | Notes |
|---|---|---|---|---|
| Claude Code | claude | ~/.claude/CLAUDE.md | ~/.claude | Honors CLAUDE_CONFIG_DIR when set. |
| Codex | codex | ~/.codex/AGENTS.md | ~/.codex | Honors CODEX_HOME when set. |
| Cursor Agent | cursor | ~/AGENTS.md | ~/.cursor | The CLI discovers AGENTS.md walking from the working directory toward home. |
| OpenCode | opencode | ~/.config/opencode/AGENTS.md | ~/.config/opencode | |
| Grok Build | grok | imports the Claude global file | ~/.grok | grok inspect shows the import; the installer reports covered via claude and writes no second block. |
| Hermes Agent | hermes | ~/.hermes/SOUL.md | ~/.hermes | A marker-managed block inside your own SOUL.md. |
| OpenClaw | openclaw | ~/.openclaw/workspace/AGENTS.md | ~/.openclaw/workspace | Existing workspaces only. |
The Hermes memory provider and OpenClaw memory plugin are separate from this block. See Memory: adapters.
<!-- gno:agents:begin -->
<!-- gno-agents block v5 sha256:<16 hex> — managed by `gno agents`; manual edits inside the markers are overwritten -->
...ladder + writing contract...
<!-- gno:agents:end --><!-- gno:agents:begin --> and <!-- gno:agents:end --> never change once shipped, so a block installed by any release is found by every later one.gno agents verify is deterministic: exactly one marker block per target, stamp version and hash equal to the installed release. Per target it reports one of ok, outdated (older version or a body that no longer matches its hash), missing (no file or no block), malformed, error (the file could not be read), covered (another target owns the same file, via an import chain or a shared real file), or not-detected. Exit code 1 on any outdated, missing, or malformed target; exit 2 when the only failures are unreadable files. Install and update report per-target actions the same way: install, update, current, covered, not-detected, error; update reports a file without a block as absent and leaves it untouched, and uninstall reports remove or absent.
verify checks the file, not how the agent behaves. To confirm an agent picked up the block, start a fresh session in each harness and ask it to describe its loaded knowledge protocol. It should describe the GNO retrieval ladder.
<file>.gno-agents.bak.<timestamp> with the same permission mode; the new content lands through a temp file and an atomic rename, so a failed write leaves the live file untouched.manualBlock in --json). Other targets proceed.covered via <target> (same file).install creates the instruction file when a detected harness lacks one; it never creates harness directories. update never adds a block or creates a file.Several config directories of one harness on one machine are served by the explicit, repeatable flag; discovery never guesses at them. Inside an extra directory the installer manages the first existing of CLAUDE.md, AGENTS.md, SOUL.md, and creates AGENTS.md when none exists. The directory itself must exist.
gno agents install \
--extra-dir ~/.claude-instances/work-cli \
--extra-dir ~/.claude-instances/sub2-cliThe block is the routing contract; the workflows stay in the gno skill. Version 5 teaches the retrieval ladder, scoped to a collection first:
gno search. In the block's words: “A question, or a name or topic taken from it, is not exact text: use rung 3”gno recall "<query>" --scope <scope>, current facts, citedgno query "<question>" --fast -n 10 (keyword and semantic)gno query "<question>" -n 10, which adds query expansion and rerankinggno context build "<goal>" --budget 12000gno changes, gno diff, gno impactgno ask "<question>" --verify (abstention is valid)gno query diagnose with a target, and a scope re-check, before any grepThen the writing contract in four sentences: retrieve first, since a question alone is read-only; edit an existing canonical note in its source file; gno capture creates genuinely new notes and is never an update API; a fact that may change goes through gno remember, which proposes, with the --add or --supersede <uri> --predecessor-hash <hash> decision taken from a recall. Recalled spans are context, not new facts, so the recall receipt travels back as --receipt. After writes: reindex the collection and verify retrieval. Cite with gno:// URIs. The block closes with one static pointer: load /gno when the skill is installed, otherwise run gno skill install --scope user first.
The generalized version of that contract, with what each rung returns and where each one stops, is the knowledge protocol page.
When a GNO upgrade ships a newer block, verify reports outdated and update replaces the block in place, backup first. update only touches files that already contain the block; a file without one is reported absent with a hint to run gno agents install, and no file is created.
Version 5 narrows the first rung: gno search is for a term, identifier, quote, or error you already have verbatim, and a question, or a name or topic taken from it, goes to gno query --fast. The gno skill and the MCP gno_search description carry the same wording. Run gno agents update and gno skill install --force after upgrading to pick it up.
The installer is per machine: GNO's index and database are machine-local derived state and never sync. Instruction files may be synced or repo-managed (dotfiles, a private instructions repo, symlink schemes); the installer writes through symlinks and its marker-managed block survives file-level sync. Run gno agents verify on each machine after syncing.
The protocol block teaches retrieval over your curated index. It does not import or watch agent conversations, and no hook or schedule is installed. Session history is a separate archive with its own config and index, manual by default; its Claude Code hook and daemon schedule are a separate, explicit opt-in. Imported turns are evidence, never promoted to remember facts automatically. Read the session archive guide.