OpenKB Documentation

The wiki/ directory is the compiled knowledge artifact of your knowledge base. It contains synthesized summaries, concepts, and entities.

Important: Do not modify files in the raw/ directory. For internal state (config, hash registry, PageIndex DB), do not read <kb-root>/.openkb/ directly; instead, use openkb status or openkb list to inspect the state.

OpenKB provides several specialized workflows and artifacts depending on your needs:

• Configuration: Setting up config.yaml, managing API keys, and tuning LiteLLM (e.g., Ollama, Copilot).
• Commands: The standard lifecycle loop using add, query, remove, recompile, lint, list, and status.
• Page Indexing: Managing long documents via local vs. cloud indexing.
• Chat: Using the interactive REPL with persistent sessions and slash commands.
• Skills: Distilling redistributable agent skills from your wiki (outputs SKILL.md).
• Slides: Generating single-file HTML slide decks.
• Visualization: Rendering the wiki as an interactive knowledge graph (graph.html).

OpenKB organizes ingested data into a Markdown wiki located at <kb>/wiki/. The directory structure includes:

• wiki/concepts/*.md: Cross-document synthesis on specific topics.
• wiki/entities/*.md: Pages for specific named things (people, organizations, etc.). Each has a type: field in the frontmatter.
• wiki/summaries/*.md: One per ingested document, linking to related concepts.
• wiki/sources/*.md: Full text for short documents.
• wiki/sources/*.json: Paginated content for long PDFs.

You can view a high-level overview of all available content by reading <kb>/wiki/index.md or by running openkb list to see a table of ingested documents and concepts.

You can trigger the openkb-html-critic skill to review a generated HTML deck or single-page artifact for visual quality and structural correctness. This skill is designed to catch CSS specificity bugs, navigation issues, and self-containment failures.

Invocation Methods:

• CLI: Use the command openkb deck new --critique.
• Chat: Use the command /critique <path> where <path> is the path to the HTML file under output/.

For diagnostic purposes, do not use bare print statements. Instead, use the centralized logging module to ensure consistent diagnostic output:

• Use openkb/log.py for all logging.

Use openkb init to create a new knowledge base directory structure. This command is interactive by default, prompting for the LLM model (in LiteLLM provider/model format), the LLM API key, and the output language.

To automate initialization in scripts or CI/CD, use flags to skip prompts. Note that if stdin is not a TTY, init will use defaults instead of hanging.

# Create directory and initialize
mkdir my-kb && cd my-kb
openkb init

# Non-interactive initialization with flags
openkb init --model anthropic/claude-sonnet-4-6 --language en
openkb init -m gpt-5.4 -l zh

# Scripted initialization via pipe
printf 'gpt-5.4\n\nen\n' | openkb init

OpenKB includes a bundled single-page application called the Knowledge Workbench served directly by the REST server. To use the web interface, install the package with the [web] extra and start the server using the openkb-web command.

Installation

Install the package with the web extra via pip:

pip install "openkb[web]"

Running the Server

Start the server to serve both the API and the Workbench at http://127.0.0.1:7566/:

openkb-web --host 127.0.0.1 --port 7566

OpenKB uses LiteLLM to support multiple providers (OpenAI, Claude, Gemini, etc.).

1. Set the model: During openkb init or in the .openkb/config.yaml file, use the provider/model format (e.g., anthropic/claude-sonnet-4-6). OpenAI models can omit the prefix (e.g., gpt-5.4).
2. Set the API Key: Create a .env file in your knowledge base directory with the following variable: LLM_API_KEY=your_llm_api_key

OpenKB includes a FastAPI service for HTTP clients.

1. Install the web dependencies: pip install -e ".[web]"
2. Start the service: python -m openkb.api

The interactive API documentation (Swagger/OpenAPI) is available at http://127.0.0.1:7566/docs and can be imported into Postman.

To find the absolute path of the active knowledge base, run openkb status. The first line of output, Knowledge base: <path>, provides the absolute path required for all subsequent file operations.

If openkb status returns "No knowledge base found", you must either cd into a directory containing an .openkb/ folder or run openkb init to create a new one.

$ openkb status
Knowledge base: /Users/.../my-kb