okf-search

Search local Open Knowledge Format (OKF) Markdown from Pi, Node.js, or a browser.

This monorepo contains a native Rust/Tantivy search backend, the Pi package built on it, and a JavaScript MiniSearch backend for browsers and Node.js. All three build in-memory indexes; no search service is required.

Choose a package

Package	Use it for	Search engine
okf-search-native	Node.js applications on a supported native platform	Rust and Tantivy
okf-minisearch	Browser applications, or an ESM-only Node.js backend	MiniSearch
pi-okf-search	Searching a local OKF directory from Pi	okf-search-native

Use okf-search-native for Node-only applications that can use its prebuilt native addons. Use okf-minisearch when you need browser support. All three packages apply the same OKF parsing and validation rules. Their ranking, scores, snippets, and fuzzy matches can differ.

Use the Rust/Tantivy backend from Node.js

npm install okf-search-native

Given an OKF Markdown tree in ./knowledge:

import { openOkf } from "okf-search-native";

const index = await openOkf("./knowledge");
const [hit] = index.search("rollback snapshot", { limit: 1 });

if (!hit) throw new Error("No matches.");

console.log({
  title: hit.title,
  path: hit.path,
  headingPath: hit.headingPath,
  startLine: hit.startLine,
  endLine: hit.endLine,
  snippet: hit.snippet,
});

okf-search-native can also index Markdown already in memory, validate documents, add or replace documents, remove documents from the current index, and accept prepared documents through okf-search-native/prepared. See the native package guide for its complete API and supported platforms.

Use the JavaScript backend

Install okf-minisearch for Node.js or a bundled browser application:

npm install okf-minisearch

Its package-root API also provides openOkf, createOkfSearch, document validation, in-memory updates, and search. It additionally supports browser-selected files and autoSuggest.

Without a bundler, load its browser API from a CDN:

<script src="https://cdn.jsdelivr.net/npm/okf-minisearch@2"></script>

See the okf-minisearch guide for Node.js, browser, search, and auto-suggest examples.

Use from Pi

Install the package:

pi install npm:pi-okf-search

Add the directory to ~/.pi/agent/settings.json:

{
  "pi-okf-search": {
    "root": "/absolute/path/to/knowledge"
  }
}

Start Pi and ask it to search:

Search the knowledge base to find the rollback procedure.

The package gives Pi one read-only okf_search tool. Results include the source path and inclusive line range so Pi can reopen the exact passage with read. Run /okf status to inspect the loaded snapshot and /okf refresh after files change.

See the pi-okf-search guide for configuration, query behavior, result interpretation, refreshes, and platform requirements.

How the packages fit together

                         ┌─ okf-search-native ── Node.js
OKF Markdown ─ preparation
                         └─ okf-minisearch ───── Node.js or browser

pi-okf-search ── okf-search-native ── okf_search tool in Pi

The public backends share the repository's OKF parsing, validation, document preparation, filters, and result model. When given a directory, they recursively load lowercase .md files, excluding files named exactly index.md and log.md. Search returns at most one best-matching section per document, and both strict and degraded OKF documents are searchable by default.

Indexes remain in memory. Adding or removing a document changes the active index, not its source file. Reopening a directory rebuilds the index from disk.

Requirements

Package	Runtime
okf-search-native	Node.js >=22.19.0; macOS x64/arm64 and Linux x64 with glibc >=2.17; Windows x64 is experimental
pi-okf-search	Node.js >=22.19.0 and the same native platforms as okf-search-native
okf-minisearch	Node.js >=20 for directory loading, or a modern browser; ESM only

The native packages do not support browsers, Linux musl/Alpine, Linux arm64, or Windows arm64. Check the native platform matrix before deploying.

Browser demo

Try the okf-minisearch browser demo. It searches a sample corpus and validates selected Markdown entirely in memory.

Development

The full workspace requires Node.js >=22.19.0, pnpm 11.22.0, and Rust 1.88.0.

pnpm install
pnpm package:check

pnpm package:check performs the full build, Rust checks, type checks, tests, and packed-package consumer checks.

Build and test one package with pnpm filters:

pnpm --filter okf-search-native build
pnpm --filter okf-search-native test
pnpm --filter okf-minisearch test
pnpm --filter pi-okf-search test

Run the Pi extension from this checkout after building the native backend:

pnpm --filter okf-search-native build
pi -e ./packages/pi-okf-search/extensions/okf-search/index.ts

Learn about OKF

• OKF v0.2 specification
• okf-search-native documentation
• pi-okf-search documentation
• okf-minisearch documentation

License

Released under the MIT License.