# Table of Contents - [Documentation — GNO Local Knowledge Workspace](#documentation-gno-local-knowledge-workspace) - [Web UI — GNO Docs](#web-ui-gno-docs) - [REST API — GNO Docs](#rest-api-gno-docs) - [Agent skills — GNO Docs](#agent-skills-gno-docs) - [Packaging proof — GNO Docs](#packaging-proof-gno-docs) - [SDK — GNO Docs](#sdk-gno-docs) - [MCP integration — GNO Docs](#mcp-integration-gno-docs) - [How-To — GNO Docs](#how-to-gno-docs) - [Architecture — GNO Docs](#architecture-gno-docs) - [Quickstart — GNO Docs](#quickstart-gno-docs) - [Installation — GNO Docs](#installation-gno-docs) - [Configuration — GNO Docs](#configuration-gno-docs) - [CLI commands — GNO Docs](#cli-commands-gno-docs) - [How search works — GNO Docs](#how-search-works-gno-docs) - [Troubleshooting — GNO Docs](#troubleshooting-gno-docs) - [Publish a note — GNO Docs](#publish-a-note-gno-docs) - [Visibility modes — GNO Docs](#visibility-modes-gno-docs) - [Cursor integration — GNO Docs](#cursor-integration-gno-docs) - [Claude Code integration — GNO Docs](#claude-code-integration-gno-docs) - [Use cases — GNO Docs](#use-cases-gno-docs) - [Fine-tuned models — GNO Docs](#fine-tuned-models-gno-docs) - [Claude Desktop integration — GNO Docs](#claude-desktop-integration-gno-docs) - [Structured query syntax — GNO Docs](#structured-query-syntax-gno-docs) --- # Documentation — GNO Local Knowledge Workspace Documentation Everything you need to run GNO locally. ======================================= GNO is a local knowledge workspace. Most users access it through their AI tools — Claude Code, Claude Desktop, Claude Cowork, Cursor, Codex, OpenClaw, Hermes Agent — via a one-line skill or MCP install. The docs cover installation, configuration, per-client setup guides, the CLI, web UI, REST API, and SDK, plus the optional gno.sh publishing layer for sharing a note or collection beyond your machine. New here? Start with the [quickstart](https://gno.sh/docs/quickstart) — you’ll go from an empty folder to a searchable knowledge base wired into your AI tools in under five minutes. Going straight for a specific integration? Jump to [Claude Code](https://gno.sh/docs/claude-code) , [Claude Desktop](https://gno.sh/docs/claude-desktop) , [Cursor](https://gno.sh/docs/cursor) , or the full [MCP reference](https://gno.sh/docs/mcp) . Getting Started --------------- * [Quickstart](https://gno.sh/docs/quickstart) * [Installation](https://gno.sh/docs/installation) * [Configuration](https://gno.sh/docs/configuration) Reference --------- * [CLI commands](https://gno.sh/docs/cli) * [Packaging proof](https://gno.sh/docs/packaging) * [Web UI](https://gno.sh/docs/web-ui) * [REST API](https://gno.sh/docs/api) * [SDK](https://gno.sh/docs/sdk) * [MCP integration](https://gno.sh/docs/mcp) * [Agent skills](https://gno.sh/docs/skills) * [Structured query syntax](https://gno.sh/docs/syntax) * [Fine-tuned models](https://gno.sh/docs/fine-tuned-models) Integrations ------------ * [Claude Code](https://gno.sh/docs/claude-code) * [Cursor](https://gno.sh/docs/cursor) * [Claude Desktop](https://gno.sh/docs/claude-desktop) Guides ------ * [How-To](https://gno.sh/docs/how-to) * [How search works](https://gno.sh/docs/how-search-works) * [Architecture](https://gno.sh/docs/architecture) * [Use cases](https://gno.sh/docs/use-cases) * [Troubleshooting](https://gno.sh/docs/troubleshooting) gno.sh Publishing ----------------- * [Publish a note](https://gno.sh/docs/publish-quickstart) * [Visibility modes](https://gno.sh/docs/publish-visibility) Beyond the docs --------------- * [GitHub repository](https://github.com/gmickel/gno) — source code, issues, releases * [FAQ](https://gno.sh/faq) — short answers to common questions * [Feature pages](https://gno.sh/features) — marketing-style overview of every capability * [gno.sh publishing](https://gno.sh/publish) — hosted sharing layer on top of the local workspace --- # Web UI — GNO Docs Reference Web UI ====== The local browser workspace started by gno serve: search, browse, graph, edit, capture, API, and live indexing. `gno serve` starts GNO’s local browser workspace and REST API. It is the easiest surface for people who do not want to live in a terminal: add folders, watch indexing progress, search, ask, browse notes, inspect the knowledge graph, and safely edit Markdown. Everything still runs on your machine. What this is ------------ * **Workspace** — a dashboard, document browser, search UI, ask UI, graph, editor, collections screen, and connector setup. * **Local API server** — the same process exposes `/api/*` for scripts and internal tools. * **Live indexer** — while the workspace is running, file changes are watched and synced so recent notes become searchable. Launch and manage ----------------- gno serve # foreground, http://localhost:3000 gno serve --port 8080 # custom port gno serve --index research # named index gno serve --detach # background; prints pid + url gno serve --status --json # machine-readable status gno serve --stop # graceful stop * `--port` changes the browser/API port. * `--detach`, `--status`, `--stop`, `--pid-file`, and `--log-file` use the same lifecycle contract as `gno daemon`. * Use `gno daemon` instead when you want background indexing without the browser or API server. Workspace pages --------------- * **Dashboard** — first-run checklist, health center, model download state, document counts, indexing state, quick capture. * **Search** — BM25, vector, and hybrid retrieval with filters for collection, date, category, author, tags, intent, and query modes. * **Ask** — cited Q&A over your local documents. Good for “what did I decide?” and “summarize these meeting notes” workflows. * **Browse** — cross-collection tree with folder detail panes and document quick switching. * **Doc View / Editor** — rendered document view, split-view Markdown editor, live preview, frontmatter metadata, wiki-link autocomplete, presets, and safe editing rules. * **Graph** — interactive network of wiki links, markdown links, backlinks, unresolved links, and similarity edges. * **Collections and Connectors** — add folders, reindex, tune collection settings, and install agent integrations. Quick capture ------------- Press N to capture a note into an editable collection. The basic path is still title plus content; open **Source** only when you want provenance fields such as kind, URL, author, observed time, or external id. Choose a preset when you want a scaffold; `idea-original`, `person`, `company-project`, and `meeting` are tuned for second-brain pages. Quick Capture writes structured `source:` frontmatter and shows the same receipt states as CLI, MCP, REST, and SDK capture: write result, FTS sync, and embedding. FTS sync may be pending, skipped, or failed independently from the file write. Embedding stays separate until you run embed or index. The typed presets use the same synthesis/timeline pattern as CLI capture: current assessment above `## Timeline`, raw notes and dated evidence below it. If `contentTypes` rules are configured, matching preset frontmatter or folder prefixes become `contentType` metadata in JSON search/query results. Search and ask controls ----------------------- The Web UI exposes the same retrieval controls as the CLI. Use exact search for names and phrases, vector search for conceptual matches, hybrid for normal research, and the Ask page when you want a grounded answer with citations. term: "spaced repetition" intent: personal knowledge base learning loop hyde: A note explaining how repeated review turns saved notes into long-term memory. Safe editing model ------------------ Markdown and plain text stay editable. Converted binaries (PDF, DOCX, XLSX, PPTX) stay read-only. If you want to work on the content of a converted document, use **Create editable copy** in the doc view — it spawns a new markdown note with source provenance intact. Keyboard shortcuts ------------------ * Cmd/Ctrl+K — command palette and quick switcher * N — quick capture a new note * / — focus search * T — cycle search depth * ? — shortcut reference Next steps ---------- * [Keep a collection fresh](https://gno.sh/docs/how-to#keep-fresh) * [REST API reference](https://gno.sh/docs/api) * [CLI serve and daemon reference](https://gno.sh/docs/cli#serve-daemon) --- # REST API — GNO Docs Reference REST API ======== HTTP endpoints exposed by gno serve for search, documents, graph data, models, jobs, and workspace automation. The REST API is the HTTP version of the local GNO engine. Start it with `gno serve`, then call `/api/*` from curl, scripts, desktop launchers, internal dashboards, or small apps. It is best when you want automation without embedding the SDK or installing an MCP client. What this is ------------ * **Search API** — BM25, vector, hybrid query, and cited ask endpoints. * **Workspace API** — documents, folders, collections, tags, links, graph, note presets, content-type metadata, and autocomplete. * **Operations API** — status, sync, jobs, model pull status, and connector detection. Launch the server ----------------- gno serve # default port 3000 gno serve --port 8080 gno serve --detach # browser workspace + API in background Read endpoints -------------- * `GET /api/health` — basic liveness check. * `GET /api/status` — index stats, collection health, model state, background watcher state, and onboarding state. * `GET /api/capabilities` — feature availability for the active install. * `GET /api/collections`, `GET /api/tags`, `GET /api/docs`, `GET /api/doc` — enumerate and fetch local content. * `GET /api/doc/:id/links`, `GET /api/doc/:id/backlinks`, `GET /api/doc/:id/similar`, `GET /api/graph` — graph and relationship data. * `GET /api/events` — server-sent document change events for live UIs. Search endpoints ---------------- curl -X POST localhost:3000/api/search -d '{"q":"exact term"}' curl -X POST localhost:3000/api/vsearch -d '{"q":"concept"}' curl -X POST localhost:3000/api/query -d '{"q":"research question"}' curl -X POST localhost:3000/api/ask -d '{"q":"what changed?"}' Search bodies mirror the CLI: `collection`, `limit`, `since`, `until`, `category`, `author`, `intent`, `exclude`, `tags_any`, `tags_all`, and mode-specific controls such as `noExpand`, `noRerank`, `candidateLimit`, and `queryModes`. curl localhost:3000/api/query \ -H 'content-type: application/json' \ -d '{ "q": "authentication", "collection": "notes", "limit": 20, "tags_any": ["security"] }' Write and job endpoints ----------------------- * `POST /api/collections` and `DELETE /api/collections/:name` — add or remove indexed folders. * `POST /api/sync` — trigger reindexing from the browser or an automation. * `POST /api/capture` — capture a note with structured provenance, optional preset scaffolds, and a receipt that separates write, sync, and embed state. * `POST /api/docs`, `PUT /api/docs/:id`, `POST /api/docs/:id/move`, `POST /api/docs/:id/duplicate`, `POST /api/docs/:id/deactivate` — create and manage editable documents. * `POST /api/folders` — create a folder inside a collection. * `POST /api/models/pull`, `GET /api/models/status`, `GET /api/jobs/active`, `GET /api/jobs/:id` — model downloads and long-running job polling. Use `/api/capture` for second-brain capture with `source:` frontmatter and presets such as `person`, `company-project`, `meeting`, or `idea-original`. Use `/api/docs` for raw note creation without provenance capture semantics. REST capture starts an async sync job, so receipts usually return `sync.status` as `pending` with a job id. Capture content must be text, `/api/capture` does not accept legacy `overwrite`, and capture writes fail instead of replacing a late-arriving file. Security model -------------- * **Localhost by default.** The server is designed for your own machine. If you expose it to a network, put authentication in front. * **CSRF protection.** Mutating browser requests need a same-origin local origin or an API token. * **Optional token.** Set `GNO_API_TOKEN` and send `X-GNO-Token` from non-browser clients. export GNO_API_TOKEN="secret" gno serve curl -H "X-GNO-Token: secret" localhost:3000/api/status --- # Agent skills — GNO Docs Reference Agent skills ============ Install GNO as a progressive agent skill for Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent, and compatible clients. GNO skills teach coding agents how to use the `gno` CLI without permanently loading a large tool schema into their context. They are ideal for quick, explicit knowledge lookups from Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent, and other clients that support agent skills. What this is ------------ * **Progressive instructions** — the agent discovers the GNO workflow only when you invoke the skill or ask for local knowledge retrieval. * **CLI-backed** — skill commands call the installed `gno` binary, so results match the terminal. * **Good for humans and agents** — ask the agent to search a personal knowledge base, project docs, PDFs, meeting notes, or saved research before it answers. * **Second-brain recipes** — installed playbooks route agents through lookup, capture, meetings, email context, source summaries, ideas, and citation/provenance workflows. Install ------- gno skill install --scope user # Claude Code default gno skill install --target codex --scope user gno skill install --target opencode --scope user gno skill install --target openclaw --scope user gno skill install --target hermes --scope user gno skill install --target all --scope user --force * `--target` — `claude`, `codex`, `opencode`, `openclaw`, `hermes`, or `all`. * `--scope` — `user` for every project or `project` for the current repo. * `--force` — overwrite an existing installed copy after upgrading GNO. Skill management commands ------------------------- * `gno skill install` — copy the bundled skill into the selected target. * `gno skill uninstall` — remove it. * `gno skill show` — preview the generated skill files. * `gno skill show --file recipes/brain-first-lookup.md` — preview a nested recipe playbook. * `gno skill paths` — show target install locations. Using the skill --------------- /gno search "deployment checklist" /gno query "what did I save about spaced repetition?" /gno ask "summarize my notes on local-first software" /gno graph --neighbors gno://notes/llm-memory.md Natural language works too: “search my notes for the latest pricing decision,” “find related docs before you edit this file,” or “use GNO to retrieve my notes about this client.” Second-brain recipes -------------------- Recipes are agent-facing guidance files, not native connectors. Email, calendar, chat, and web material must be user-supplied or exported unless a separate tool provides it. gno skill show --file recipes/brain-first-lookup.md gno skill show --file recipes/capture-and-file.md gno skill show --file recipes/meeting-ingestion.md gno skill show --file recipes/email-context.md gno skill show --file recipes/source-summary.md gno skill show --file recipes/idea-capture.md gno skill show --file recipes/citation-and-provenance.md Write-flavored recipes include provenance, privacy, prompt-injection handling, and post-write verification with `gno index`, `gno embed`, `gno search`, `gno query`, or `gno get`. Skills vs MCP ------------- * Use **skills** for explicit slash-command lookups and low context overhead. * Use **MCP** when you want the AI client to automatically call tools during conversation. * Installing both is normal: skills for direct control, MCP for deeper agent integration. --- # Packaging proof — GNO Docs Reference Packaging proof =============== How GNO proves the npm tarball users install contains the runtime files and doctor contract needed for release. The supported CLI distribution is the npm package installed through Bun. Before a release is published, GNO verifies the actual packed tarball instead of only testing the repository checkout. Local package smoke ------------------- bun run test:package This command runs `scripts/package-smoke.ts`. It calls `npm pack`, installs from the generated npm tarball into isolated temporary `HOME`, `GNO_*`, npm cache, and npm prefix paths, then runs the packaged binary. Packed file proof ----------------- The smoke checks the package allowlist and required runtime files. The required file proof includes `package.json`, `bunfig.toml`, `src/index.ts`, `src/sdk/index.ts`, `src/embed/retry.ts`, `src/serve/public/globals.built.css`, and `THIRD_PARTY_NOTICES.md`. Packaged CLI proof ------------------ The installed tarball binary must pass `gno --version`, `gno --help`, `gno init`, and `gno doctor --json` from the isolated install. Doctor JSON failures are release failures. The doctor assertion is exact: output must include the `embedding-fingerprint` check and an `embeddingFingerprint` payload with `currentFingerprint`, `pendingChunks`, `legacyChunks`, `mixedGroups`, and `groups`. This proves the packaged install exposes the same embedding freshness contract as the repository build. --- # SDK — GNO Docs Reference SDK === Import GNO directly into a Bun or TypeScript app with createGnoClient and the same local retrieval engine. The SDK is for apps that want GNO in-process. Use it when a local Bun or TypeScript app needs search, retrieval, document access, indexing, or graph navigation without shelling out to `gno` or running `gno serve`. What this is ------------ * Same retrieval core as CLI, Web UI, API, and MCP. * Direct control over config, database path, download policy, and lifecycle. * Best for local apps, research tooling, desktop shells, and private automation where HTTP is unnecessary. Install ------- bun add @gmickel/gno Basic usage ----------- import { createDefaultConfig, createGnoClient } from "@gmickel/gno" const config = createDefaultConfig() config.collections = [{\ name: "notes",\ path: "/Users/me/notes",\ pattern: "**/*",\ include: [],\ exclude: [],\ }] const client = await createGnoClient({ config, dbPath: "/tmp/gno-sdk.sqlite", }) await client.index({ noEmbed: true }) const results = await client.search("authentication") for (const hit of results.results) { console.log(hit.uri, hit.score) } await client.close() Client APIs ----------- * `client.search(query, opts?)` — BM25 keyword search for exact words, phrases, filenames, and identifiers. * `client.vsearch(query, opts?)` — vector similarity for conceptual matches. * `client.query(query, opts?)` — hybrid retrieval with expansion, opt-in graph candidates, fusion, and reranking controls. * `client.ask(question, opts?)` — retrieval-only or cited answer generation. * `client.get(ref)` and `client.multiGet(refs)` — fetch indexed documents by URI, doc ID, or path. * `client.links(ref)`, `client.backlinks(ref)`, `client.similar(ref)` — navigate direct and semantic relationships. * `client.list()` and `client.status()` — inspect document inventory and index health. * `client.capture(input)` — write a note with provenance and an optional `presetId`, then return the same capture receipt shape as CLI, API, and MCP. Content is text-only, collision policies are runtime-validated, legacy `overwrite` is not accepted, and writes fail on late-arriving files. * `client.update()`, `client.embed()`, `client.index()` — sync files, embed chunks, or do both. * `client.close()` — release file handles and SQLite connections. const receipt = await client.capture({ collection: "notes", title: "Customer call", content: "Follow up on renewal timeline.", presetId: "meeting", tags: ["customer", "follow-up"], source: { kind: "meeting", title: "Customer call", }, }) console.log(receipt.uri, receipt.contentHash) Configuration patterns ---------------------- Define collections in code when your app owns the workspace, or point at an existing GNO config when the user already has one. const fromExisting = await createGnoClient({ configPath: "/Users/me/Library/Application Support/gno/config/index.yml", }) const noDownloads = await createGnoClient({ config, downloadPolicy: { offline: false, allowDownload: false }, }) Lifecycle --------- Always call `await client.close()` when your process is shutting down. After close, further calls throw a GNO SDK error. This matters for desktop apps, tests, and short-lived automations because the SDK holds SQLite connections and file handles. --- # MCP integration — GNO Docs Reference MCP integration =============== Install GNO as a local MCP server for Claude Desktop, Claude Code, Cursor, Codex, Zed, Windsurf, Amp, and more. MCP lets AI assistants call local tools. GNO’s MCP server gives Claude, Cursor, Codex, and other clients grounded access to your own documents without uploading the corpus to a hosted search service. GNO retrieves; the client model synthesizes. What this is ------------ * **Read tools** — search, vector search, hybrid query, document fetch, tags, status, links, backlinks, similar docs, and graph exploration. * **Write tools** — capture notes, add/remove collections, sync, embed, and index. These are disabled by default. * **Resources** — documents addressable as `gno://` URIs for precise follow-up reads. Install ------- gno mcp install --target claude-desktop gno mcp install --target claude-code gno mcp install --target cursor gno mcp install --target codex gno mcp install --target zed gno mcp install --target windsurf gno mcp install --target opencode gno mcp install --target amp gno mcp status Default scope is user-level when the client supports it. Use `--scope project` for project-local configuration in clients such as Claude Code, Cursor, Codex, OpenCode, and LibreChat. Restart the client after install. Server command -------------- * `gno mcp` or `gno mcp serve` — run the stdio MCP server directly. * `gno mcp install` — write the selected client config. * `gno mcp uninstall` — remove GNO from a client config. * `gno mcp status` — inspect configured targets. * `--enable-write` or `GNO_MCP_ENABLE_WRITE=1` — allow mutating tools. Tool playbook ------------- * `gno_query` — default for most questions. Hybrid retrieval returns URIs, snippets, scores, and line anchors. * `gno_search` — exact phrases, titles, identifiers, and error strings. * `gno_vsearch` — conceptual matches where wording may differ. * `gno_get` and `gno_multi_get` — retrieve exact context after search. Prefer bounded line ranges when available. * `gno_links`, `gno_backlinks`, `gno_similar`, `gno_graph`, `gno_graph_neighbors`, `gno_graph_path` — navigate relationship context. * `gno_status`, `gno_list_tags`, `gno_collections_list` — diagnose what exists before searching. * `gno_capture`, `gno_sync`, `gno_embed`, `gno_index`, `gno_add_collection`, `gno_remove_collection` — write-enabled operations. Recommended agent pattern ------------------------- 1. Start with `gno_query` for broad questions. 2. Use `gno_get` around returned line anchors instead of loading whole documents by default. 3. Use `gno_multi_get` with a byte cap when several sources are needed. 4. Use graph tools when the question is about relationships, missing links, related ideas, or how two notes connect. Security posture ---------------- Write tools (`capture`, `sync`, `embed`, `index`, collection changes) are disabled by default so your AI client cannot accidentally modify the corpus. Enable them explicitly per client: gno mcp install --target cursor --enable-write GNO_MCP_ENABLE_WRITE=1 gno mcp Collection creation rejects dangerous roots such as `/`, `~`, system folders, and hidden config directories. Still review client approval prompts before write calls. Capture ------- `gno_capture` is registered only when write tools are enabled. It writes structured `source:` frontmatter, syncs the file for FTS, accepts the same typed `presetId` values as CLI/REST/SDK capture, and returns the same provenance receipt shape as CLI, REST, and SDK capture, plus legacy MCP fields such as `docid`, `absPath`, `overwritten`, and `serverInstanceId`. { "collection": "notes", "content": "thought to remember", "source": { "kind": "web", "url": "https://example.com/source", "title": "Source page" }, "collisionPolicy": "open_existing", "presetId": "source-summary", "tags": ["inbox", "research"] } Collision checks include indexed documents and disk-only files. Use `open_existing` to return an existing receipt without rewriting, `create_with_suffix` to create the next available path, or legacy `overwrite: true` to replace the target path. Content must be text, and non-overwrite captures fail instead of replacing a late-arriving file. MCP capture does not auto-embed; run `gno_embed` or `gno_index` afterward when vector search should include the note. Resource URIs ------------- GNO exposes every document as an MCP resource, so clients can fetch a file by URI without going through a tool call. gno://documents/ gno://collections/ Related ------- * [Agent skills reference](https://gno.sh/docs/skills) * [Connect your AI tools](https://gno.sh/docs/how-to#connect-ai) --- # How-To — GNO Docs Guides How-To ====== Practical GNO recipes for keeping collections fresh, building personal knowledge bases, connecting AI tools, and recovering stale indexes. GNO is not only for codebases. It works well for a personal knowledge base, research archive, meeting-note library, PDF folder, or Karpathy-style “memory bank” that your AI tools can search before they answer. These recipes start from useful outcomes, not implementation details. For second-brain work, create typed pages with `gno capture --preset person`, `--preset company-project`, `--preset meeting`, or `--preset idea-original`. Keep the current synthesis above `## Timeline` and the evidence trail below it. Installed skills also include recipes for brain-first lookup, capture/file, meeting ingestion, email context, source summaries, idea capture, and citation/provenance. Preview them with `gno skill show --file recipes/brain-first-lookup.md`. These recipes use local indexed context and user-supplied/exported external material; they do not add native Gmail, Calendar, Slack, webhook, cron, or background-agent automation. Keep a collection fresh automatically ------------------------------------- Use `gno daemon` when you want local file changes to become searchable without keeping the Web UI open. gno init ~/Documents/Knowledge --name knowledge gno index --models-pull gno daemon --detach gno daemon --status gno daemon --stop The daemon watches configured collections, syncs changed files, and embeds new chunks. Use `--no-sync-on-start` if you only want future changes handled. For git-backed folders, run `gno update --git-pull` or `gno index --git-pull` when you want remote commits pulled in. Build a personal AI memory bank ------------------------------- 1. Put notes, PDFs, docs, exports, and research into one folder or a few topic folders. 2. Add them as GNO collections with clear names. 3. Run `gno index`, then keep them fresh with `gno daemon --detach`. 4. Install MCP or skills so your AI assistant can retrieve from that memory before answering. contentTypes: - id: person prefixes: [people/] preset: person - id: meeting prefixes: [meetings/] preset: meeting gno collection add ~/Documents/Research --name research gno collection add ~/Documents/Notes --name notes gno collection add ~/Downloads/Papers --name papers gno index gno mcp install --target claude-desktop gno skill install --target all --scope user --force Connect your AI tools --------------------- Pick the integration by how you want the assistant to behave. * [MCP](https://gno.sh/docs/mcp) — automatic tool calls from Claude Desktop, Claude Code, Cursor, Codex, Zed, Windsurf, OpenCode, Amp, LM Studio, LibreChat, and compatible clients. * [Agent skills](https://gno.sh/docs/skills) — explicit `/gno` lookups with low context overhead. * [REST API](https://gno.sh/docs/api) — scripts, launchers, dashboards, and custom local apps. gno mcp install --target cursor --scope project gno skill install --target codex --scope user Use GNO without living in a terminal ------------------------------------ Start the local workspace, then add folders and manage indexing from the browser. gno serve open http://localhost:3000 Use Search for retrieval, Ask for cited answers, Browse for document navigation, Graph for relationships, and Collections for folder management. Fix stale or missing results ---------------------------- 1. Confirm the files are indexed: `gno ls --collection notes`. 2. Rescan changed files: `gno update`. 3. Refresh embeddings: `gno embed notes`. 4. Run the full path: `gno index`. 5. Diagnose system issues: `gno doctor`. If you changed the embedding model, clear stale collection embeddings before rebuilding them: gno collection clear-embeddings notes gno embed notes Research with filters and graph context --------------------------------------- Combine filters when your archive grows beyond simple search. gno query "learning loops" --collection research --tags-any ai,pkm gno ask "what are my strongest notes on retrieval?" --since "last month" --answer gno graph --neighbors gno://notes/llm-memory.md --include-similar gno graph --from gno://notes/a.md --to gno://notes/b.md Local GNO stays private. When you intentionally want to publish a note or collection, export an artifact and upload it through gno.sh Studio. gno publish export atlas --out ~/Downloads/atlas.json Then open [/studio](https://gno.sh/studio) , import the artifact, and pick public, secret-link, invite-only, or encrypted sharing. --- # Architecture — GNO Docs Guides Architecture ============ How GNO is built — Bun, SQLite, local models, and the shared retrieval core. GNO is a Bun-compiled TypeScript application with a SQLite-backed index, local model inference via node-llama-cpp, and a shared retrieval core that every surface (CLI, Web UI, SDK, REST API, MCP) plugs into. Runtime ------- * **Bun** — instant cold starts, single binary distribution, TypeScript-first runtime * **SQLite + sqlite-vec** — BM25 FTS plus vector similarity via a SQLite extension. One database file per GNO installation. * **node-llama-cpp** — local LLM inference for embedding, reranking, and answer generation. GGUF model format. Storage layout -------------- * `~/.config/gno/` — config files (index.yml, presets) * `~/.local/share/gno/` — SQLite database, model cache, asset cache * `~/.cache/gno/` — temporary artifacts, rerank scratchpad Surfaces -------- Every GNO surface speaks to the same shared retrieval core: * **CLI** — `src/cli/*`, bundled as the `gno` binary * **Web UI** — `gno serve` launches a Bun HTTP server with the browser workspace and the REST API * **SDK** — package-root importable client, same core under the hood * **REST API** — exposed by `gno serve`, 35+ endpoints * **MCP server** — stdio transport, read/write tools, graph navigation, and resources for any MCP-compatible client * **Desktop** — a native window wrapping the web workspace Data flow --------- 1. **Ingestion** — file walker reads sources, parsers extract text + frontmatter, chunker splits into retrievable units 2. **Embedding** — chunk text is encoded to dense vectors via the chosen embedding model 3. **Indexing** — chunks land in SQLite FTS and sqlite-vec tables; docs, links, and tags land in relational tables 4. **Retrieval** — query enters the pipeline, hits BM25 + vector, merges, reranks, returns 5. **Answer** — for `ask`, the top matches go to the local LLM with a citation-preserving prompt Related ------- * [How search works](https://gno.sh/docs/how-search-works) * [Privacy model](https://gno.sh/features/privacy-first) --- # Quickstart — GNO Docs Getting Started Quickstart ========== Go from a local folder to hybrid search, browsing, and AI answers in under five minutes. Go from a local folder to hybrid search, a browsable workspace, and AI answers in under five minutes. Most users access GNO through their AI tools — Claude Code, Claude Desktop, Cursor, Codex, OpenClaw, Hermes Agent — so the quickstart wires that up too. This guide assumes GNO is already installed; if not, start with [installation](https://gno.sh/docs/installation) . 1\. Point GNO at your documents ------------------------------- A folder can be Markdown, PDF, Word, Excel, PowerPoint, plain text, or a mix. gno init ~/notes --name notes gno init ~/Documents --name docs --pattern "**/*.md" Prefer a guided UI? Start `gno serve`, open `http://localhost:3000`, and use the first-run checklist to add a folder, pick a preset, and start indexing with zero CLI commands. 2\. Index your documents ------------------------ gno index Runs keyword (BM25) + vector indexing. GNO handles Markdown, PDF, DOCX, XLSX, PPTX, and plain text automatically. On first run, GNO may download local models (embedding ~500MB, optional rerank/gen models +700MB–1.2GB). Subsequent runs use the cache. To skip startup downloads, set `GNO_NO_AUTO_DOWNLOAD=1` and run `gno models pull` explicitly. Cached GGUF files are validated before load, so intercepted HTML or other non-model responses are removed with a clear recovery error. gno ls 3\. Connect your AI tools ------------------------- This is where GNO gets powerful. Instead of copy-pasting context, your AI tools search and retrieve from your documents directly. Pick one or both integration paths: ### Skills — for coding agents Installs GNO as a `/gno` slash command. Zero context window overhead — the agent only loads GNO tools when the command is invoked. Works with Claude Code, Codex, OpenCode, OpenClaw, and Hermes Agent. gno skill install --target claude --scope user gno skill install --target codex --scope user gno skill install --target opencode --scope user gno skill install --target openclaw --scope user gno skill install --target hermes --scope user gno skill install --target all --scope user # install everywhere ### MCP — for AI assistants and editors Installs GNO as a Model Context Protocol server so Claude Desktop, Claude Cowork, Cursor, Zed, Windsurf, and others can call GNO tools automatically in conversation. gno mcp install --target claude-desktop gno mcp install --target cursor gno mcp install --target zed gno mcp install --target windsurf gno mcp install --target claude-code # MCP for Claude Code gno mcp status # see what's configured Restart the client after install. Then just ask in natural language: _“Search my notes for deployment procedures”_ or _“Find architecture docs related to this change”_. 4\. Search from the CLI (optional) ---------------------------------- If you prefer the terminal, GNO exposes three search modes for different trade-offs between speed and depth. # Fast keyword search (~5–20ms) gno search "project deadlines" # Meaning-based search (~0.5s) gno vsearch "how to handle errors" # Hybrid — keyword + semantic + reranking, best results gno query "authentication best practices" # AI answer with citations gno ask "what is the main goal of project X" --answer Use `gno capture` when you want to add a quick note to an editable collection with provenance metadata and an optional typed preset scaffold. gno capture "thought to remember" gno capture --file ./clip.md --source-url https://example.com --source-kind web --json gno capture --preset person --title "Jane Doe" --folder people/ gno capture --preset meeting --title "Weekly sync" --folder meetings/ Output formats -------------- For scripting, every command supports machine-readable output: gno search "important" --json gno search "important" --files gno search "important" --csv gno search "important" --md Next steps ---------- * Configure presets + collections: [configuration reference](https://gno.sh/docs/configuration) * Full [Claude Code](https://gno.sh/docs/claude-code) , [Claude Desktop](https://gno.sh/docs/claude-desktop) , and [Cursor](https://gno.sh/docs/cursor) integration guides * All MCP tools + clients: [MCP reference](https://gno.sh/docs/mcp) * Share a note publicly: [gno.sh publishing](https://gno.sh/publish) --- # Installation — GNO Docs Getting Started Installation ============ Install GNO via Bun, verify with gno doctor, and configure vector search on macOS. GNO ships as a Bun-compiled CLI that also exposes a web server, a TypeScript SDK, and an MCP server. One install gives you all of them. macOS and Linux --------------- bun install -g @gmickel/gno On macOS, vector search requires the Homebrew build of SQLite so GNO can load the SQLite extension for vector similarity: brew install sqlite3 After install, verify with `gno doctor`. It checks for the CLI, SQLite, models, and disk space. gno doctor Windows ------- Current support target is **windows-x64**. The CLI path works via Bun/global install, and the desktop beta ships as a packaged Windows zip on GitHub Releases. Windows arm64 is not supported yet. bun install -g @gmickel/gno Desktop beta ------------ The packaged desktop shell wraps `gno serve` in a native window with the workspace UI pre-wired. Grab a build from [GitHub Releases](https://github.com/gmickel/gno/releases) and run it like any other desktop app. Verify your install ------------------- gno --version gno doctor gno status `gno doctor` surfaces path resolution, SQLite version, model cache location, disk space, and embedding freshness. `gno status` stays lightweight: it shows the currently active config file and collection summary without probing native model runtimes. Release package proof --------------------- GNO releases run `bun run test:package` before publish. That script packs the npm tarball with `npm pack`, installs from that tarball into isolated temporary paths, verifies required packed files including `src/embed/retry.ts`, then runs the packaged `gno --version`, `gno --help`, and `gno doctor --json`. The packaged doctor proof is specific: JSON must include the `embedding-fingerprint` check and its `embeddingFingerprint` payload with `currentFingerprint`, `pendingChunks`, `legacyChunks`, `mixedGroups`, and `groups`. Connect your AI tools --------------------- The CLI is only one way to use GNO. Most users plug it into their AI tools so search, retrieval, and citations happen automatically. One command per client: # Coding agents (zero-overhead skill install) gno skill install --target claude --scope user # Claude Code gno skill install --target codex --scope user gno skill install --target opencode --scope user gno skill install --target openclaw --scope user gno skill install --target hermes --scope user gno skill install --target all --scope user # all agents # AI assistants and editors (MCP) gno mcp install --target claude-desktop gno mcp install --target cursor gno mcp install --target zed gno mcp install --target windsurf gno mcp install --target claude-code gno mcp status Full client list + write-access options: [MCP reference](https://gno.sh/docs/mcp) . Per-client setup guides: [Claude Code](https://gno.sh/docs/claude-code) , [Claude Desktop](https://gno.sh/docs/claude-desktop) , [Cursor](https://gno.sh/docs/cursor) . Next steps ---------- * Run [the quickstart](https://gno.sh/docs/quickstart) to index and search your first collection * Tune presets and collections: [configuration](https://gno.sh/docs/configuration) * Publish a note publicly: [gno.sh publishing](https://gno.sh/publish) --- # Configuration — GNO Docs Getting Started Configuration ============= Configure GNO via index.yml, manage collections, and pick the right model preset. GNO is driven by a YAML config file and a set of CLI verbs. Most users never touch the file directly — they manage collections and presets via the CLI or the Web UI. But when you need it, here’s where everything lives. Config file location -------------------- * **macOS / Linux**: `~/.config/gno/config/index.yml` * **Windows**: `%APPDATA%\gno\config\index.yml` Run `gno doctor` to see the resolved paths for your machine. 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 Exclusions ---------- Add an `exclude` array to a collection to skip files and directories: collections: notes: path: ~/notes exclude: - node_modules - .git - "**/*.tmp" Model presets ------------- GNO ships four built-in presets. Switch with one command; the first pull downloads the model files and caches them locally. * **slim-tuned** (~1GB) — fine-tuned local expansion model on top of the slim stack. Default for new installs. * **slim** — leaner models, faster on modest hardware. * **balanced** (~2GB) — larger models, better recall. * **quality** (~2.5GB) — highest quality on every stage. 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 temporal: true Frontmatter `type` becomes canonical only when it matches a configured content type ID. Otherwise it remains category metadata.`searchBoost` and `graphHints` are accepted for future ranking/graph work, but are reserved no-ops today. Per-collection model overrides ------------------------------ Override embed, rerank, or answer models for a single collection — useful when your code collection wants a code-specific embedding while your prose collection sticks with the general-purpose 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 on your LAN. models: answer: uri: http://localhost:11434/v1#llama3.1:8b 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. * `GNO_LLAMA_GPU` — choose `auto`, `true`, `false`, `cuda`, `vulkan`, or `metal`. `NODE_LLAMA_CPP_GPU` remains a compatibility alias when this is unset. * `GNO_LLAMA_BUILD` — backend build mode. Default: `never`. Set `autoAttempt` only when you intentionally want `node-llama-cpp` to try a local source build. * `GNO_LLAMA_INIT_TIMEOUT_MS` — local backend initialization timeout. Default: `30000`. * `GNO_EMBED_CONTEXTS` — override CPU embedding context count, clamped from `1` to `4`. CPU-only runs choose a small adaptive pool automatically: one context on low-memory Windows machines, otherwise at most two contexts unless you explicitly override it. * `GNO_EMBED_THREADS` — override CPU threads per embedding context. * `GNO_EMBED_CONTEXT_SIZE` — override native embedding context size. Minimum: `128`. * `GNO_NO_AUTO_DOWNLOAD` — disable automatic model downloads; explicit `gno models pull` still works. --- # CLI commands — GNO Docs Reference CLI commands ============ Reference for every gno command, global option, retrieval mode, background service, and integration surface. The `gno` CLI is the local control plane for your knowledge base. Use it to connect folders, build the index, search and ask questions, keep the collection fresh in the background, and wire GNO into AI tools. It is useful from a terminal, but the same commands also power the Web UI, REST API, MCP server, and agent skills. Quick chooser ------------- Start here when you know what you want to do but not which command to reach for. * `gno init`, `gno collection`, `gno index` — connect folders and build the index. * `gno search`, `gno vsearch`, `gno query`, `gno ask` — retrieve knowledge. * `gno get`, `gno multi-get`, `gno ls` — inspect indexed documents. * `gno capture` — add quick notes with structured provenance and a write/sync/embed receipt. * `gno links`, `gno backlinks`, `gno similar`, `gno graph` — follow relationships. * `gno serve`, `gno daemon` — run long-lived local services. * `gno mcp`, `gno skill`, `gno publish` — connect agents and share snapshots. How the CLI thinks ------------------ 1. **Collections** point at folders on disk: notes, research, PDFs, project docs, client files, or a Karpathy-style personal knowledge base. 2. **Indexing** reads files, extracts text, chunks documents, records links and tags, then embeds chunks for semantic search. 3. **Retrieval** searches with keyword, vector, hybrid, optional graph expansion, and optional reranking. 4. **Surfaces** expose the same index through the CLI, browser workspace, REST API, MCP, SDK, and installed skills. Setup: init, collection, index ------------------------------ ### gno init Creates the first GNO config and points it at a folder. Use it for the first folder in a new index. gno init ~/Documents/Knowledge --name knowledge gno init ~/Notes --name notes --pattern "**/*.md" gno init ~/Research --name research --exclude "**/archive/**" * `--name` sets the collection name used by filters. * `--pattern`, `--include`, and `--exclude` decide which files enter the index. * `--update` records a collection-specific update command, useful for git-backed or generated folders. * `--tokenizer` and `--language` tune text processing for specialized collections. ### gno collection Adds, lists, renames, removes, or resets collection embeddings after the initial setup. gno collection add ~/Downloads/Papers --name papers gno collection list gno collection rename papers reading gno collection clear-embeddings notes gno collection remove old-notes ### gno index, update, embed `update` scans files into SQLite. `embed` creates vectors for semantic search. `index` does both. gno update gno update --git-pull gno embed notes gno index gno index --models-pull gno index --no-embed * `--git-pull` pulls git-backed collections before scanning. * `--models-pull` downloads needed model files before the run. * `--no-embed` builds a fast keyword-only index. * `gno embed` and `gno embed --force` retry transient embedding chunk failures inside the same command run. Use `--verbose` when a run still fails so the sample errors and retry hint are visible. * Run `gno embed` after changing embedding models or after doctor reports stale vectors. If stale or mixed vectors remain, run `gno embed --force` for a full vector refresh. Retrieve: search, vsearch, query, ask ------------------------------------- ### gno search and gno vsearch `search` is exact and fast. Use it for titles, names, quotes, filenames, error messages, and identifiers. `vsearch` is semantic. Use it when the right documents may use different words than your query. gno search "spaced repetition" --collection notes gno search "ERR_INVALID_STATE" --line-numbers gno vsearch "notes about memory and learning loops" --limit 10 * Scope with `--collection`, `--limit`, `--min-score`, `--since`, `--until`, `--tags-any`, `--tags-all`. * Change output with `--full`, `--line-numbers`, `--json`, `--md`, `--csv`, `--files`, `--xml`. ### gno query Hybrid retrieval for normal use. It combines keyword, vector, fusion, and optional reranking. Add graph expansion when linked context matters. gno query "what did I decide about backups?" gno query "papers about retrieval evaluation" --tags-any research gno query "pricing notes" --fast gno query "architecture tradeoffs" --thorough --explain gno query "linked context" --graph --explain gno query $'auth flow\\nterm: "refresh token"\\nintent: token rotation' * `--fast` lowers latency. `--thorough` spends more time for better recall. * `--graph` enables graph-neighbor candidates. `--no-expand` and `--no-rerank` disable pipeline stages for debugging or speed. * `--intent`, `--query-mode`, `--candidate-limit`, and `--explain` steer or inspect retrieval. ### gno ask Retrieves evidence and optionally asks a local model to synthesize a cited answer. Use it for questions over your notes, not for general chatbot use. gno ask "what are my open migration risks?" --answer gno ask "summarize my latest meeting notes" --since "last week" gno ask "what did I save about local-first apps?" --show-sources * `--answer` forces synthesis. `--no-answer` returns retrieval results only. * `--max-answer-tokens` controls answer length. * `--show-sources` keeps citations visible. Read: get, multi-get, ls, tags ------------------------------ ### gno get and gno multi-get Search results return `gno://` URIs, paths, doc IDs, and line anchors. Use the read commands to pull the exact source into a terminal, script, or AI prompt after retrieval. gno get gno://notes/learning.md gno get gno://notes/learning.md --from 40 --limit 30 gno multi-get gno://notes/a.md gno://notes/b.md --max-bytes 12000 * `--from` and `--limit` fetch bounded line ranges. * `--line-numbers` preserves citation-friendly anchors. * `--source`, `--json`, `--md`, `--files` control output shape. ### gno ls, tags, status, doctor Use these when results look wrong. First check whether the document is indexed, then inspect tags and health. gno ls --collection notes gno tags gno status --json gno doctor `gno doctor` includes an `embedding-fingerprint` check. In JSON output, that check carries an `embeddingFingerprint` object with `currentFingerprint`, `pendingChunks`, `legacyChunks`, `mixedGroups`, and `groups`. Warnings mean BM25 still works, but semantic results may need `gno embed` or `gno embed --force`. ### gno capture Capture writes a note into an editable collection. Inline content,`--stdin`, and `--file` are mutually exclusive. Capture accepts text only; binary-like file or stdin content is rejected before writing. With no path, folder, or title, captures land under `inbox/YYYY-MM-DD/capture-.md` using UTC time. gno capture "thought to remember" gno capture --stdin --collection notes --preset source-summary --tags inbox,gno gno capture --file ./clip.md --source-url https://example.com --source-kind web --json gno capture --preset person --title "Jane Doe" --folder people/ gno capture --preset meeting --title "Weekly sync" --folder meetings/ gno capture "meeting note" --quiet Preset IDs include `blank`, `project-note`, `research-note`, `decision-note`, `prompt-pattern`, `source-summary`, `idea-original`, `person`, `company-project`, and `meeting`. The typed second-brain presets keep current synthesis above `## Timeline` and dated evidence below it. JSON output returns a receipt with separate write, sync, and embed status. Capture syncs the note into text search; it does not imply embedding unless `embed.status` is `completed`. Capture writes fail instead of replacing a late-arriving file. Relationships: links, backlinks, similar, graph ----------------------------------------------- ### gno links, backlinks, similar These commands answer “what does this note point to?”, “what points back?”, and “what is semantically nearby?”. gno links gno://notes/llm-memory.md gno backlinks gno://notes/llm-memory.md gno similar gno://notes/llm-memory.md --limit 8 ### gno graph Builds a document graph from wiki links, markdown links, backlinks, unresolved links, and optional similarity edges. Use it to find hubs, isolated notes, communities, nearest neighbors, and paths between ideas. gno graph --collection notes --json gno graph --neighbors gno://notes/llm-memory.md gno graph --from gno://notes/a.md --to gno://notes/b.md gno graph --include-similar --threshold 0.78 gno graph --dot > graph.dot gno graph --mermaid * Scope with `--collection`, `--limit`, `--edge-limit`, `--include-isolated`. * Add semantic edges with `--include-similar`, `--threshold`, `--similar-top-k`. * Explore locally with `--neighbors`, `--direction`, `--from`, `--to`, `--max-depth`. Services: serve and daemon -------------------------- ### gno serve Starts the local browser workspace and REST API. Use it when you want visual search, browsing, graph exploration, editing, or API access. gno serve gno serve --port 8080 gno serve --detach gno serve --status --json gno serve --stop ### gno daemon Runs the headless watch/sync/embed loop. Use it when your CLI and AI tools need fresh search results but you do not need the browser open. gno daemon --detach gno daemon --no-sync-on-start gno daemon --status gno daemon --stop Lifecycle flags for both commands: `--detach`, `--status`, `--stop`, `--pid-file`, `--log-file`. `--json` is for `--status`. Avoid running serve and daemon against the same index at the same time. Agents, models, publishing, and maintenance ------------------------------------------- ### gno mcp and gno skill Use MCP when you want AI clients to call GNO tools automatically. Use skills when you want explicit `/gno` lookups with low context overhead. gno mcp install --target claude-desktop gno mcp install --target cursor --scope project gno skill install --target all --scope user --force gno skill paths ### models, publish, bench, cleanup These are supporting commands for model files, shared artifacts, retrieval evaluation, and housekeeping. gno models list gno models use balanced gno models pull gno publish export atlas --out ~/Downloads/atlas.json gno bench fixture.json --modes bm25,hybrid --json gno cleanup gno completion zsh Global options and output flags ------------------------------- Global options work before the command name. Output flags are repeated on retrieval and read commands where they make sense. * `--index ` — use a named index instead of `default`. * `--config ` — load a specific config file. * `--offline` — use cached model files only. * `--json`, `--md`, `--csv`, `--files`, `--xml` — structured output. * `--verbose`, `--quiet`, `--no-color`, `--no-pager`, `--yes` — terminal and automation behavior. --- # How search works — GNO Docs Guides How search works ================ The GNO retrieval pipeline end to end — BM25, vector, opt-in graph expansion, fusion, and reranking. GNO’s hybrid search is not magic. It’s a deliberate pipeline of proven retrieval techniques composed to give you accurate results whether you search for exact terms or conceptual matches. The pipeline ------------ 1. **Query expansion** — optionally expand the query with HyDE (hypothetical document embeddings) and lexical variants. GNO skips expansion when it has a strong signal. 2. **BM25 retrieval** — classical full-text search over the inverted index. Fast and precise for exact terms, technical identifiers, and quoted phrases. 3. **Vector retrieval** — cosine similarity over dense embeddings. Handles synonyms and conceptual matches. 4. **Reciprocal rank fusion** — merges BM25 and vector results by rank position, not raw score. Robust to different score distributions. 5. **Optional graph expansion** — when `--graph` is passed, bounded one-hop neighbors from top seeds are added as candidates after initial fusion. Active filters still apply, existing chunk positions are preserved, and explicit links are weighted above inferred, ambiguous, or similarity edges. 6. **Second fusion pass** — graph candidates join the BM25/vector ranked inputs before reranking, so linked evidence can boost the right chunk instead of duplicating a document-level hit. 7. **Cross-encoder reranking** — the fused top-N is rescored by a cross-encoder that looks at query and document together. Slow but highly accurate for the top few results. 8. **Return** — the reranked top-K is returned with scores, snippets, and optionally the retrieval pipeline trace. Speed modes ----------- * **Fast** (~0.7s) — skip expansion and reranking, return fused BM25+vector. * **Balanced** (~2–3s) — default. Hybrid retrieval with moderate budgets and no graph expansion. * **Thorough** (~5s+) — larger expansion budget, deeper rerank. gno query "topic" --fast gno query "topic" # balanced gno query "topic" --thorough gno query "topic" --graph Benchmark fixtures ------------------ For repeatable retrieval checks, create a fixture with queries and relevant document URIs, then run `gno bench `. The command evaluates BM25, vector, and hybrid modes against the same corpus and prints metrics that make model or pipeline regressions visible before you switch defaults. gno bench docs/examples/bench-fixture.json gno bench fixture.json --modes bm25,vector,hybrid --json \--explain ---------- Pass `--explain` to any query command to see exactly what happened: expansion output, BM25 hits, vector hits, graph expansion status, fusion order, rerank scores, and stage timings including `graphMs`. Use it to tune your prompts or to debug unexpected results. gno query "topic" --explain Strong signal detection ----------------------- When your query contains exact identifiers or quoted phrases, the pipeline recognizes the strong signal and skips expansion — no point hallucinating a HyDE document when the user already told you exactly what they want. Related ------- * [Hybrid search feature](https://gno.sh/features/hybrid-search) * [Advanced retrieval](https://gno.sh/features/advanced-retrieval) * [Benchmarks](https://gno.sh/features/benchmarks) --- # Troubleshooting — GNO Docs Guides Troubleshooting =============== Common issues and their fixes — from missing SQLite to model download failures. First stop: gno doctor ---------------------- gno doctor `gno doctor` runs every health check GNO knows how to run and prints a report. Nine out of ten problems get diagnosed right here. Read its output carefully before anything else. For embedding freshness, look for the `embedding-fingerprint` check. It reports the current fingerprint, pending/stale chunks, legacy empty-fingerprint vectors, and mixed stored fingerprint groups. Vector search fails on macOS ---------------------------- Symptom: `gno vsearch` or hybrid queries fail with a SQLite extension loading error. Cause: the stock Apple SQLite doesn’t support loading extensions. GNO needs the Homebrew build. brew install sqlite3 gno doctor Models fail to download ----------------------- Symptom: the first `gno query` or `gno ask` stalls during a model pull. Solutions: * Run `gno models pull` explicitly to see real-time progress and errors. * If you’re offline or behind a firewall, set `GNO_NO_AUTO_DOWNLOAD=1` and download model files by hand into the cache. * Clear a stuck download with `gno models clean `. * If a cached download is reported as non-GGUF or intercepted HTML, fix network access and rerun `gno models pull --force`. Results feel stale after editing -------------------------------- Re-scan the index: gno update Or run `gno daemon` in the background for continuous indexing. Results feel off after switching models --------------------------------------- Vector-based search uses the embedding model that was active when the index was built. Doctor now makes this visible through the `embedding-fingerprint` check. After switching embeddings, re-embed: gno doctor gno embed # re-embed stale/pending chunks gno embed notes # or one collection `gno embed` retries transient embedding failures within the same run. If doctor still reports stale, legacy, or mixed vectors after a normal embed, force a full refresh: gno embed --force `gno embed --force` uses the same same-run retry path. If a run still fails, rerun with verbose output so GNO prints sample failures and the retry hint: gno --verbose embed --force Check which GPU backend is detected ----------------------------------- Before forcing a backend, see what `node-llama-cpp` actually detects. This works on Linux, Windows, and macOS and reports the active GPU backend (CUDA, Vulkan, or Metal), available VRAM, and which prebuilt binary is in use: bunx --bun node-llama-cpp inspect gpu (`npx --no node-llama-cpp inspect gpu` works too.) If CUDA or Vulkan shows as available here but GNO still runs on CPU, the backend is being selected or initialized incorrectly — see below. If it is not available here, the GPU driver or toolchain is the problem, not GNO. Windows model startup hangs --------------------------- Symptom: `gno index`, `gno embed`, or `gno doctor` appears stuck while loading `node-llama-cpp`, often around a Vulkan backend load test. GNO now defaults to prebuilt local-model backends, times out backend initialization, and retries CPU on Windows when automatic GPU backend selection fails. Run diagnostics first: gno doctor To force CPU mode for a constrained Windows machine, run: GNO_LLAMA_GPU=false gno embed --yes If CPU embedding still consumes too much memory, keep the adaptive default or set an explicit small context pool. On CPU-only systems, GNO defaults to one context on low-memory Windows machines and at most two contexts elsewhere: GNO_EMBED_CONTEXTS=1 gno embed --yes Advanced CPU tuning is available when you want to trade throughput, memory, and per-context parallelism: GNO_EMBED_CONTEXTS=2 GNO_EMBED_THREADS=4 gno embed --yes GNO_EMBED_CONTEXT_SIZE=512 gno embed --yes Only opt into source builds when you intentionally have Visual Studio Build Tools and a working native toolchain: GNO_LLAMA_BUILD=autoAttempt gno doctor Still stuck? ------------ * Open an issue: [github.com/gmickel/gno/issues](https://github.com/gmickel/gno/issues) * Include your `gno doctor` output and the exact command you ran. --- # Publish a note — GNO Docs gno.sh Publishing Publish a note ============== Sign up for gno.sh, import a note, and get a reading-first URL in under a minute. The fastest path from a note on your disk to a published reading surface on gno.sh. 1\. Create an account --------------------- Open [the signup page](https://gno.sh/signup) and create a free account — no credit card required. You’ll get a verification email and land on your dashboard. 2\. Open the publish studio --------------------------- Go to [the publish studio](https://gno.sh/studio) . The studio is the producer surface — it shows your source list, visibility modes, metadata projection, and an import drop zone. 3\. Drop or import a file ------------------------- Canonical path: export from local GNO first, then upload the artifact. gno publish export atlas --out ~/Downloads/atlas.json Then open [/studio](https://gno.sh/studio) and drop that compiled GNO artifact JSON into the import zone. The markdown path is still useful for quick single-note shares in dev, but the artifact JSON is the real hosted transport for larger collections. For public, secret-link, and invite-only uploads, the studio can now create a new space, overwrite an existing space, or append the new notes into an existing space so the left-hand navigator grows over time. Encrypted shares still update via fresh encrypted upload only. 4\. Pick a visibility mode -------------------------- * **Public** — a plain URL anyone can read * **Secret link** — an unguessable token. Rotate, revoke, or expire at will. * **Invite only** — members of your org sign in to read * **Encrypted** — client-side passphrase. We store ciphertext only when the artifact was encrypted locally before upload. 5\. Press publish ----------------- A receipt appears with the share URL. Click Open to see how your reader will experience the page — full editorial typography, outline, scoped search, and keyboard navigation. Republish --------- Re-importing the same route slug replaces the existing share with a new snapshot. If you want to grow a published collection instead of replacing it, choose **Append to existing** in the studio. Readers keep the same URL in either case; append adds notes to the navigator, overwrite replaces the snapshot. Related ------- * [Publish platform overview](https://gno.sh/publish) * [Visibility modes in depth](https://gno.sh/docs/publish-visibility) * [Publish feature page](https://gno.sh/features/publish-sharing) --- # Visibility modes — GNO Docs gno.sh Publishing Visibility modes ================ Public URLs, secret links, invite-only spaces, and end-to-end encryption — how to choose. gno.sh ships four visibility modes. Pick the one that matches how much control you need over who sees the share. Public URL ---------- A plain, guessable URL. Anyone with the link can read. No auth, no gate. Good for open research notes, client-facing overviews, and anything you’d otherwise post on a blog. URL shape: https://gno.sh/share// Secret link ----------- A long, unguessable token appended to the URL. Readers with the token open the page; anyone without it gets a 404. You can rotate the token at any time (old links stop working), revoke access entirely, or expire in 24 hours. URL shape: https://gno.sh/secret/ Invite only ----------- Readers must be signed in to gno.sh and be an accepted member of your organization. Good for team reference spaces, internal research, or client deliverables where you want an audit trail of who opened the page. URL shape: https://gno.sh/private/ Encrypted --------- Export an encrypted artifact from local GNO with a passphrase you choose, then upload it to gno.sh. Only ciphertext lands on gno.sh servers. Readers enter the passphrase in their browser to decrypt and read. We cannot recover a lost passphrase — that’s the whole point. Store it somewhere safe. To update an encrypted share, export a fresh encrypted artifact from local GNO and upload it again. Hosted republish does not rebuild encrypted shares from source. URL shape: https://gno.sh/locked/ Picking the right mode ---------------------- * Sharing with the world? **Public** * Sharing with one person or one team, casually? **Secret link** * Sharing with a named audience inside your org? **Invite only** * Sharing something you don’t want even gno.sh to be able to read? **Encrypted** Related ------- * [Publish quickstart](https://gno.sh/docs/publish-quickstart) * [Publish feature page](https://gno.sh/features/publish-sharing) --- # Cursor integration — GNO Docs Integrations Cursor integration ================== Install GNO as an MCP server in Cursor for hybrid retrieval while you code. Cursor supports MCP servers natively. One-command install gives Cursor access to GNO’s 19 retrieval tools — search, query, ask, graph, backlinks, similar, and more. Quickstart ---------- bun install -g @gmickel/gno gno init ~/notes --name notes && gno index gno mcp install --target cursor After install, restart Cursor. The GNO MCP server will appear in the MCP settings panel automatically. Using it in Cursor ------------------ Cursor’s composer and chat can both invoke GNO tools. Just ask in plain language: > “Search my notes for the retry logic we discussed” > “Find related notes to this file and summarize them” Cursor picks the appropriate GNO tool and cites the source docs in its response. Project scope ------------- For project-specific MCP configuration, install at the project scope. This writes a `.cursor/mcp.json` in the current project. gno mcp install --target cursor --scope project Manual configuration -------------------- If auto-install fails, add to `~/.cursor/mcp.json`: { "mcpServers": { "gno": { "command": "gno", "args": ["mcp"] } } } --- # Claude Code integration — GNO Docs Integrations Claude Code integration ======================= Use GNO with Claude Code via the SKILL.md install or the MCP server. Claude Code supports two integration paths. **Skills** install GNO as a `/gno` slash command with zero context pollution. **MCP** exposes the same retrieval tools through the Model Context Protocol so Claude can call them automatically. Quickstart ---------- bun install -g @gmickel/gno gno init ~/notes --name notes gno index # Install the skill (preferred — zero context overhead) gno skill install --target claude --scope user # Optional: also install MCP for automatic tool calls gno mcp install --target claude-code The skill target is called `claude` (Claude Code is the default). Use `--scope user` to install globally, or omit it for project-local install. Using the skill --------------- After installing the skill, Claude Code exposes a slash command: /gno search "authentication patterns" /gno query "how does our API handle errors" /gno ask "what's our deployment process" Skills are preferred for coding agents because they have zero context window overhead — the tool definitions only load when the slash command is invoked. Use `gno skill install --target all` to install across Claude Code, Codex, OpenCode, OpenClaw, and Hermes Agent at once. Using MCP --------- With the MCP server installed, Claude Code can call GNO tools automatically. Just ask in plain language: > “Search my notes for deployment procedures” > “Find my architecture docs and summarize the relevant parts for this change” Claude picks the right tool (`gno_query`, `gno_search`, etc.) based on the request. Project scope ------------- For project-specific knowledge, install at the project scope. This writes a `.claude/settings.json` in the current project instead of the user-level config. gno mcp install --target claude-code --scope project --- # Use cases — GNO Docs Guides Use cases ========= Real workflows people use GNO for — research, coding agents, client work, and more. GNO started as a hybrid search CLI and has grown into a full local knowledge workspace. Here’s how people actually use it. Obsidian vault, supercharged ---------------------------- Point GNO at your Obsidian vault. You keep editing in Obsidian, and suddenly you have BM25 + vector + reranking over your notes, a CLI for quick queries, and an MCP server your AI tools can reach. gno init ~/Documents/Obsidian --name vault && gno index gno mcp install --target claude-desktop Memory for Claude Code ---------------------- Install GNO as a skill for Claude Code. Your coding agent can query your notes, docs, and project files on demand without pasting everything into every prompt. gno skill install --target claude --scope user # Then in Claude Code: # /gno query "how does our auth flow work" Research + synthesis -------------------- Research corpus on disk, query via CLI, pipe results to `jq` or to a spreadsheet automation tool, and get cited AI answers from local models. gno query "Q4 budget projections" --json | jq '.results[0]' gno ask "what did we conclude about pricing" --answer Due diligence and consulting ---------------------------- Index a client’s mixed-format document set (Markdown, PDFs, Office docs), share the workspace through the gno.sh publishing layer as an invite-only or encrypted space, and hand the reader URL to the client. gno init ~/clients/acme --name acme && gno index # Export a compiled artifact, open /studio, publish as # invite-only or encrypted Team wiki with git sync ----------------------- Point GNO at a git-synced team wiki directory. `gno daemon` keeps the index fresh as team members push updates, and everyone on the team gets the same retrieval behavior in their local CLI and AI tools. Personal memory layer --------------------- Index everything personal you write: journals, meeting notes, saved articles, receipts. One `gno query` later you remember things you’d otherwise have lost. --- # Fine-tuned models — GNO Docs Reference Fine-tuned models ================= GNO ships a fine-tuned local expansion model trained on Apple Silicon with MLX LoRA. GNO publishes a fine-tuned retrieval expansion model —`gno-expansion-slim-retrieval-v1` — trained locally on Apple Silicon with MLX LoRA. It’s the default on fresh installs and benchmarks meaningfully above the base slim preset. What this is ------------ The expansion model rewrites or augments difficult queries before retrieval. It is not the model that stores your documents or answers every question; it is a small local helper that improves recall when your query and your notes use different words. The numbers ----------- * **nDCG@10 0.925** on the canonical benchmark corpus * **Ask Recall@5 0.875** on the ask-style answer benchmark * Shipped via Hugging Face, pulled on first run Install it ---------- gno models use slim-tuned gno models pull Train your own -------------- The training harness lives in the main GNO repo under `research/`. It uses MLX LoRA for local fine-tuning and can export GGUF artifacts you can install via the Hugging-Face-backed custom preset format. Benchmarks ---------- Before promoting a model change, run the benchmark suite. Use `gno bench` for a public CLI check against your own fixture, and see the [benchmarks feature page](https://gno.sh/features/benchmarks) for the fixture workflow and result metrics. gno bench docs/examples/bench-fixture.json gno bench fixture.json --json --- # Claude Desktop integration — GNO Docs Integrations Claude Desktop integration ========================== Install GNO as an MCP server in Claude Desktop for hybrid retrieval over your local documents. Claude Desktop was one of the first MCP clients. One-command install adds GNO to Claude Desktop’s MCP configuration so Claude can search your local knowledge base in conversation — and **Claude Cowork** picks up the same MCP config, giving your agentic desktop sessions persistent access to your entire document collection. Quickstart ---------- bun install -g @gmickel/gno gno init ~/notes --name notes && gno index gno mcp install --target claude-desktop Quit and reopen Claude Desktop to pick up the new server. Using it in conversation ------------------------ > “Search my notes for anything about the quarterly review process” > “What did I write about the deployment architecture last month?” > “Find related notes to this PDF and give me a summary” Claude picks the right tool and cites the source document in the response. Manual configuration -------------------- If the auto-install fails, add GNO to Claude Desktop’s config manually. Location depends on your OS: * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` { "mcpServers": { "gno": { "command": "gno", "args": ["mcp"] } } } --- # Structured query syntax — GNO Docs Reference Structured query syntax ======================= Multi-line query documents with term, intent, and hyde for explicit retrieval behavior. For complex queries, GNO supports a multi-line query document syntax on `gno query` and `gno ask`. Use typed lines to steer the retrieval pipeline without reaching for CLI flags. What this is ------------ Structured query syntax is a small text format for telling GNO which parts of a question are exact terms, which parts describe intent, and which parts should act like a hypothetical ideal answer. It helps when a natural-language question is ambiguous or when your personal knowledge base uses inconsistent wording. Example ------- auth flow term: "refresh token" -oauth1 intent: how token rotation works hyde: Refresh tokens rotate on each use and previous tokens are invalidated. Rules ----- * Structured syntax is only activated for multi-line input. * Blank lines are ignored. * Recognized typed lines: `term:`, `intent:`, `hyde:`. * At most one `hyde:` line is allowed per document. * Unknown prefixes (e.g. `vector:`) are rejected. Base query resolution --------------------- Every query document needs a base query. GNO picks the base in this order: 1. Plain untyped lines joined together 2. Otherwise all `term:` lines joined together 3. Otherwise all `intent:` lines joined together `hyde:` lines are never searched directly — they serve only as hypothetical document expansion signal. Supported surfaces ------------------ * CLI: `gno query`, `gno ask` * REST: `/api/query`, `/api/ask` * MCP: `gno_query` * Web UI: Search and Ask text boxes * SDK: `client.query(...)`, `client.ask(...)` CLI example ----------- gno query $'auth flow\\nterm: "refresh token"\\nintent: token rotation' ---