Installation, search, models, agents, and publishing.

GNO is a local knowledge workspace that indexes Markdown, PDF, Word, Excel, and PowerPoint, and makes them searchable with gno ask --answer / --verify, citing local passages. The corpus and index stay on your machine; built-in models run locally, while configured HTTP model roles and optional gno.sh publishing are explicit network boundaries.

Install via Bun with bun install -g @gmickel/gno. On macOS, vector search requires Homebrew SQLite (brew install sqlite3). Run gno doctor to verify your installation and embedding freshness, or launch gno serve for a guided first-run setup in the browser. Published packages are smoke-tested from the npm tarball with bun run test:package.

Yes. The current support target is windows-x64. The CLI path works via Bun/global install, and the desktop beta now ships as a packaged Windows zip on GitHub Releases. Windows arm64 is not supported yet.

Yes. After install, run gno serve and open localhost:3000. The dashboard walks you through adding a folder, choosing a speed-vs-quality preset, indexing, and proving local lexical retrieval. Semantic readiness stays separate and can remain pending while models download or embeddings run.

Run gno doctor or inspect gno status --json. GNO derives a bounded term from each indexed collection and proves that local lexical search returns the expected document; it does not mark readiness green just because files, an index, or models exist. The same activation result appears in /api/status and the Web Health Center. /api/health only proves the server process is alive. Semantic readiness is independent. For MCP, use the explicit read-only verification action on the Web Connectors page; installed skill runtimes remain unverifiable because GNO cannot prove the client loaded them.

Run gno doctor and check the embedding-fingerprint result. It reports the current fingerprint, pending or stale chunks, legacy vectors, and mixed fingerprint groups. Run gno embed first; if stale or mixed vectors remain, run gno embed --force. Both embed paths retry transient chunk failures inside the same run.

Yes. Run gno daemon for headless continuous indexing and a resident MCP endpoint at 127.0.0.1:3000/mcp — same watch, sync, and embed runtime as gno serve, no browser. Local models load on demand, can be reused during their idle grace period, then retire until needed again. Exact paths use content hashing; atomic-save and directory events use bounded failure-safe reconciliation. For background lifecycle, gno daemon --detach self-spawns and exits 0; gno daemon --status and gno daemon --stop give you first-class control without nohup, launchd, or systemd.

Restoring an unchanged file at its prior URI reactivates its indexed identity and records a change. Unchanged chunks and embedding inputs can reuse existing work. A changed title, model, or other embedding input needs the matching new embeddings; run gno doctor to inspect freshness and gno embed to resume pending work.

GNO indexes Markdown (.md) with frontmatter extraction, PDF (.pdf), Microsoft Word (.docx), Excel (.xlsx), PowerPoint (.pptx), and plain text files. It also imports portable JSONL, EML/MBOX mail, ICS calendar, WebVTT/SRT transcripts, explicitly configured JSON/text transcripts, and explicit browser bookmark/history exports as independently searchable read-only records. These are local file imports: no live account, OAuth, network fetch, archive unpacking, or attachment execution. Indexed-document detection covers English, German, French, Italian, Chinese, Japanese, and Korean. A separate 34-language query classifier selects expansion prompts; it is not a document detector or a retrieval-quality claim.

Not in place. PDF/DOCX/PPTX/XLSX source files stay read-only. PDFs open as native rendered pages with selectable text, zoom, fit modes, Download original, and an extracted-text toggle; the other converted formats remain viewable as indexed content. If you want to edit the content, use “Create editable copy” to generate a markdown note with source provenance.

Not by default. The corpus, index, and built-in models stay on your machine with zero telemetry and can work offline once models are cached. A configured HTTP model endpoint receives the text needed for its role, and optional gno.sh publishing receives only the artifact you explicitly export and upload.

Yes. Point GNO at your Obsidian vault directory and it indexes everything. GNO understands wiki links ([[note]]), frontmatter tags, and can discover semantic connections between notes that Obsidian’s built-in search misses. For editable notes, rename and same-collection move can preview and atomically rewrite supported wiki and Markdown references; ambiguous or unsupported plans fail closed. GNO adds BM25+vector search, cited answers, and a knowledge graph on top of the vault.

Obsidian still wins on plugins, Canvas, and Excalidraw. GNO covers search, browse tree, graph, safe editing, cited answers, and agent access. Choose on that split.

gno search matches keywords without loading a model. gno vsearch uses meaning-based search; gno query combines keyword and vector candidates with optional expansion and reranking. Semantic latency depends on your hardware, corpus, enabled stages, and model load state. First use and use after idle retirement include a cold model load.

No. Local reranking sizes its context to the prepared inputs where supported, with a safe native-auto fallback. Allocation and timing gains depend on the backend and workload; a smaller context is not a whole-device memory guarantee or a fix for every native failure. Backend upgrades can change scores and ordering. See How search works for the measured evidence and limits.

Use gno ask "your question" --answer for the existing cited-answer path. Use gno ask "your question" --verify when you want GNO to build a closed Context Capsule, classify each substantive claim as supported, contradicted, insufficient, or uncertain, and withhold the draft unless support reaches 100%. Built-in models need no cloud API; configured HTTP model roles receive the text required for their role.

No. Verified Ask checks a generated draft only against the exact evidence retained in its local Context Capsule. It binds verdicts to evidence IDs, line ranges, and hashes, reports stale or missing evidence and verifier degradation, and abstains when support is incomplete. It does not prove claims beyond the supplied corpus or guarantee that the corpus itself is true.

Yes. Use --collection or -c, for example gno search "term" -c notes. You can also filter by tags (--tags-any, --tags-all), dates (--since, --until), and exclude specific documents (--exclude). Supported filters apply before candidate limits. Empty or fewer-than-requested matches are valid; they do not mean vector search failed. Vector failure or lexical fallback is reported separately.

GNO supports multi-line query documents using term: (exact keywords), intent: (semantic intent steering), and hyde: (hypothetical document passages). These give you explicit control over the retrieval pipeline for complex queries.

On macOS and Linux the default is ~/.config/gno/config/index.yml. On Windows it lives under %APPDATA%\gno\config\index.yml. Run gno doctor to see the exact resolved paths for your machine.

Use gno collection add path --name name for each folder, then run gno update to index them all. You can add Obsidian vaults, project docs, research folders, and code repos — any directory on your machine.

Yes. Capture and Quick Capture include presets for source summaries, decisions, original ideas, people, company/projects, and meetings. The second-brain presets use a synthesis/timeline pattern: current assessment above ## Timeline, dated evidence or raw notes below it. Optional contentTypes rules in index.yml map configured frontmatter type values or folder prefixes to canonical contentType metadata. A searchBoost from 0.5 to 2 can add a bounded -0.05..+0.05 soft ranking contribution; it never widens retrieval, defers minScore, creates candidates, or bypasses hard filters.

Use gno serve when you want the browser dashboard, full REST API, or desktop shell integration. Use gno daemon for headless continuous indexing and MCP with redacted resident status; full app status remains loopback-only. Both use the same exact-vs-ambiguous watcher reconciliation, expose the same resident /mcp endpoint and lifecycle flags, and are alternative owners of one index, so a second process against the same data directory is rejected.

Yes. Point compatible Streamable HTTP clients at http://127.0.0.1:3000/mcp from either gno serve or gno daemon. Client sessions stay isolated while the resident process shares one store, job runtime, and model lifecycle. Models load lazily, stay reusable during the idle grace period, then retire; the next semantic request may be cold. A native-child failure needs an explicit retry after cleanup, without automatic replay. Existing stdio gno mcp configurations remain supported. Bearer authentication never enables mutation by itself; writes require the separate --mcp-enable-write option.

Yes. Add them to the exclude array in your collection config (for example node_modules, .git, temporary files). You can also use --exclude at query time to skip specific documents from results.

GNO uses local models via node-llama-cpp. The default preset is slim-tuned (~1GB) with the fine-tuned local expansion model plus the same embed, rerank, and answer stack as slim. Other built-in presets are slim, balanced (~2GB), and quality (~2.5GB).

No API key is required for GNO's built-in local models. They are downloaded once and run on your machine. A custom OpenAI-compatible HTTP endpoint may require whatever authentication that server enforces.

Use gno models use <preset> then gno models pull to download, or switch presets directly in the Web UI. GNO validates cached GGUF files before loading them, reports intercepted downloads clearly, and skips HTTP rerank endpoints because they are external services rather than downloadable models. Presets are slim-tuned, slim, balanced, or quality. You can also offload inference to a remote GPU server on your network via HTTP backends.

Yes. GNO supports per-collection model overrides. Add models.embed under one collection in index.yml, set it in the Web UI collection model dialog, or use gno collection add --embed-model when creating a new collection. This is the recommended way to tune code collections without changing the rest of the workspace.

Yes. GNO accepts Hugging Face URIs (hf:org/repo/file.gguf), local file URIs (file:/path/to/model.gguf), and remote OpenAI-compatible HTTP endpoints (http://host:port/path#modelname). Use them in a custom preset globally or as per-collection overrides.

Yes. That's a supported pattern. Run GNO on one machine, run an OpenAI-compatible server on another, and reference its exact endpoint from a named models.presets entry. HTTP backends support the embed, rerank, expand, and gen roles; the server receives the text sent to each configured role, while the corpus and index remain local.

Re-embed so vector and hybrid search catch up to the new model. Run gno embed for everything or gno embed <collection> for one collection. You can then optionally run gno collection clear-embeddings <collection> to remove stale old-model vectors.

GNO publishes a fine-tuned query-expansion model (gno-expansion-slim-retrieval-v1) on Hugging Face. The promoted retrieval fixture measured nDCG@10 of 0.925 and Ask Recall@5 of 0.875. It is the expand role in slim-tuned, not the embedding or standalone answer model. Select it with gno models use slim-tuned and download it with gno models pull --expand.

Run gno skill install --scope user and your agent can search your documents on demand. First-class targets: Claude Code, Codex, OpenCode, OpenClaw, and Hermes Agent. Grok Build and Cursor read the Claude skill directory automatically; other skill-capable clients can copy the same files. Installed skills also include second-brain recipes for lookup, capture, meetings, email context, source summaries, ideas, and citations. The agent pulls in only the passages it needs.

Yes, on two levels. Retrieval: install the skill and Claude Code looks up notes, docs, and project files when it needs context, pulling matching passages on demand instead of pasting a vault into the prompt. Memory: mark one collection memoryManaged: true and the agent stores standing facts with gno remember "<fact>" --scope <scope> and reads them back with gno recall "<query>" --scope <scope>, which returns current facts only, at most 8 under 512 tokens, each cited by gno:// URI. A fact is replaced by a hash-checked supersede, never edited in place, and the recall receipt travels back as --receipt so recalled text is not re-stored as a new fact. The gno agents install protocol block and three bundled memory recipes teach the agent when to recall and when to remember. See the memory reference for the full contract and its limits.

Run gno mcp install --target cursor (or zed, windsurf, amp, etc.). The installer pins the exact Bun + GNO package runtime, active index, and absolute config, data, and cache roots so the client opens the same workspace even outside your shell. This lets your editor’s AI assistant search and retrieve from your documents directly.

Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools. GNO provides 34 read-only tools by default, including retrieval, Knowledge Delta, Context Capsules, scoped memory recall, and the opt-in gno_ask verified-answer tool; 19 mutating tools, gno_remember among them, are separately enabled with --enable-write, for 53 total. The opt-in core tool profile advertises 7 read tools (plus gno_capture and gno_remember with writes enabled) with short routing descriptions, so a session pays for 9 tool definitions instead of 53; the write gate is the same in both profiles. gno_ask requires literal verify: true and never widens write authority. gno mcp status passively reports configuration presence; use the Web Connectors page’s explicit read-only verification action when you need a fresh runtime and retrieval proof.

Yes. GNO indexes Markdown, PDFs, Office files, and text, and lets you search and ask with cited local-model answers. The corpus and index stay local, and built-in models run locally; configured HTTP model roles receive the text needed for their role. Use it from the workspace UI, the command line, the API, or directly from your AI tools.

Yes. Use --json for machine-readable output, for example gno search "term" --json | jq. GNO also supports CSV, Markdown, XML, and URI output formats. For TypeScript apps, use the SDK to embed GNO directly.

gno.sh is a hosted publication layer. Export a note or collection from local GNO with gno publish export <target>, then upload that artifact at /studio to get a reading-first public URL, secret link, invite-only space, or encrypted share. Local PNG/JPEG/GIF/WebP/AVIF images travel in the artifact (public immutable URLs, secret no-store reauth, encrypted Blob URLs); invite-only image delivery is not supported yet. The publish surface is one feature in the broader GNO product — see the publish platform page for details.

Yes. Point GNO at the compiled markdown wiki and, if you want, the raw sources, then search both via hybrid retrieval, cited answers, MCP, or skill.

GNO is a local-first RAG system with a workspace around it. Its corpus and index remain on your machine, while optional HTTP inference sends role-specific text to the server you configure. It combines keyword search, semantic search, reranking, cited answers, and supported AI-tool integrations.