openknowledge

README

Open Knowledge

Git-native CI and an MCP runtime for agent knowledge. Open Knowledge finds stale, conflicting, and missing knowledge, prepares evidence-backed fixes, runs deterministic retrieval and evidence regressions, and serves the current production version with explicit passing or degraded health.

🌐 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. Create

Run the interactive setup wizard:

okn setup

This command uses the base preset by default. It creates a lightweight knowledge base for repository documentation, architecture, services, decisions, and changelog content.

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. Validate

When the agent finishes:

okn validate Wiki

4. Search or browse

okn search Wiki "release workflow"
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 upgrades

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

Use the trusted preset when the knowledge base needs explicit sources, evidence, claim lifecycle, or conflict checks:

okn setup --use-case trusted

Use okn setup --use-case custom when neither preset matches the intended result. All presets use the same Markdown and OKF format. A preset changes the setup task and starter content, not the knowledge format.

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 for interactive onboarding. Use okn setup --prompt for an existing agent. Use okn setup --agent <runtime> to launch one. Use validate to verify the wiki. Use search to retrieve knowledge. Use view to browse the wiki.

Trust and govern

Use audit to find knowledge risks. Use claims and evidence for trusted facts. Use eval and quality to measure results.

Query and interchange

Use query for explicit semantic queries. Use export to create portable output.

Publish and operate

Use mcp to serve MCP tools. Use connect and registry to manage sources. Use automation for jobs and deployments.

Advanced internals

Use agent for an agent task. Use get and list for direct inspection. Other advanced tools are scaffold, prompt, ast, and spec.

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

Publish a wiki

okn export html creates a public distribution bundle in a local folder. It does not deploy the bundle or start an MCP server.

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"]

Export the reviewed content:

okn export html --out ./site Wiki

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.

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.