Open Knowledge

Open Knowledge turns repository Markdown into managed, searchable knowledge for people and agents. One lifecycle covers setup, checks, review, format upgrades, and publication to a static viewer or MCP runtime.

🌐 Website | 📖 Documentation | 🧭 Commands | 📝 Changelog | 📐 OKF specification | ⚖️ License

The knowledge lifecycle

Markdown + Git ──► deterministic checks ──► evidence-backed PR
      ▲                                      │
      └──── rollback ◄── production MCP ◄────┘

Quick start

1. Install

curl -fsSL https://openknowledge.sh/install | bash

2. Set up

Run the interactive setup wizard:

okn setup

Setup discovers Markdown across the repository. The Markdown does not need YAML frontmatter or authored links. Select paths in the CLI, then create a managed copy or adopt one directory in place.

If setup finds no Markdown, it creates a task for an agent. An installed agent appears first. You can also copy the task or save it to a file.

To use an agent that already works inside the project, copy this prompt:

Set up Open Knowledge for this workspace. Check the CLI with `okn version`.
If it is missing, install it from https://openknowledge.sh/install and verify
the installation. Then run `okn setup --prompt` and follow its complete task.
Ask me before product-level decisions. Finish with the printed `okn validate`
and `okn search` commands.

The generated task is the source of truth for the setup workflow. The default target is Wiki.

To let the CLI launch an installed agent runtime, run:

okn setup --agent <codex|claude|opencode>

Agent mode runs the same generated task. It creates and validates the wiki.

3. Check

When the agent finishes:

okn check Wiki

check reports one status from the configured validation, link, freshness, retrieval, claims, and publication layers.

4. Search, review, or browse

okn search Wiki "release workflow"
okn review Wiki
okn view Wiki

Alternative npm installation

npm install -g @openknowledge-sh/openknowledge

Both installers provide okn and openknowledge. This documentation uses okn. See Installation for supported platforms and verification details.

Before the CLI sends its first event, it discloses anonymous usage and sanitized error telemetry. Telemetry is enabled by default. Run okn telemetry show-payload to inspect a sample. Put --no-telemetry before a command to disable telemetry and save the opt-out. See Product Telemetry and Privacy.

Optional controls

The local knowledge workflow does not require typed claims, Knowledge CI, or a production runtime.

Add Knowledge CI when pull requests must verify knowledge quality. Add the runtime when clients need a production MCP service:

okn setup github Wiki
okn setup runtime Wiki

The GitHub profile adds an Action-first workflow, source baseline, starter eval questions, and config-driven gates. The runtime profile publishes immutable generations with explicit passing or degraded health. See the complete Knowledge CI Golden Path.

Workflows

Start here

Use setup to create or adopt knowledge. Use check to get one health status. Use search to retrieve managed or unmanaged Markdown. Use view to browse a bundle. Use review for an optional agent review. Use publish for configured output. Use upgrade for OKF format changes.

Advanced

The CLI retains direct validation, audit, claims, evidence, eval, quality, query, export, MCP, connection, automation, and agent tools. Root help groups these lower-level controls under Advanced.

See the command index for all commands. Use okn <command> --help for exact command syntax.

Publish a wiki

okn publish builds configured output only after okn check permits it. Unmanaged Markdown and blocked knowledge cannot be published.

Review the knowledge base before you create this bundle. After you enable publication, Markdown is public unless it sets okf_publish: false. Add this configuration to Wiki/.openknowledge.toml:

[release]
outputs = ["viewer"]

Inspect the plan, then publish the reviewed content:

okn publish Wiki --target viewer --out ./site --plan
okn publish Wiki --target viewer --out ./site

The bundle includes a static viewer, llms.txt, a connect manifest, and a portable source archive. Add "mcp" to release.outputs when a deployed runtime should also expose HTTP MCP. See HTML export and .openknowledge.toml for publication filters and asset options. The advanced okn export html command remains available for direct exporter control.

Development

pnpm install --frozen-lockfile
pnpm test
pnpm build

See CLI operations for focused test, build, website, and release commands.

License and attribution

Open Knowledge is licensed under Apache-2.0.

The embedded OKF specification is Apache-2.0 material from GoogleCloudPlatform/knowledge-catalog. See THIRD_PARTY_NOTICES.md for attribution.