OpenKB — Technical Briefing
Overview
OpenKB is a Python-based CLI system (51 files) that compiles raw documents into a structured, interlinked wiki-style knowledge base using LLMs. It integrates with PageIndex for vectorless long-document retrieval and supports multi-modality (figures, tables, images). The codebase is Python-heavy (41 of 51 files) with a CLI entry point and modular agent architecture.
Architecture & Core Components
The system follows a document-to-wiki pipeline:
raw/ incoming files → markitdown/PageIndex preprocessing → LLM compilation → wiki output (markdown with [[wikilinks]])
Key modules in openkb/ include:
| Module | Purpose |
|---|---|
| converter.py | Document format conversion (PDF, Word, Markdown, PPT, HTML, Excel via markitdown) |
| indexer.py | PageIndex tree indexing for long documents |
| agent/ | Chat, query, compiler, lint, and tooling logic |
| cli.py | Command-line interface |
| main.py | Package entry point |
The agent/ subpackage contains 7 files handling chat sessions, query execution, compilation, linting, and tool management. The watcher.py module enables watch mode for automatic wiki updates when files are dropped into raw/.
Configuration & Setup
pyproject.toml — Project metadata and dependencies (no lockfile present, flagged as a reproducibility risk) .env.example — Template for LLM API key configuration (LLMAPIKEY) config.yaml.example — Configuration template for openkb init, specifying provider/model in LiteLLM format (e.g., anthropic/claude-sonnet-4-6 or bare gpt-5.4) .openkb/config.yaml — Runtime config written after initialization
Installation options documented: pip install openkb pip install git+https://github.com/VectifyAI/OpenKB.git (latest from GitHub) git clone + pip install -e . (editable/development)
Detected Issues
| Severity | Issue | Evidence |
|---|---|---|
| Low/Risk | Dependencies declared without a lockfile — non-reproducible builds | pyproject.toml present but no uv.lock, requirements.txt, or Pipfile.lock detected. Pinning and reproducibility rely on the package index at install time. |
No lockfile means pip install openkb may resolve to different dependency versions across environments. For a tool claiming "scale to long documents" and "compiled wiki" use cases, this is a non-trivial reproducibility risk, especially when LLM provider versions and SDKs affect behavior.
Test & CI Status
20 test files under tests/ covering CLI, config, compiler, chat sessions, converter, indexer, lint, markdown renderer, query, state, tree renderer, and watcher GitHub Actions CI configured via .github/workflows/publish.yml Test coverage appears comprehensive across the module boundary layers (CLI → agent → core)
Honest Assessment
OpenKB is a functional, well-structured CLI tool for LLM-powered knowledge base compilation. The PageIndex integration for long-document retrieval without vectors is a genuine differentiator from traditional RAG approaches. Multi-modality support (images, tables via markitdown) and Obsidian-compatible markdown output are practical features that lower adoption friction.
The absence of a lockfile is the most concrete risk — it undermines the "compile once, keep current" premise if dependency drift changes LLM behavior between runs. Adding uv.lock or migrating to requirements.txt with pinned pins would resolve this in under five minutes.
Who should use it: Teams or individuals who need to convert a corpus of mixed-format documents into a navigable, LLM-managed wiki and who are already comfortable configuring LiteLLM providers. Not ideal for environments requiring strict reproducibility without lockfile management.
Who should look elsewhere: Organizations requiring out-of-the-box reproducibility guarantees without configuration, or projects needing vector-based retrieval only (OpenKB explicitly positions itself as "vectorless").
Briefing complete. Evidence drawn from directory structure, pyproject.toml, test inventory, and README-sourced install commands. No lockfile = reproducibility risk; otherwise solid modular design.