Gno

GNO

Local search, retrieval, and synthesis for the files you actually work in.

[](https://www.npmjs.com/package/@gmickel/gno) [](./LICENSE) [](https://gno.sh) [](https://twitter.com/gmickel) [](https://discord.gg/nHEmyJB5tg)

> [!TIP] > gno.sh/publish is live. Turn any GNO note or collection into a polished, reader-first URL — editorial typography, scoped search, and four visibility modes from public to encrypted-before-upload. [See the reader →](#publish-to-gnosh)

> ClawdHub: GNO skills bundled for Clawdbot — clawdhub.com/gmickel/gno

GNO is a local knowledge engine for notes, code, PDFs, Office docs, meeting transcripts, and reference material. It gives you fast keyword search, semantic retrieval, grounded answers with citations, wiki-style linking, and a real workspace UI, while keeping the whole stack local by default.

Use it when:

• your notes live in more than one folder
• your important knowledge is split across Markdown, code, PDFs, and Office files
• you want one retrieval layer that works from the CLI, browser, MCP, and a Bun/TypeScript SDK
• you want better local context for agents without shipping your docs to a cloud API

What GNO Gives You

• Fast local search: BM25 for exact hits, vectors for concepts, hybrid for best quality
• Real retrieval surfaces: CLI, Web UI, REST API, MCP, SDK
• Local-first answers: grounded synthesis with citations when you want answers, raw retrieval when you do not
• Connected knowledge: backlinks, related notes, graph view, cross-collection navigation
• Shareable, not synced: export a note or collection to gno.sh as a polished reader page — public, secret, invite-only, or locally encrypted before upload
• Operational fit: daemon mode, model presets, remote GPU backends, safe config/state on disk

One-Minute Tour

# Install
bun install -g @gmickel/gno

# Add a few collections
gno init ~/notes --name notes
gno collection add ~/work/docs --name work-docs --pattern "**/*.{md,pdf,docx}"
gno collection add ~/work/gno/src --name gno-code --pattern "**/*.{ts,tsx,js,jsx}"

# Add context so retrieval results come back with the right framing
gno context add "notes:" "Personal notes, journal entries, and long-form ideas"
gno context add "work-docs:" "Architecture docs, runbooks, RFCs, meeting notes"
gno context add "gno-code:" "Source code for the GNO application"

# Index + embed
gno update --yes
gno embed

# Search in the way that fits the question
gno search "DEC-0054"                            # exact keyword / identifier
gno vsearch "retry failed jobs with backoff"     # natural-language semantic lookup
gno query "JWT refresh token rotation" --explain # hybrid retrieval with score traces

# Retrieve documents or export context for an agent
gno get "gno://work-docs/architecture/auth.md"
gno multi-get "gno-code/**/*.ts" --max-bytes 30000 --md
gno query "deployment process" --all --files --min-score 0.35

# Run the workspace (pick one — don't run both against the same index concurrently)
gno serve            # browser/desktop session with the Web UI
gno daemon --detach  # headless continuous indexing (background; --status / --stop to manage)

---

Contents

• [Quick Start](#quick-start)
• [Installation](#installation)
• [Daemon Mode](#daemon-mode)
• [Search Modes](#search-modes)
• [Agent Integration](#agent-integration)
• [Web UI](#web-ui)
• [Publish to gno.sh](#publish-to-gnosh)
• [REST API](#rest-api)
• [SDK](#sdk)
• [How It Works](#how-it-works)
• [Features](#features)
• [Local Models](#local-models)
• [Fine-Tuned Models](#fine-tuned-models)
• [Architecture](#architecture)
• [Development](#development)

---

What's New

> Latest release: [v1.8.0](./CHANGELOG.md#180---2026-06-05) > Full release history: [CHANGELOG.md](./CHANGELOG.md)

• Second-brain capture: gno capture, REST /api/capture, SDK

client.capture(), MCP gno_capture, and Web UI Quick Capture write provenance-rich notes from text, stdin, or files, including typed presets for ideas, people, company/projects, and meetings

• Schema-lite content types: optional contentTypes rules map configured

frontmatter type values or path prefixes to canonical contentType metadata in JSON search/query results

• Publish to gno.sh: new gno publish export CLI and Web UI action produce a self-contained artifact you upload to the hosted reader — public, secret, invite-only, or locally encrypted before upload
• Retrieval Quality Upgrade: stronger BM25 lexical handling, code-aware chunking, terminal result hyperlinks, and per-collection model overrides
• Code Embedding Benchmarks: new benchmark workflow across canonical, real-GNO, and pinned OSS slices for comparing alternate embedding models
• Default Embed Model: built-in presets now use Qwen3-Embedding-0.6B-GGUF after it beat bge-m3 on both code and multilingual prose benchmark lanes
• Regression Fixes: tightened phrase/negation/hyphen/underscore BM25 behavior, cleaned non-TTY hyperlink output, improved gno doctor chunking and embedding fingerprint visibility, and fixed the embedding autoresearch harness

Upgrading Existing Collections

If you already had collections indexed before the default embed-model switch to Qwen3-Embedding-0.6B-GGUF, run:

gno models pull --embed
gno embed

That regenerates embeddings for the new default model. Old vectors are kept until you explicitly clear stale embeddings.

If the release also changes the embedding formatting/profile behavior for your active model, prefer one of these stronger migration paths:

gno embed --force

or per collection:

gno collection clear-embeddings my-collection --all
gno embed my-collection

If a re-embed run still reports failures, rerun with:

gno --verbose embed --force

Recent releases now print sample embedding errors and a concrete retry hint when batch recovery cannot fully recover on its own.

Model guides:

• [Code Embeddings](./docs/guides/code-embeddings.md)
• [Per-Collection Models](./docs/guides/per-collection-models.md)
• [Bring Your Own Models](./docs/guides/bring-your-own-models.md)

Fine-Tuned Model Quick Use

models:
  activePreset: slim-tuned
  presets:
    - id: slim-tuned
      name: GNO Slim Tuned
      embed: hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf
      rerank: hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf
      expand: hf:guiltylemon/gno-expansion-slim-retrieval-v1/gno-expansion-auto-entity-lock-default-mix-lr95-f16.gguf
      gen: hf:unsloth/Qwen3-1.7B-GGUF/Qwen3-1.7B-Q4_K_M.gguf

Then:

gno models use slim-tuned
gno models pull --expand
gno models pull --gen
gno query "ECONNREFUSED 127.0.0.1:5432" --thorough

> Full guide: Fine-Tuned Models · Feature page

---

Quick Start

gno init ~/notes --name notes    # Point at your docs
gno index                        # Build search index
gno daemon --detach              # Keep index fresh in the background (macOS/Linux)
gno query "auth best practices"  # Hybrid search
gno ask "summarize the API" --answer  # AI answer with citations

Manage the detached process with gno daemon --status and gno daemon --stop.

---

Installation

Install GNO

Requires Bun >= 1.0.0.

bun install -g @gmickel/gno

macOS: Vector search requires Homebrew SQLite:

brew install sqlite3

Verify everything works:

gno doctor

Windows: current validated target is windows-x64, with a packaged desktop beta zip now published on GitHub Releases. See [docs/WINDOWS.md](./docs/WINDOWS.md) for support scope and validation notes.

Keep an index fresh continuously without opening the Web UI:

gno daemon            # foreground (Ctrl+C to stop)
gno daemon --detach   # background (macOS/Linux); use --status / --stop to manage

gno daemon runs the watch/sync/embed loop headless. --detach self-spawns a detached child and exits 0; gno daemon --status and gno daemon --stop give you lifecycle control without nohup, launchd, or systemd units.

See also: [docs/DAEMON.md](./docs/DAEMON.md)

Connect to AI Agents

MCP Server (Claude Desktop, Cursor, Zed, etc.)

One command to add GNO to your AI assistant:

gno mcp install                      # Claude Desktop (default)
gno mcp install --target cursor      # Cursor
gno mcp install --target claude-code # Claude Code CLI
gno mcp install --target zed         # Zed
gno mcp install --target windsurf    # Windsurf
gno mcp install --target codex       # OpenAI Codex CLI
gno mcp install --target opencode    # OpenCode
gno mcp install --target amp         # Amp
gno mcp install --target lmstudio    # LM Studio
gno mcp install --target librechat   # LibreChat

Check status: gno mcp status

Skills (Claude Code, Codex, OpenCode, OpenClaw)

Skills integrate via CLI with no MCP overhead and include second-brain recipe playbooks:

gno skill install --scope user        # User-wide
gno skill install --target codex      # Codex
gno skill install --target opencode   # OpenCode
gno skill install --target openclaw   # OpenClaw
gno skill install --target all        # All targets

> Full setup guide: MCP Integration · CLI Reference

---

Daemon Mode

Use gno daemon when you want continuous indexing without the browser or desktop shell open.

gno daemon                  # foreground (Ctrl+C to stop)
gno daemon --no-sync-on-start
gno daemon --detach         # background (macOS/Linux); auto-writes pid + log files
gno daemon --status         # check the detached process
gno daemon --stop           # SIGTERM with 10s timeout, SIGKILL fallback

It reuses the same watch/sync/embed runtime as gno serve, but stays headless. --detach / --status / --stop give you symmetric lifecycle controls so you don't need nohup, launchd, or systemd units. The same flag set is available on gno serve.

Daemon guide →

---

SDK

Embed GNO directly in another Bun or TypeScript app. No CLI subprocesses. No local server required.

Install:

bun add @gmickel/gno

Minimal client:

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.query("JWT token flow", {
  noExpand: true,
  noRerank: true,
});

console.log(results.results[0]?.uri);
await client.close();

More SDK examples:

import { createGnoClient } from "@gmickel/gno";

const client = await createGnoClient({
  configPath: "/Users/me/.config/gno/index.yml",
});

// Fast exact search
const bm25 = await client.search("DEC-0054", {
  collection: "work-docs",
});

// Semantic code lookup
const semantic = await client.vsearch("retry failed jobs with backoff", {
  collection: "gno-code",
});

// Hybrid retrieval with explicit intent
const hybrid = await client.query("token refresh", {
  collection: "work-docs",
  intent: "JWT refresh token rotation in our auth stack",
  candidateLimit: 12,
});

// Fetch content directly
const doc = await client.get("gno://work-docs/auth/refresh.md");
const bundle = await client.multiGet(["gno-code/**/*.ts"], { maxBytes: 25000 });

// Indexing / embedding
await client.update({ collection: "work-docs" });
await client.embed({ collection: "gno-code" });

await client.close();

Core SDK surface:

• createGnoClient({ config | configPath, dbPath? })
• search, vsearch, query, ask
• get, multiGet, list, status
• update, embed, index
• close

Full guide: SDK docs

---

Search Modes

| Command | Mode | Best For | | :----------------- | :------------------ | :---------------------------------------- | | gno search | Document-level BM25 | Exact phrases, code identifiers | | gno vsearch | Contextual Vector | Natural language, concepts | | gno query | Hybrid | Best accuracy (BM25 + vector + reranking) | | gno ask --answer | RAG | Direct answers with citations |

BM25 indexes full documents (not chunks) with Snowball stemming, so "running" matches "run". Vector embeds chunks with document titles for context awareness. All retrieval modes also support metadata filters: --since, --until, --category, --author, --tags-all, --tags-any.

gno search "handleAuth"              # Find exact matches
gno vsearch "error handling patterns" # Semantic similarity
gno query "database optimization"    # Full pipeline
gno query "meeting decisions" --since "last month" --category "meeting,notes" --author "gordon"
gno query "performance" --intent "web performance and latency"
gno query "performance" --exclude "reviews,hiring"
gno ask "what did we decide" --answer # AI synthesis

Output formats: --json, --files, --csv, --md, --xml

Common CLI Recipes

# Search one collection
gno search "PostgreSQL connection pool" --collection work-docs

# Export retrieval results for an agent
gno query "authentication flow" --json -n 10
gno query "deployment rollback" --all --files --min-score 0.4

# Retrieve a document by URI or docid
gno get "gno://work-docs/runbooks/deploy.md"
gno get "#abc123"

# Fetch many documents at once
gno multi-get "work-docs/**/*.md" --max-bytes 20000 --md

# Inspect how the hybrid rank was assembled
gno query "refresh token rotation" --explain

# Work with filters
gno query "meeting notes" --since "last month" --category "meeting,notes"
gno search "incident review" --tags-all "status/active,team/platform"

# Export a publish artifact for gno.sh
gno publish export work-docs --out ~/Downloads/work-docs.json
gno publish export "gno://work-docs/runbooks/deploy.md" --out ~/Downloads/deploy.json
# Or let GNO choose your Downloads folder automatically
gno publish export work-docs

The local web UI exposes the same export flow:

• Collections page → collection menu → Export for gno.sh
• Document view → Export for gno.sh

Both actions download the same JSON artifact the CLI writes, ready for upload at https://gno.sh/studio.

Retrieval V2 Controls

Existing query calls still work. Retrieval v2 adds optional structured intent control and deeper explain output.

# Existing call (unchanged)
gno query "auth flow" --thorough

# Structured retrieval intent
gno query "auth flow" \
  --intent "web authentication and token lifecycle" \
  --candidate-limit 12 \
  --query-mode term:"jwt refresh token -oauth1" \
  --query-mode intent:"how refresh token rotation works" \
  --query-mode hyde:"Refresh tokens rotate on each use and previous tokens are revoked." \
  --explain

# Multi-line structured query document
gno query $'auth flow\nterm: "refresh token" -oauth1\nintent: how refresh token rotation works\nhyde: Refresh tokens rotate on each use and previous tokens are revoked.' --fast

• Modes: term (BM25-focused), intent (semantic-focused), hyde (single hypothetical passage)
• Explain includes stage timings, fallback/cache counters, and per-result score components
• gno ask --json includes meta.answerContext for adaptive source selection traces
• Search and Ask web text boxes also accept multi-line structured query documents with Shift+Enter

---

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gmickel
• Source: gmickel/gno
• License: MIT
• Homepage: https://www.gno.sh

Install and usage instructions live in the source repository linked above.