Knowl

Your project knowledge, maintained as a wiki.

Knowl is a self-hosted LLM wiki for your projects. It turns source documents into connected Markdown pages and gives AI agents grounded evidence from that wiki. Knowledge remains available across tasks, with references back to the sources that support it.

Knowl builds on Andrej Karpathy's LLM Wiki pattern: an agent reads sources and maintains connected knowledge over time. Bring your own ACP-compatible agent to maintain the wiki. Your knowledge stays in portable, Open Knowledge Format (OKF) Markdown under your control.

Get started · Browse the wiki · See Knowl's own wiki · Documentation

What You Get

| Need | What Knowl provides | | --- | --- | | Keep project knowledge across tasks | An LLM-maintained wiki built from durable source revisions | | Understand where a result came from | Bounded evidence linked to its supporting sources | | Own and inspect your knowledge | Plain Markdown in an OKF-compatible workspace | | Read the wiki in your browser | An optional read-only console for pages, saved sources, search, and processing history | | Find related evidence across different wording | Optional hybrid search through your own embedding API or local CPU server | | Choose where it runs | Local Codex, a self-hosted MCP/HTTP service, or an embedded Go runtime |

From Sources to a Wiki

Connect project sources or start from an existing Markdown wiki, Obsidian vault, or OKF bundle. Knowl preserves accepted source revisions, and the configured LLM maintainer proposes semantic updates to the wiki. Updates pass validation before they become part of the knowledge base.

A URL submission stores a reference. To use the page's contents as a source, submit its text. See the ingest examples.

Your agent retrieves relevant evidence and uses it to answer or act. You can also read the wiki directly, inspect its source references, or export it for publishing. See the source-to-wiki example for a complete walkthrough.

Get Started

| Local | Service | | --- | --- | | Keep a wiki alongside your project and use a local ACP agent to maintain it. | Run a persistent Knowl service and connect clients over MCP or HTTP. | | Local quickstart with Codex | Service quickstart |

Both guides take you from a source document to a published wiki page and a retrieval result. Choose your maintainer in the agent guide, including a custom agent through generic_acp over stdio.

The container quickstart is now in the service guide.

Knowl Uses Knowl

Knowl maintains a wiki of its own documentation. Compare the source docs with the generated wiki to see source material become connected knowledge. The walkthrough explains the configured ACP agent, generation commands and saved source provenance.

Connect an Agent

Local Codex plugin

Use Knowl from a local Codex project with setup and maintenance skills plus MCP tools. For the v0.8.0 npm release, setup is:

npx --yes @baldaworks/[email protected] setup codex

The npm instructions require that release to be published. After setup, start a new Codex thread and use $knowl:run for one bounded wiki maintenance cycle. See the local Codex guide for requirements, provider configuration, offline use, and supported scope.

MCP and HTTP

Connect other agents to the self-hosted service over MCP. Knowl exposes three tools: knowl_retrieve for evidence, knowl_ingest for durable inputs, and knowl_operation for operation status.

The same capabilities are available through HTTP. See service connection guide, service operations, and the OpenAPI contract.

Knowl can request one corrected plan when generated output fails validation. Inspect the result through operation status, or disable correction in your config.

Go applications

Embed Knowl through pkg/knowl, or use pkg/knowlfx for Fx lifecycle integration. See the product design for runtime composition and ownership boundaries.

Read Your Wiki in a Browser

Enable the optional web UI to browse published pages, inspect their saved source revisions, retrieve evidence, and follow maintenance status. It runs inside the Go service with locally bundled assets and is disabled by default. Connect with an operator token; use HTTPS when exposing the service beyond loopback.

Search Across Different Wording

Enable optional embeddings to retrieve related evidence across paraphrases and word forms. Knowl combines semantic and keyword search while keeping the original page text and source references in its results. The semantic index covers the full text of each published page within the configured projection capacity; a dense-only match shows the matching passage as its excerpt.

Use your own compatible embedding API or the local CPU embedding server. Dense scoring runs natively inside SQLite or optional operator-provisioned pgvector; see deployment/rebuild guidance and the actual performance comparison. Zero stored-vector transfer does not promise faster queries: current paired measurements remain mixed, and the original full-query regressions are retained. Full integrity is established before atomic publication; ordinary reads check scalar readiness, snapshot/model compatibility and consumed evidence. Lexical-only remains the default. Embeddings are off by default. Choose explicit keyword fallback or strict semantic availability in the search guide.

Keep Your Knowledge Portable

The canonical wiki lives in wiki/ as an OKF v0.2 bundle. Accepted source revisions are preserved separately in raw/, so semantic pages remain connected to their evidence. The default local operational store uses SQLite.

Export the wiki as a standalone bundle, or add an llms.txt navigation file for agents and publication. See workspace and export for the layout and commands.

Documentation By Goal

| Goal | Start here | | --- | --- | | Run a local wiki with Codex | Local quickstart | | Run Knowl as an MCP/HTTP service | Service quickstart | | Bring your own ACP agent | Agent configuration | | Use the Codex plugin | Codex integration | | Browse the wiki | Web UI | | Configure lexical or hybrid search | Search | | See Knowl maintain its own wiki | Own-docs walkthrough | | Operate and recover Knowl | Operations | | Understand storage and export | Workspace and OKF | | Embed Knowl in Go | Go application integration |

See the documentation index for architecture, API contracts, quality measurements and release history.

License

Knowl is released under the MIT License.