# GNO > A local knowledge engine for notes, code, PDFs, and Office documents. GNO indexes your files on your own machine and gives you hybrid keyword-plus-semantic search, a browsable workspace with knowledge graph and editor, a CLI, an SDK, a REST API, and MCP or agent-skill integration for ten AI clients. What sets it apart is that its retrieval can show its work: deterministic evidence with exact line spans and content hashes, answers that abstain when support is incomplete, and receipts you can re-verify later. Open source, MIT licensed, zero telemetry. ## What you get - **One local index** across Markdown, PDF, Office documents, plain text, source code, portable mail and calendar exports, transcripts, JSONL, and browser exports. - **Three search modes**: keyword (BM25), semantic (vector), and hybrid — fused, reranked, and explainable, with structured intent controls and metadata filters. - **A real workspace**: cross-collection folder tree, per-tab browse context, a markdown editor, provenance-carrying quick capture, and a navigable knowledge graph. - **Cited AI answers** over your own documents, with citations that resolve to the source passage. - **Six interfaces on one index**: CLI, web UI, REST API, TypeScript SDK, MCP server, and a desktop shell. - **Ten AI clients, one command each**: Claude Code, Claude Desktop, Cursor, Codex, Zed, Windsurf, OpenCode, Amp, LM Studio, LibreChat. - **Agent memory**: `gno remember` and `gno recall` store scoped, cited facts as Markdown files, replaced by hash-checked supersede and never edited in place. - **Agent session archive**: `gno sessions import` brings selected Codex, Claude Code, OpenClaw, and Hermes conversations into a separate, redacted archive index with every turn marked human or assistant. Manual by default; a Claude Code SessionEnd hook or a `gno daemon` schedule runs only after you enable it. - **Retry-safe writes**: an optional request ID on capture, remember, and document saves lets a client check `gno request-status` and retry without writing twice. - **Optional hosted publishing** at gno.sh when a slice of your workspace needs a URL. No GPU required, no account required, no telemetry. Free and MIT licensed. ## Why not another local RAG tool - **Context Capsules**: one bounded, deterministic evidence bundle per goal, with exact line ranges, three levels of content hash, declared coverage gaps, and explained omissions, all under a single global token budget. Measured on 48 paired agentic benchmark tasks: 100% task completion accuracy retained, 48.94% fewer retrieval calls, 44.12% less model-visible context. - **Verified answers**: `gno ask --verify` generates against one closed Capsule, classifies every substantive claim as supported, contradicted, insufficient, or uncertain, and withholds the draft below 100% support. Abstention is a valid outcome, not a failure. - **Verified setup**: `gno setup` returns only after lexical search proves a real corpus-derived hit. Semantic readiness is tracked separately and honestly. - **Knowledge Delta**: bounded metadata-only change journal, structural diffs, dependency impact paths, and freshness reverification for saved Capsules. - **Private retrieval learning**: opt-in local traces, explicit judgments only, content-free qrels export, read-only baseline-versus-candidate replay. Nothing is recorded or personalized by default. - **Collection egress policies**: fail-closed `local_only`, `lan`, or `remote` boundaries per collection. Derived Capsules, traces, and exports inherit the most restrictive source policy, and authentication never overrides it. ## Boundaries and honest limits - Corpus, index, and built-in models stay local. The three explicit network boundaries are: downloading a model, configuring an HTTP inference endpoint, and uploading an artifact you exported for gno.sh publishing. - Verified Ask checks claims only against the evidence retained in its local Capsule. It is not a general fact-check and cannot make an incorrect source correct. - Local models load on first use and unload after five idle minutes (`warmModelTtl`). Keyword search needs no model; the first semantic request after a pause reloads models and is slower. HTTP MCP clients of `gno serve` or `gno daemon` share loaded models, and stdio MCP still works. If a model process fails, the request returns an error; GNO does not retry it automatically. - Supported search filters apply before candidate limits. Empty or fewer-than-requested results are valid, distinct from reported vector failure or lexical fallback. Vector and hybrid language filters match chunk language; lexical search accepts the language filter but ignores it. - Leaving the Web UI indexing view does not stop indexing jobs already running on the server. Cancelling a request stops your wait, but model work already started finishes first. Interrupted embedding resumes on the next run. - File and export adapters read local export files only. They never authenticate to accounts, read live browser databases, fetch URLs, or open attachments. ## Install ```bash bun install -g @gmickel/gno # requires Bun >= 1.3 gno setup ~/notes --name notes gno mcp install --target cursor # or claude-code, zed, windsurf, ... ``` ## Documentation Every docs page is also served as Markdown at the same path with a `.md` suffix, or by requesting the HTML path with `Accept: text/markdown`. The whole docs set in one file: https://gno.sh/llms-full.txt. ### Getting Started - [Quickstart](https://gno.sh/docs/quickstart): Index a local folder and prove BM25 in under five minutes; semantic search and Ask follow once models download. - [Installation](https://gno.sh/docs/installation): Install GNO via Bun, prove local retrieval with gno doctor, and configure vector search on macOS. - [Configuration](https://gno.sh/docs/configuration): Configure GNO via user config or a portable project profile, manage collections, and pick the right model preset. ### Reference - [CLI commands](https://gno.sh/docs/cli): Reference for every gno command, global option, retrieval mode, background service, and integration surface. - [Package contents](https://gno.sh/docs/packaging): What the GNO npm package needs to run, and how to check that an installed copy works. - [Web UI](https://gno.sh/docs/web-ui): The local browser workspace started by gno serve: search, browse, graph, edit, capture, API, and live indexing. - [REST API](https://gno.sh/docs/api): HTTP endpoints exposed by gno serve for search, documents, graph data, models, jobs, and workspace automation. - [SDK](https://gno.sh/docs/sdk): Import GNO directly into a Bun or TypeScript app with createGnoClient and the same local retrieval engine. - [MCP integration](https://gno.sh/docs/mcp): Install GNO automatically as a local MCP server for exactly 10 named clients; configure Raycast and other compatible clients manually. - [Agent skills](https://gno.sh/docs/skills): Install GNO as a progressive agent skill for Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent, and compatible clients. - [Agent instructions](https://gno.sh/docs/agents-install): gno agents install keeps one versioned, marker-managed GNO protocol block in the global instruction file of every harness on the machine: which file each harness reads, what the markers and the version stamp guarantee, and what the block teaches. - [Structured query syntax](https://gno.sh/docs/syntax): Multi-line query documents with term, intent, and hyde for explicit retrieval behavior. - [Fine-tuned models](https://gno.sh/docs/fine-tuned-models): GNO ships gno-expansion-slim-retrieval-v1 as the expand role in slim-tuned (nDCG@10 0.925, Ask Recall@5 0.875). It does not train on your corpus. ### Integrations - [Browser clipper](https://gno.sh/docs/browser-clipper): Capture a visible selection or Reader-style page into local GNO with previewed Markdown and exact provenance. - [Claude Code](https://gno.sh/docs/claude-code): Use GNO with Claude Code via the SKILL.md install or the MCP server. - [Cursor](https://gno.sh/docs/cursor): Install GNO as an MCP server in Cursor for hybrid retrieval while you code. - [Claude Desktop](https://gno.sh/docs/claude-desktop): Install GNO as an MCP server in Claude Desktop for hybrid retrieval over your local documents. ### Guides - [Context Capsules](https://gno.sh/docs/context-capsules): What a Capsule is, how GNO compiles one, every field it contains, how to verify it later, and when to use one instead of a plain query. - [Compiled project context](https://gno.sh/docs/compiled-context): Verified, budgeted project evidence with explicit local refresh and read-only remote previews. - [Typed metadata filters](https://gno.sh/docs/typed-metadata): Filter retrieval with explicit custom strings, numbers, booleans, and arrays. - [Retrieval learning & replay](https://gno.sh/docs/retrieval-learning): Turn a real retrieval miss into a content-free regression fixture, then replay a candidate pipeline against it before you change anything. - [Knowledge Delta](https://gno.sh/docs/knowledge-delta): Answer change-shaped questions directly: what moved since Tuesday, what structurally changed in this note, and which conclusions depended on it. - [Memory](https://gno.sh/docs/memory): How gno remember and gno recall store and retrieve agent facts: the write-path taxonomy, explicit scopes, supersession, budgeted cited recall, context fencing and its limits, and what memory does not do. - [Agent session archive](https://gno.sh/docs/sessions): Import selected Codex, Claude Code, OpenClaw, and Hermes sessions into a dedicated, redacted, searchable archive that stays separate from your curated vault, manually or through opt-in automation (a Claude Code SessionEnd hook or a daemon schedule). - [Retry-safe writes](https://gno.sh/docs/retry-safe-writes): Send a request ID with capture, remember, or a document save so a retry after a lost response finishes the same write instead of duplicating or overwriting it. - [Knowledge protocol](https://gno.sh/docs/protocol): The retrieval ladder and the writing contract an agent follows over your collections: which GNO command answers which kind of question, what each rung returns and where it stops, and when a write is an edit, a capture, or a remember. - [Project setup & profiles](https://gno.sh/docs/project-profiles): gno setup returns only after a corpus-derived BM25 proof. Commit .gno/index.yml for portable collection/context/content rules; the SQLite DB, model cache, and locks stay out of the repo. - [File & export adapters](https://gno.sh/docs/file-export-adapters): Index mail, calendar, transcript, browser, and JSONL exports as individually searchable records, with no account access and no live connectors. - [Integrity audits](https://gno.sh/docs/integrity-audits): Find broken local links, incomplete declared provenance, and source/index drift. Stable finding IDs; no automatic repair. - [Collection egress](https://gno.sh/docs/collection-egress): Give each collection a fail-closed transport boundary that follows its content through inference, publishing, exports, Capsules, and traces. - [How-To](https://gno.sh/docs/how-to): Practical GNO recipes for keeping collections fresh, building personal knowledge bases, connecting AI tools, and recovering stale indexes. - [How search works](https://gno.sh/docs/how-search-works): BM25, vector, default bounded graph expansion, fusion, and reranking, end to end. - [Architecture](https://gno.sh/docs/architecture): Bun, SQLite, local GGUF models via node-llama-cpp, and one retrieval core shared by CLI, Web UI, SDK, REST, and MCP. - [Use cases](https://gno.sh/docs/use-cases): Obsidian vaults, Claude Code memory, client corpora under local_only, Capsule-backed agent answers, and export-adapter records. - [Troubleshooting](https://gno.sh/docs/troubleshooting): Doctor output, Homebrew SQLite on macOS, model pulls, stale embeddings, switching backend or Bun version, resident background issues, and Windows llama.cpp startup. ### gno.sh Publishing - [Publish a note](https://gno.sh/docs/publish-quickstart): Sign up for gno.sh, import an exported artifact, and publish a versioned reading-first snapshot. - [Visibility modes](https://gno.sh/docs/publish-visibility): Choose public URL, secret-link token, org invite, or client-side passphrase encryption. ## Features - [Context Capsules](https://gno.sh/features/context-capsules): One bounded, checkable evidence handoff for an agent - [Verified Answers](https://gno.sh/features/local-llm): A cited answer from a local LLM, or an honest abstention - [Knowledge Delta](https://gno.sh/features/knowledge-delta): Know what changed, and which conclusions depended on it - [Agent Memory](https://gno.sh/features/agent-memory): One auditable memory store for every agent you authorize - [Agent Sessions](https://gno.sh/features/agent-sessions): Search past coding-agent sessions, with who said what kept on every turn - [Integrity Audits](https://gno.sh/features/integrity-audits): Know what needs attention from one read-only local report - [Private Retrieval Learning](https://gno.sh/features/retrieval-learning): Turn a real miss into a regression test you own - [Verified Setup & Project Profiles](https://gno.sh/features/project-setup-profiles): Activate a folder with proof, then keep its retrieval intent portable - [Collection Egress Governance](https://gno.sh/features/collection-governance): Decide where each collection is allowed to travel - [Hybrid Search](https://gno.sh/features/hybrid-search): Rank the matching paragraph first - [Advanced Retrieval](https://gno.sh/features/advanced-retrieval): Filter by date, tag, author, and language; expand, steer, exclude, and `--explain` - [AI Agent Integration](https://gno.sh/features/agent-integration): Your agents retrieve from your knowledge base on demand - [AI Tool Integration](https://gno.sh/features/mcp-integration): Install GNO as MCP in ten named clients - [Daemon Mode](https://gno.sh/features/daemon-mode): Keep GNO fresh without the web UI - [Benchmarks](https://gno.sh/features/benchmarks): Measure before you switch, and publish it either way - [Fine-Tuned Models](https://gno.sh/features/fine-tuned-models): Measured query expansion with a tuned local model - [Web UI](https://gno.sh/features/web-ui): Browse and edit notes. Read PDFs in their native layout. - [Desktop App](https://gno.sh/features/desktop-app): The workspace in a native window, with gno serve supervised for you - [GNO Recall for Omarchy](https://gno.sh/features/omarchy-recall): The index in your bar: health, recent documents, and a Super+R overlay - [Knowledge Graph](https://gno.sh/features/graph-view): Force-directed graph of wiki links, markdown links, similarity edges, and typed `doc_edges` - [Note Linking](https://gno.sh/features/note-linking): Follow wiki links, backlinks, and typed relations; rewrite them on rename - [Collections](https://gno.sh/features/collections): Group sources by directory, glob, context, and per-collection egress policy - [Tag System](https://gno.sh/features/tags): Filter the local index by frontmatter and hierarchical tags - [Multi-Format Indexing](https://gno.sh/features/multi-format): Index Markdown, Office, PDF, mail, calendar, transcripts, and browser exports - [Browser Clipper](https://gno.sh/features/browser-clipper): Capture a visible selection or Reader extract over loopback pairing - [Privacy First](https://gno.sh/features/privacy-first): Corpus, index, and default models stay on disk with zero telemetry - [Fast CLI](https://gno.sh/features/fast-cli): Keyword search without a model startup - [REST API](https://gno.sh/features/api): 35+ localhost HTTP endpoints for search, ask, graph, and models - [SDK](https://gno.sh/features/sdk): Embed GNO directly - [Publish & Sharing](https://gno.sh/features/publish-sharing): Share your GNO workspace as a reading surface ## Integrations - [Claude Code](https://gno.sh/integrations/claude-code): Give Claude Code a memory that outlives the session - [Claude Desktop](https://gno.sh/integrations/claude-desktop): Ask Claude Desktop about your own files - [Cursor](https://gno.sh/integrations/cursor): Cursor's assistant retrieves ADRs, vendor PDFs, and notes outside the open repo - [Codex](https://gno.sh/integrations/codex): Codex, with your documentation in reach - [Zed](https://gno.sh/integrations/zed): Local retrieval inside Zed's assistant - [Windsurf](https://gno.sh/integrations/windsurf): Windsurf plus your own reference material - [OpenCode](https://gno.sh/integrations/opencode): OpenCode retrieves from your local index on demand - [Amp](https://gno.sh/integrations/amp): Amp, connected to your local corpus - [LM Studio](https://gno.sh/integrations/lm-studio): A fully local stack: LM Studio for generation, GNO for evidence - [LibreChat](https://gno.sh/integrations/librechat): LibreChat retrieves from a local GNO index, not a hosted vector database - [OpenClaw](https://gno.sh/integrations/openclaw): OpenClaw calls GNO skill retrieval against your local notes, docs, and code - [Hermes Agent](https://gno.sh/integrations/hermes): Give Hermes a retrieval protocol for your knowledge - [Obsidian](https://gno.sh/integrations/obsidian): Keep the vault. Add retrieval your agent can use ## Comparisons - [GNO vs Obsidian](https://gno.sh/comparisons/obsidian): Obsidian wins on plugins, Canvas, and visual note-taking. GNO wins on retrieval, agent access, and multi-format indexing. They compose well. - [GNO vs Khoj](https://gno.sh/comparisons/khoj): Khoj is a broader personal AI assistant platform. GNO is a tighter local retrieval and workspace engine for developer workflows. - [GNO vs PrivateGPT](https://gno.sh/comparisons/privategpt): Both are privacy-first local RAG. PrivateGPT is a Python-first server stack. GNO is a local knowledge workspace with stronger retrieval UX and agent integration. - [GNO vs Quivr](https://gno.sh/comparisons/quivr): Quivr is a team-oriented second brain with cloud sync. GNO is a local-first retrieval workspace with CLI, REST API, and agent integration. - [GNO vs AnythingLLM](https://gno.sh/comparisons/anythingllm): AnythingLLM is a full chat app with document upload. GNO is a retrieval engine and workspace that plugs into your existing AI tools. - [GNO vs Reor](https://gno.sh/comparisons/reor): Reor is a standalone note app with built-in chat. GNO indexes any folder and also ships a workspace editor, graph, and PDF viewer; you can keep Obsidian/VS Code or work in GNO’s UI. - [GNO vs GPT4All](https://gno.sh/comparisons/gpt4all): GPT4All is a local LLM chat app with attached document support. GNO is a retrieval workspace for using multiple AI clients with the same local index. - [GNO vs Kotaemon](https://gno.sh/comparisons/kotaemon): Kotaemon is a RAG web UI focused on document Q&A with citations. GNO is a retrieval engine with CLI, REST API, MCP, and agent integrations in addition to a web UI. - [GNO vs Qmd](https://gno.sh/comparisons/qmd): Both run local hybrid search with an MCP server over the notes you keep. Qmd is a single-purpose CLI with four MCP read tools. GNO adds PDF and Office indexing, a 7-tool or 38-tool MCP profile, Context Capsules, verified answers, remember/recall memory, a workspace UI, and optional publishing. - [GNO vs GBrain](https://gno.sh/comparisons/gbrain): GBrain is a self-maintaining agent memory: it writes the brain after conversations and enriches it overnight, on its own agenda. GNO is the knowledge engine your agents capture into and retrieve from, over folders and formats you already keep, on a cadence you wire. - [GNO vs grep](https://gno.sh/comparisons/grep): grep finds exact patterns at sub-millisecond speed. GNO finds concepts, handles multi-format content, and feeds AI agents. - [GNO vs Elasticsearch](https://gno.sh/comparisons/elasticsearch): Elasticsearch is a distributed search engine for production workloads. GNO is a single-user local knowledge workspace with embedded SQLite. ## Optional - [Publishing platform](https://gno.sh/publish): export a note or collection locally and publish it as a reading-first page (public, secret link, invite-only, or encrypted before upload). - [Pricing](https://gno.sh/pricing): the local engine is free and MIT licensed; pricing covers hosted publishing only. - [Ecosystem](https://gno.sh/ecosystem): companion tools. - [Full documentation as one file](https://gno.sh/llms-full.txt) - [Source](https://github.com/gmickel/gno)