GNO — local knowledge engine
Build a second brain you own: your files, your agents, their memory, and the evidence behind every answer, on one local index.
Point GNO at folders on your machine and it builds one SQLite index across Markdown, code, PDFs, and Office docs. Search it, browse and edit it in the workspace, connect ten AI clients in one command, and let agents remember what they learn, scoped and cited. When an answer has to be checked, a Context Capsule carries exact line spans and verified Ask abstains below full claim support. Open source, MIT, zero telemetry.
bun install -g @gmickel/gno && gno setup ~/notes --name notesConditions. GNO 1.38.0 indexed a 143-document demo vault for a fictional incident-response team, with Markdown notes, TypeScript sources, PDFs, and Office files in four collections. gno graph, gno links, and gno similar supplied the nodes, wiki links, similarity edges, hubs, isolates, and unresolved targets. Each cycle replays one recorded run of gno query --explain, so the BM25 hits, vector hits, reranked top-k, and Context Capsule spans and content hashes are the ones GNO returned. The third query is a verified Ask that failed closed and emitted no answer. The browser draws only the 3D layout and the query origin marker. Hover a node to see its neighbourhood.
§1 — Start here
Install, point GNO at one folder, add the others wherever they live, search, and connect one AI client. Everything further down the page builds on these five.
# Point GNO at a folder. Returns after lexical search finds a real hit.
gno setup ~/notes --name notes# Add more folders, wherever they live. Each becomes a collection in the same index.
gno collection add ~/Documents/contracts --name contracts# Keyword and semantic retrieval, fused and reranked.
gno query 'why did we drop the queue rewrite'# Same index, one command, into Claude Code. Swap the target for Cursor, Codex, or the other seven.
gno mcp install --target claude-code# When the answer has to be checked: generate only what a closed Capsule supports.
gno ask 'why did we drop the queue rewrite' --verify --show-sources§2 — Everything you keep, one index
One SQLite index across every collection, however the folders are spread across your machine. Binary formats are converted once and stay read-only; Markdown stays editable in place.
Markdown, plain text, source code, PDF, and Office documents, plus mail, calendar, transcript, JSONL, and browser exports. Export containers become independently searchable read-only records without live account access.
Group sources by directory with glob patterns, includes, and excludes. Add contexts and project-aware affinity, and give each collection its own local, LAN, or remote egress policy.
The browser clipper captures a visible selection or a Reader extract over a paired loopback connection, with a server-owned preview and exact provenance. Workspace capture carries typed presets and the same provenance fields.
§3 — Look around
The web UI is a full notes app: a cross-collection tree, a Markdown editor that writes back to your files, PDFs as native pages, capture with provenance from the workspace or the browser clipper, and a graph that opens the source note. It can be the only app you write in; Obsidian users keep their vault and gain the index. Run it in the browser with gno serve, as the desktop app (beta), or from the Omarchy bar with GNO Recall: a health widget, a panel with counts and recent documents, and a Super+R overlay for search and collection browsing.
Conditions. GNO 1.45.1, the Fig. 1 demo vault. Each cycle replays one recorded gno capture --json receipt (preset meeting, source kind meeting, 2 tags, content hash, sync completed), then gno links list (3 wiki links, all resolved), gno backlinks (0 for a new note), and gno similar (3 neighbours after an embed) for the new note. The browser draws only the rows and the edges.
§4 — Search that shows its work
Keyword search misses paraphrases and vector search misses the exact error code. GNO runs both, fuses them with reciprocal rank fusion, reranks with a cross-encoder, and can print why a result ranked where it did.
BM25 and vector results are fused with reciprocal rank fusion and reranked by a cross-encoder, across 15,000+ documents in one index. The explain mode prints what every stage contributed to a result's rank.
How ranking worksFilter by date, tag, author, or language. Steer the search intent, exclude topics, and expand a query to related concepts. Built-in stages run locally; HTTP model roles use the endpoint you configure.
Advanced retrievalThe slim-tuned preset uses a published fine-tuned model for retrieval-time query expansion. It never trains on your documents and stays separate from the model that writes answers.
Fine-tuned modelsRecording is off until you enable it. Only judgments you make explicitly become qrels, exported fixtures contain no source text, and replay compares a candidate against a baseline read-only. It recommends; you promote.
Private retrieval learning§5 — Connect your agents
Claude Code, Claude Desktop, Cursor, Codex, Zed, Windsurf, OpenCode, Amp, LM Studio, and LibreChat read the same index with the same ranking: integrations for ten supported agent clients, each one command. A 7-tool core profile keeps the tool list short and writes stay opt-in. An agent that needs to remember gets remember and recall: cited facts, scoped per agent, superseded by hash instead of edited in place. gno agents install writes a protocol block into the harness that teaches the retrieval ladder and the writing contract.
Conditions. GNO 1.45.1, the Fig. 1 demo vault in four collections plus one memory-managed scratch collection with two remembered facts. Each cycle replays one recorded walk of the ladder for one question: gno search (5 BM25 hits), gno recall (2 facts under the 8-fact / 512-token budget with a receipt), gno query --fast (5 hybrid results; the expanded and reranked run aborted twice with a native GGML assert on the recording machine, so the fast run is what the rung shows), gno context build (2 spans, 14461 of 20000 tokens, 18 omitted), gno ask --verify (abstained, 0 of 5 claims supported), and gno query diagnose for a document the question does not reach (absent from all five stages). The browser draws only the fan-in and the walking marker.
One-command MCP or skill install. Pick your client.
§6 — Memory your agents can cite
gno remember stores a fact as a Markdown record in a memory-managed collection; gno recall returns the current facts for a query under a budget of 8 facts and 512 tokens, each with its URI and content hash. The same contract runs on the CLI, MCP, REST, and the SDK, and ships as a Hermes Agent provider and an OpenClaw memory plugin.
Conditions. GNO 1.45.1, one memory-managed collection, lexical mode with no embedding model, caller agent:claude-code. Six gno remember calls stored facts under scope project:atlas. gno recall returned one fact under the 8-fact / 512-token budget with a receipt digest. Storing that recalled span again was rejected as MEMORY_FENCED_REPLAY. A supersede wrote a successor that names its predecessor by content hash; the next recall returned only the successor, and a recall under scope project:other returned 0 facts. Every id, hash, and budget figure is from the recorded run.
§7 — When the answer has to be checked
Once search works, the next question is whether you can trust what comes back. One bounded Capsule per goal carries exact line spans, source hashes, one token budget, and an explicit list of gaps. Verified Ask generates against that closed set and withholds the draft unless every substantive claim is supported.
Conditions. GNO 1.45.1, the Fig. 1 demo vault. Each cycle replays one recorded gno context build (2 spans with line ranges and mirror hashes, 14461 of 20000 tokens, 18 candidates omitted, coverage incomplete), the gno ask --verify that ran against that closed evidence (5 claims: 4 insufficient, 1 uncertain, 0 supported, so the answer was withheld as coverage_below_threshold), and gno context watch + reverify after one evidence file changed (content_stale). No claim reached supported in the recorded run; the figure shows the abstention path it saw, never a supported answer it did not. The browser draws only the sliding spans and the budget bar.
Compile one bounded evidence bundle for a goal: exact line spans, source hashes, one global token budget, collapsed duplicates, and an explicit list of what it could not find. Your agent reads it once instead of issuing repeated gno_query / gno_search calls.
How Capsules workVerified Ask generates against one closed Capsule, classifies every substantive claim as supported, contradicted, insufficient, or uncertain, and withholds the draft unless support reaches 100%. An abstention is a valid result, not a failure.
See verified answersSaved Capsules can be watched. When their sources move, the resident runtime reverifies the exact spans and writes a canonical, non-generative freshness receipt. Knowledge Delta shows what changed and which decisions depended on it.
Read about Knowledge Deltagno setup returns only after lexical search finds a real result derived from your own corpus. No green checkmark for a folder that indexed but cannot be searched. Semantic readiness is tracked separately and honestly.
Verified setup§8 — Characterization
Compiled once, across all 48 paired agentic retrieval tasks. Fewer retrieval calls, a smaller model-visible context, the same task accuracy. These figures measure the handoff workflow; ranking quality has its own artifacts. Every number resolves to a committed benchmark artifact you can download and recompute, pinned to a corpus with its limits stated beside the result.
The agent stops re-searching for context it already has
Same answers reached on a smaller token budget
No completion loss against the paired baseline
Conditions. Measured across all 48 paired tasks in the agentic retrieval benchmark, not a selected task. The baseline lane is normalized to 100. Raw receipts, fingerprints, and the limitations of the run are published with the result.
Move through collections and nested folders, keep separate browse context per tab, and jump from folder structure straight into the note you want. Markdown stays editable, converted binaries stay read-only, and PDFs retain their native page layout in the viewer.
Ask a question and GNO answers from your own documents with citations that resolve to the source passage. Turn on verification and every substantive claim gets bound to an evidence ID, a line range, and a content hash before the draft is released.
§9 — Runs while you work
Run GNO headless as a watcher and resident MCP gateway. The journal records every change, the scheduled findings pass writes audit records into a collection, and an interrupted embed resumes from its durable checkpoint on the next run. Local models load on demand, stay reusable during idle grace, then retire. After a native-child failure, retry explicitly once cleanup completes; failed requests are not replayed.
Conditions. GNO 1.45.1, the Fig. 1 demo vault. Each cycle replays a recorded gno changes --follow --jsonl stream while one note was created, edited, and deleted (3 events with their post-cursors), one gno audit --json pass (78 link findings in 179 ms; the daemon was not running on the recording machine, so the scheduled findings pass is represented by the same read-only audit it runs), and two gno index --json receipts: the embed stage was killed mid-run and the next run reported resumedFrom for it, finishing 47 embeddings in 2911 ms without re-indexing the 143 lexical files. The browser draws only the sliding squares and the bar.
One persistent service watches and indexes while local models load on demand, remain reusable during idle grace, then retire. Clients explicitly configured for its Streamable HTTP MCP endpoint share that runtime; direct CLI and stdio clients do not automatically attach.
Broken or ambiguous links, declared provenance, and source and index freshness in one offline report with stable finding IDs and exact totals, so two runs diff cleanly.
Every collection carries a local-only, LAN, or remote policy. One evaluator checks serving, inference, publishing, exports, and derived evidence before any transfer, and being signed in never overrides it.
Zero telemetry, and everything works offline once models are cached. Exactly three explicit boundaries: a model download, an HTTP model role you configure, and a snapshot you publish.
Script it, embed it in a Bun app, or call it over REST. Every surface and every agent client hits the same index with the same ranking behavior.
§10 — Feature index
BM25 and vectors fused, reranked, and explainable, over Markdown, code, PDFs, Office files, and portable exports.
Markdown, PDF, Office, code, plus portable mail, calendar, transcript, JSONL, and browser exports, as independently searchable records.
Browse collections, edit markdown, read PDFs as native pages, and open the knowledge graph from the same local index.
Skills and MCP for ten clients, plus a shared resident gateway with lazy model loading, warm reuse, and idle retirement.
remember and recall on the CLI, MCP, REST, and SDK: scoped, cited facts, superseded by content hash, fenced against replay.
One persistent service with warm model reuse and idle retirement, a change journal you can follow, and a scheduled findings pass that writes audit records.
One deterministic, token-budgeted evidence handoff with exact spans, declared gaps, and reproducibility fingerprints.
Generate against one closed Capsule, classify every substantive claim, and abstain when the evidence is incomplete.
See what changed, trace which decisions depend on it, and reverify saved evidence when its sources move.
The workspace in a native window that supervises gno serve; signed macOS DMG and a Windows x64 zip, in beta.
A quiet bar widget, an anchored panel with health and recents, and a Super+R overlay over the same local index.
Clip a visible selection or a Reader extract over a paired loopback connection, with a server-owned preview and exact provenance.
A published fine-tuned model for retrieval-time query expansion only; it never trains on your documents.
Off until enabled; only explicit judgments become qrels, fixtures carry no source text, replay is read-only.
One offline, read-only report over links, provenance, and freshness, with stable finding IDs and exact totals.
Committed artifacts behind every number: pinned corpora, raw outputs, fingerprints, and stated limitations.
Fail-closed local, LAN, and remote policies that follow evidence through inference, publishing, exports, and traces.
Export an explicit snapshot and host it as a reading-first page: public URL, secret link, invite-only, or encrypted.
Export from GNO, upload the artifact, and get a page with editorial typography, outline navigation, scoped search, and backlinks restricted to what you published. Public URLs, secret links, invite-only spaces, or shares encrypted before they leave your machine.
§11 — Top questions
Point GNO at folders on your machine and it builds one local index across markdown, code, PDFs, Office documents, and portable exports. From there you get keyword, semantic, and hybrid search; a workspace with a folder tree, a markdown editor, native PDF pages, and a knowledge graph; and one-command hookup so Claude Code, Cursor, Codex, and seven other clients retrieve from the same index. When an answer has to be checked, GNO can compile a Context Capsule and abstain below full claim support. Open source, MIT licensed. Indexing, search, and built-in models run on your machine.
Markdown, PDF, Office documents, plain text, and source code, plus portable mail and calendar exports, transcripts, JSONL, and browser exports. Markdown stays editable in the workspace; converted binaries stay read-only, and the interface never blurs the two. Point it at a folder that mixes all of them and it handles the mix.
Those match the words you typed. GNO also matches meaning, so a search for “how we handle retries” finds the paragraph that talks about exponential backoff without the word “retry” in it. It reads inside PDFs and Office files rather than just their filenames, it spans every folder you have added rather than one vault, it answers questions in natural language with citations, and it exposes all of that to your AI tools. If your material is one folder of Markdown and you only ever search for exact strings, ripgrep is genuinely fine.
No GPU required and no account required. Local GNO is free and MIT licensed. Document conversion and keyword search do not need local model inference. Embedding is separate model work. Semantic search and AI answers use built-in local models that run on CPU, and will use Apple Silicon or a GPU if you have one. You can point inference at an external endpoint instead, which is an explicit opt-in, and the only paid thing anywhere is the optional gno.sh hosted publishing layer.
Not by default. Indexing, search, and the built-in models run on your machine with zero telemetry, and work offline once models are cached. There are exactly three boundaries, all explicit: downloading a model, configuring an HTTP inference endpoint (which then receives the text for that model role), and uploading an artifact you exported for gno.sh. Each collection also carries a fail-closed egress policy that authentication cannot override.
One command per client. gno mcp install --target <client> pins the exact runtime, index, and workspace roots so the client opens the same workspace regardless of shell environment, and gno skill install gives agents CLI-level retrieval with no protocol overhead. MCP exposes 34 read-only tools by default, including Capsule build, Capsule verification, Knowledge Delta, scoped memory recall, and the opt-in verified Ask tool. The 19 mutating tools, gno_remember among them, require a separate flag. An opt-in core profile advertises 7 read tools with routing descriptions (9 with writes enabled) for sessions that should pay for fewer tool definitions.
Yes, in two layers over one local index. Retrieval: your agent pulls the passages it needs on demand instead of loading a knowledge base into every session. Facts: mark one collection memoryManaged: true and any agent you authorize can gno remember a standing fact under explicit scopes and gno recall the current facts later, at most 8 under 512 tokens, cited by gno:// URI. Each fact is one markdown file in your own vault with caller, session, source, and content hash in its frontmatter; a change is a hash-checked supersede that keeps the predecessor on disk, and a recall receipt fences recalled text from being stored again as new. The same contract runs on the CLI, MCP (gno_recall read-only, gno_remember behind --enable-write), REST, and the SDK, so Claude Code, Codex, and the Hermes Agent provider read and write the same store, and the OpenClaw plugin retrieves over it. Run gno daemon and several clients share one resident runtime over a Streamable HTTP MCP gateway. Local models load on demand, stay reusable during their idle grace period, then retire; the next semantic request reloads them. Nothing is captured automatically and no model sits in the write path: every fact is an explicit call, and the agent decides add or supersede.
GNO indexes the folders you already have, including PDFs, Office files, and portable exports, and puts a workspace, a CLI, an SDK, REST, and ten agent clients on that one index. On top of that it can produce checkable evidence: a Context Capsule with exact line spans and content hashes, an answer path that abstains unless every substantive claim is supported, freshness receipts when sources move, and setup that reports success only after lexical search returns a real corpus hit. The benchmark artifacts behind those claims ship in the repository. Search and the workspace work without ever touching the evidence layer.
No, and GNO will not claim otherwise. Verified Ask checks a draft only against the exact evidence retained in its closed local Capsule. It binds verdicts to evidence IDs, line ranges, and hashes, reports stale evidence and verifier degradation, and abstains when support is incomplete. It does not prove anything beyond your corpus, and it cannot make a wrong source right.
An optional publishing layer. Export a note or collection locally, upload the artifact, and get a reading-first page: public URL, secret link, invite-only space, or a share encrypted before it leaves your machine. Public snapshots can also expose the shipped read-only agent projection. Private agent API access is deferred: secret-link, invite-only, and encrypted spaces remain human-reader surfaces. The five-partner knowledge-room pilot is a consented concierge validation program, not a generally available service. Nothing outside the artifact you exported ever reaches the server.
Yes to both. Point GNO at an Obsidian vault and it indexes wiki links, frontmatter tags, and the whole tree, adding hybrid search, cited answers, and agent access on top of what you already have. For an LLM Wiki, where an agent compiles raw sources into a persistent markdown knowledge base, GNO indexes both the compiled wiki and the raw sources, so retrieval spans both layers.