Install GNO

Configuration

Configure GNO via user config or a portable project profile, manage collections, and pick the right model preset.

Change collections and presets from the CLI or Web UI. The YAML file is for defaults the UI does not cover. User config is ~/.config/gno/config/index.yml (Windows: %APPDATA%\gno\config\index.yml). gno doctor prints the resolved paths.

Config file location

Run gno doctor to see the resolved paths for your machine.

Index database busy timeout

busyTimeoutMs sets SQLite busy_timeout for the index database. Integer milliseconds from 1000 to 600000; default 60000. gno doctor reports the live PRAGMA busy_timeout value. Raise it for long embedding passes on slow disks.

busyTimeoutMs: 60000

Project-local retrieval profiles

A repository can commit a portable .gno/index.yml profile that describes one collection, its contexts and content types, and request-local project-affinity defaults. A profile is optional: repos without one keep the normal user config and current-directory behavior.

schemaVersion: "1.0"
collection:
  name: project-docs
  root: docs
  include: ["**/*.md"]
  exclude: [node_modules, .git]
contexts:
  - file: AGENTS.md
contentTypes:
  people:
    prefixes: [people]
    preset: person
affinityDefaults:
  enabled: true
  contribution: 0.03

Paths are repository-relative and cannot escape the selected project root. The schema is closed: unknown keys, absolute paths, traversal, environment expansion, Windows-reserved names, unsafe glob syntax, duplicate IDs, and references to GNO runtime files fail validation. Likely secret context paths such as .env, private keys, and credentials are rejected. Context files must be regular UTF-8 files no larger than 64 KiB; the profile itself is capped at 1 MiB. GNO also excludes .gno from the declared collection. Profile excludes containing glob metacharacters are real Bun globs; plain values retain directory-component matching. Multiple include globs preserve literal commas and bracket classes. Brace alternatives are rejected; express their branches as separate include or exclude entries.

gno profile check
gno profile show
gno profile diff
gno profile apply

The first three commands are read-only. apply takes a canonical, cross-process config lock and additively creates or updates only profile-declared config and store projections; it does not index documents or delete unrelated DB-only collections, documents, contexts, omitted content types, or index state. Multiple contexts for one collection are preserved. A timestamp-free local binding records the canonical profile path, collection, and fingerprint so removal-only edits remain observable without exposing machine paths in public receipts. The tracked profile is never rewritten. Config, data, database, model cache, selected file-backed models, apply receipt, and lock state must stay in the user’s external GNO runtime directories, never inside the repository. Overlap fails before mutation. Commit the portable profile and referenced guidance, not databases, model files, caches, locks, receipts, or secrets.

Collections

Each collection is a named source of documents. Collections have their own include/exclude rules and can optionally override model presets.

# Add a collection
gno collection add ~/notes --name notes

# Add with a glob pattern
gno collection add ~/code --name code --pattern "**/*.{ts,md}"

# List collections
gno collection list

# Remove a collection
gno collection remove notes

Collection egress policy

Every collection has one effective boundary: local_only, lan, or remote. An omitted value fails closed to local_only. Collections created before this policy was introduced keep their indexed documents and lexical/vector data, but report legacy_default provenance; newly synchronized collections without an explicit value report config_default. Neither default permits LAN or remote transfer. Egress policy is distinct from source availability (below).

gno collection policy get notes
gno collection policy check --action remote_inference \
  --destination remote --content-class source -c notes \
  --authenticated --authorized --explain-egress
gno collection policy set notes remote --confirm-relaxation 0
gno collection policy set notes local_only

Authentication, write permission, and collection policy are independent gates. Mixed or derived evidence uses the most restrictive participating collection. Relaxation requires the current single-use policy revision; tightening invalidates resident sessions, active streams, queued jobs, and saved authorization state. Tightening blocks future GNO-controlled transfers but cannot recall data already uploaded. Revoke or expire supported private links separately; public-space deletion is not yet self-service, so request remote takedown. Encrypted gno.sh artifacts remain client-encrypted; gno.sh never receives the passphrase and cannot decrypt or recover them.

Source availability

collections[].sourceAvailability is optional and independent of egressPolicy. Exact values: any (default) or local. Availability controls whether source content may be materialized during indexing; egress controls where derived data may travel. There is no separate public knob beyond these two modes.

Sync receipts distinguish eligible files, CLOUD_PLACEHOLDER / CLOUD_PARTIAL skips (not conversion errors), DATALESS_DIRECTORY, and fail-closed SOURCE_AVAILABILITY_* codes. Previously indexed descendants under unproven prefixes stay searchable rather than being treated as proven deletions.

Evidence scope: Google Drive, iCloud Drive, and OneDrive only for the tested macOS/provider configuration; OneDrive only for both validated immediate SharePoint library roots. No Windows or Linux cloud- filesystem guarantee. Metadata or provider bookkeeping may still occur. GNO local mode does not pin, evict, or download as product behavior.

On the controlled 5,000-file all-local Markdown corpus (2 warmups, 9 interleaved samples per lane), current production anymeasured -1.1280% versus the pre-implementation production walker and hierarchical local added 1.1841% median traversal overhead versus current any. These are fixture-scoped scan results, not provider-latency or zero-network-activity guarantees.

collections:
  - name: drive-notes
    path: /Users/you/Library/CloudStorage/GoogleDrive-…/My Drive/notes
    pattern: "**/*"
    sourceAvailability: local
    egressPolicy: local_only

File and export adapters

GNO streams user-controlled exports into separate searchable records: one JSONL object, mail message, calendar event, transcript cue, or browser item at a time. Each record retains its real export path, exact locator, dates, people, available thread/event/session identity, attachment inventory, and anchors across search, get, Ask, and Context Capsules.

collections:
  - name: exports
    path: /Users/me/exports
    pattern: "**/*"
    include: [.jsonl, .eml, .mbox, .ics, .vtt, .srt, .browser-export]
    recordAdapters:
      jsonl:
        fieldMapping:
          id: /external_id
          body: /payload/text
          participants: /participants
          dateFields:
            created: /created_at

Reimport with the same stable identity updates in place. Only a fully valid complete snapshot can deactivate disappeared records; malformed, truncated, or cap-limited snapshots preserve unseen records. Defaults cap a container at 100 MiB, one record at 2 million canonical characters, a snapshot at 50 million characters or 100,000 records, retained failures at 1,000, and adapter iteration at 60 seconds. Calendar recurrence emits at most 64 bounded local anchors. Partial imports always produce a visible warning; verbose output adds stable codes, locators, retryability, and redacted messages.

JSONL updates preserve identity only when a configured mapping or a conventional id field supplies one. Without either, GNO derives identity from canonical row content, so editing a row appears as one removed record plus one added record rather than an in-place update.

Export adapters never authenticate to mail/calendar/browser accounts, inspect live browser profiles, cookies, passwords, or sessions, fetch URLs or attachments, execute embedded content, or unpack archives. HTML becomes inert text. In structured results, source.relPath is the real export container; use the unique uri or docid to retrieve one record. The bounded record.adapter object identifies the exact adapter version and configuration fingerprint. .gno/records/ is reserved for virtual record identities and never walked as physical collection content.

Exclusions

Add an exclude array to a collection to skip files and directories:

collections:
  notes:
    path: ~/notes
    exclude:
      - node_modules
      - .git
      - "**/*.tmp"

Project-aware retrieval

projectAffinity.enabled defaults to true and controls only the user-configured cwd fallback. projectAffinity.contribution defaults to and is capped at 0.03. For a local CLI request, repeatable explicit --project-root values win; otherwise the nearest valid.gno/index.yml supplies its canonical project root and request-local affinity settings. Missing or invalid profiles fall back to the cwd-derived root and user default. An explicit root or valid profile therefore still applies when the user-config fallback is disabled. --no-project-affinity disables all three sources for that request. Explicit roots replace inferred roots, duplicate or overlapping roots never stack, and all auxiliary scoring shares one ±0.08 cap. Remote hints are a separate untrusted input: they never trigger local profile or filesystem discovery and currently contribute zero affinity. Collection, tag, date, exclude, and egress filters remain hard.

Model presets

GNO ships four built-in presets. Switch with one command; the first pull downloads the model files and caches them locally.

All four built-in presets use Qwen3-Embedding-0.6B-GGUF for embeddings. Model cache size varies with selected artifacts, quantization, and files already present; the preset names are not measured clean-install size claims.

gno models use balanced
gno models pull
gno models list

Content types

contentTypes is an optional schema-lite layer for second-brain pages. Empty or absent rules keep legacy behavior. When a rule matches, GNO indexes canonical contentType metadata alongside normal category filters.

contentTypes:
  - id: person
    prefixes: [people/, contacts/]
    preset: person
  - id: meeting
    prefixes: [meetings/]
    preset: meeting
    searchBoost: 1.15
    temporal: true

Frontmatter type becomes canonical only when it matches a configured content type ID. Otherwise it remains category metadata. A canonical configured frontmatter type wins over longest-prefix matching; only one rule applies, so overlapping prefixes cannot stack.graphHints types projected graph relationships.

searchBoost accepts 0.5 to 2; omitted or 1 is exactly neutral. One matched rule contributes at most ±0.05 and composes once with trusted local project affinity under a shared ±0.08 auxiliary cap. BM25 and vector boosts only adjust already-selected candidates: they never widen candidate retrieval or defer minScore. Hybrid applies the composed auxiliary score to normalized fusion before rerank blending, leaving rerank order and lexical top-hit protection authoritative. Final scores stay in 0..1. No boost bypasses collection, tag, date, category, author, or exclude filters.

Query and Ask --explain receipts show the base score, factor, bounded contribution, combined cap, final score, rule source, and full ranking-rules fingerprint when a non-neutral rule is active. Status exposes only rule IDs, normalized factors, and that fingerprint; configured prefixes stay private. Boost-only config edits change the ranking fingerprint without requiring document conversion or vector rebuilding.

Per-collection model overrides

Override embed, rerank, expand, or generation models per collection. Example: a code collection on a code embedding model, a notes collection on the preset embed model.

collections:
  code:
    path: ~/code
    models:
      embed: nomic-ai/nomic-embed-code-v1.5

Remote model servers

Point GNO at an OpenAI-compatible server (Ollama, LM Studio, vLLM) running on another machine. Remote roles receive the query, chunk, or retrieved answer context sent to that role; they do not receive the corpus as a remotely mounted index.

models:
  activePreset: remote
  presets:
    - id: remote
      name: Remote GPU Server
      embed: http://192.168.1.100:8081/v1/embeddings#qwen3-embedding-0.6b
      rerank: http://192.168.1.100:8082/v1/completions#qwen3-reranker
      expand: http://192.168.1.100:8083/v1/chat/completions#gno-expand
      gen: http://192.168.1.100:8083/v1/chat/completions#qwen3-4b

Local model runtime

GNO uses node-llama-cpp for local GGUF models. The default path uses prebuilt backends only; source builds are opt-in so normal indexing does not unexpectedly require local compiler toolchains.