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.