KaaS
README.md
<img src="docs/assets/logo.svg" align="right" width="110" alt="KaaS — Knowledge-as-a-Service">
# KaaS — Knowledge as a Service
**English** · [中文](README.zh-CN.md)
[](https://github.com/bybit-exchange/kaas/actions/workflows/tests.yml)
[](LICENSE)
[](https://github.com/bybit-exchange/kaas/releases)
[](https://bybit-exchange.github.io/kaas-doc/)
[](#mcp-access)
Turn scattered notes, documents, and transcripts into a searchable, queryable personal Wiki — powered by LLM-driven knowledge compilation.
**[Documentation](https://bybit-exchange.github.io/kaas-doc/)** · [Quick Start](#quick-start) · [MCP access](#mcp-access)
## What Makes This Different
Unlike typical RAG systems that chunk and embed raw text, KaaS **compiles** your
content through a 4-phase LLM pipeline. What comes out is human-readable Markdown
articles — not a black-box vector store.
## The Compiled Wiki
What you get is a tree of Markdown articles: categories on the left, the rendered
article in the middle, its headings down the right. Chat answers cite these
articles by name, so an answer and the page it came from are one click apart.
## How It Works
Raw content passes through four LLM phases: extract concepts, entities and
decisions; classify them into articles; write or merge the Markdown; update the
indexes. Retrieval then reads whole pages rather than embedded fragments — the
LLM walks the master index, picks the articles it needs, and answers from their
full text.
## Why We Built This
KaaS started as an internal tool. Our knowledge lived scattered across
documents, meetings, and email — and every time someone changed roles or left,
the context they'd built up walked out with them. New people spent weeks
piecing it back together.
A distillation pipeline fixed that. It compiles each person's scattered
material into a wiki tied to their _role_ rather than their identity — so when
someone moves on, the raw data goes but the distilled judgment stays for whoever
fills the seat next.
The payoff is the same either way: the organization stops re-answering the same
questions. That's what convinced us it was worth open-sourcing.
## Quick Start
KaaS calls LLMs through any **OpenAI-compatible** API (OpenAI, DeepSeek, Ollama, vLLM, Azure OpenAI, etc.). Pick one of the three paths below.
### Option A: Your AI agent
Already living in a coding agent (Claude Code, Codex, openclaw, …)? Give it this
repository's URL and ask for what you want — it can do the whole setup. Or paste
this to save it a step:
```
Set up KaaS to build a queryable knowledge base from my files.
Fetch https://raw.githubusercontent.com/bybit-exchange/kaas/main/docs/agent-quickstart.md
and follow it exactly.
```
> **If you are an AI agent reading this**: fetch
> [`docs/agent-quickstart.md`](docs/agent-quickstart.md) and follow that instead of
> the shell snippets below. It routes the three things users ask for — build a wiki
> from their files, run the full service with the web UI, or point your `ask` tool
> at a KaaS that already exists — and marks where to stop and ask them.
That snippet asks for one specific outcome: the AI engine and a queryable wiki, no
web UI. Ask your agent for the web UI instead and the runbook sets up the full
service — which is the same ground Options B and C cover, written for a human to
run by hand.
### Option B: Docker
```bash
docker run -d --name kaas \
-p 8080:8080 \
-v ./data:/app/data \
-e LLM_API_KEY=sk-xxx \
-e LLM_BASE_URL=https://api.openai.com/v1 \
-e LLM_MODEL=gpt-4o-mini \
ghcr.io/bybit-exchange/kaas:edge
```
Prebuilt for `linux/amd64` and `linux/arm64`. `edge` tracks `main`. From the
first stable release there will also be version tags and `latest` — pin a
version for anything you actually depend on. To build from source instead:
`docker build -t kaas .`
### Option C: CLI install
```bash
# Install (Linux amd64/arm64, macOS arm64)
curl -fsSL https://raw.githubusercontent.com/bybit-exchange/kaas/main/install.sh | sh
# Start the service
export PATH="$HOME/.kaas:$PATH" # where the installer put the binary
export LLM_API_KEY="sk-xxx" # OpenAI-compatible API key
export LLM_BASE_URL="https://api.openai.com/v1" # API endpoint
export LLM_MODEL="gpt-4o-mini" # Model name
kaas serve # Default: http://localhost:8080
```
Supported platforms: Linux amd64/arm64 and macOS arm64 (Apple Silicon); there is
no darwin/amd64 build, so Intel Macs need Option A or B. The binary is symlinked into
`~/.kaas`, which the installer will tell you to add to PATH. Uninstall:
`rm -rf ~/.local/share/kaas ~/.kaas/kaas`.
### After it starts (Options B and C)
`LLM_BASE_URL` defaults to `https://api.openai.com/v1` and `LLM_MODEL` defaults to
`gpt-4o-mini`. Change them to point at any OpenAI-compatible endpoint, then open
http://localhost:8080.
Running from a checkout instead of a release? See [Development](#development).
### Enable remote MCP (optional)
To let Claude Code or other MCP clients connect to the knowledge base, set
`KAAS_MCP_ENABLED=true`. Environment variables override `kaas.toml` on every
start, so this works for both Docker and `kaas serve`:
```bash
docker run -d --name kaas \
-p 8080:8080 \
-v ./data:/app/data \
-e LLM_API_KEY=sk-xxx \
-e KAAS_MCP_ENABLED=true \
-e KAAS_MCP_TOKEN=your-secret-token \
ghcr.io/bybit-exchange/kaas:edge
```
MCP client URL: `http://<host>:8080/mcp`, Authorization: `Bearer your-secret-token`.
## Architecture
| Layer | Tech | Purpose |
|-------|------|---------|
| Web UI | React + Vite + shadcn/ui | Chat, Submit, Wiki, Status |
| Backend | Go (net/http + go-zero/conf) | REST API, Worker Pool, Task Queue, MCP endpoint |
| AI Engine | Python (kb-ai daemon) | LLM Compile Pipeline, LLM-iterative retrieval, Chat |
| Storage | SQLite (default) / MySQL | Job queue, compile state |
| Retrieval | LLM iterative | master-index → LLM page selection → full-article context (no embeddings) |
The Go backend spawns the Python AI engine as a long-running daemon process, communicating via a multiplexed stdin/stdout protocol. A single Docker image bundles everything — no sidecar containers needed.
## Features
- **Readable articles**: what you query is pages, not ranked fragments — see [How It Works](#how-it-works) for the four phases that produce them
- **Answers you can check**: every chat reply cites the wiki articles behind it, so you can open the source and disagree with it (streamed over SSE)
- **A knowledge base you own**: articles are plain Markdown on disk — read them, hand-edit them, commit them, review a diff
- **Adding one document costs one document**: compiles are incremental against a content checksum, so a new note doesn't re-pay for the corpus you already compiled
- **A long run survives its own failures**: extract and pipeline work runs concurrently; tasks are leased, so a worker that dies mid-compile has its work reclaimed rather than lost, and repeated LLM failures trip a breaker instead of burning spend
- **Text, a file, or a URL**: paste it, upload it, or point KaaS at a page
- **Reachable from your editor**: any MCP-capable coding agent queries the compiled wiki through a single `ask` tool
## MCP Access
Expose the compiled wiki to any [Model Context Protocol](https://modelcontextprotocol.io)
client (Claude Code, Codex, openclaw, …) through a single `ask` tool —
`ask(query, paths?, model?)` returns a cited Markdown answer grounded in the
wiki. Two transports:
**stdio** (local — the agent spawns the server, fully self-contained):
```bash
# The agent launches this; set KAAS_KB_DIR to the knowledge-base root and
# the LLM_* credentials in the environment.
kb-ai mcp # stdio is the default transport
```
```bash
# Claude Code:
claude mcp add kaas -- kb-ai mcp
```
For Codex / openclaw, add a stdio MCP server with command `kb-ai mcp` and env
`KAAS_KB_DIR` + `LLM_*`.
**streamable-http** (remote — published through the backend's `:8080` origin):
Run the container with `KAAS_MCP_ENABLED=true` (see [Quick Start](#quick-start)).
The backend exposes the MCP endpoint at `/mcp`. Point a remote agent at it:
```bash
# Claude Code:
claude mcp add --transport http kaas http://host:8080/mcp
```
Set `KAAS_MCP_TOKEN` to require `Authorization: Bearer <token>` on the HTTP
transport (off by default — local/intranet assumption). stdio has no network
surface and is unauthenticated.
## Configuration
All configuration lives in `etc/kaas.toml`. Copy and edit it:
```toml
[llm]
api_key = "sk-..."
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"
[ai.mcp]
enabled = false # set true to expose /mcp endpoint
token = "" # bearer token for MCP auth (empty = no auth)
timeout_sec = 120 # tools/call timeout
```
With Docker or the CLI, pass secrets as environment variables — they override the
TOML at startup:
| Env Var | Overrides | Default |
|---------|-----------|---------|
| `LLM_API_KEY` | `[llm] api_key` | _(empty)_ |
| `LLM_BASE_URL` | `[llm] base_url` | `https://api.openai.com/v1` |
| `LLM_MODEL` | `[llm] model` | `gpt-4o-mini` |
| `LLM_SUMMARIZE_MODEL` | `[llm] summarize_model` | same as `model` |
| `KAAS_MCP_ENABLED` | `[ai.mcp] enabled` | `false` |
| `KAAS_MCP_TOKEN` | `[ai.mcp] token` | _(empty = no auth)_ |
| `KAAS_WEB_DIR` | `[server] web_dir` | `/app/web/dist` (in Docker) |
| `KAAS_AI_MCP_URL` | `[ai] mcp_url` | _(deprecated — use `KAAS_MCP_ENABLED`)_ |
| `KB_AI_WRITE_TIMEOUT_S` | _(env only)_ | `300` |
| `KB_AI_EXTRACT_TIMEOUT_S` | _(env only)_ | `180` |
Raise `KB_AI_WRITE_TIMEOUT_S` when compiling with a slow local model. A write call
rewrites a whole article, so its latency tracks the article's length rather than the
prompt's: merging nine documents into one article on a local 27B model took 349s,
past the 300s default, and a call that runs out of budget surfaces as a per-document
entry in the run's `errors` rather than as a failed command.
There is no single right value, because local throughput is not a property of the
model alone. The same call on the same machine took 349s with one model resident and
over 900s with a second model sharing the GPU. Size it from the slowest write you
actually observe, and note the budget is per attempt — a timeout is retried twice,
so the wall-clock cost of a value that is still too low is three times over.
`KB_AI_EXTRACT_TIMEOUT_S` is the same knob for the extract phase, and the phase that
usually needs it first: extract runs on every document, so it is where a slow model
fails earliest. Its 180s default is deliberately tighter than the write phase's,
because extract calls are bounded in size and a single hung one blocks the whole job
— but that figure assumes a hosted model's generation speed. A local 12B model
exhausted all three attempts on a 4386-character prompt, which is a small document.
Size extract more conservatively than the write phase, because it retries in two
places rather than one: the LLM layer retries a timeout twice, and the summarize
strategy's second phase re-dispatches its entire call set once on any failure. A
hung call there costs six attempts to discover — about 1140s at the 180s default,
and over 90 minutes at 900s — so a value that is still too low is expensive twice
over.
Both variables ignore an unusable value (zero, negative, non-numeric, NaN, or
infinite) and say so once on stderr, rather than letting a typo in an env var decide
how a compile behaves.
The docs site has a
[full configuration reference](https://bybit-exchange.github.io/kaas-doc/getting-started/configuration.html)
covering the settings not listed here.
## Development
The quickest way to start all services locally:
```bash
# First time: create your local config (not tracked by git)
cp etc/kaas.toml etc/kaas-dev.toml
# Edit etc/kaas-dev.toml — set your LLM credentials:
# [llm]
# api_key = "sk-..."
# base_url = "https://api.openai.com/v1" # or your preferred endpoint
# model = "gpt-4o-mini"
make dev
```
This launches the Go backend (which auto-spawns the Python AI daemon) and the Vite dev server together.
To run components individually:
```bash
# Backend (spawns Python daemon automatically)
go run ./cmd/kaas -f etc/kaas.toml
# Frontend (hot-reload)
cd web && pnpm dev
# MCP server (stdio — for local agent integration)
cd py && KAAS_KB_DIR=./data uv run kb-ai mcp
# Tests
make test
```
## Contributing
Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup,
how to run the tests, and commit conventions.
## Acknowledgments
The core idea — compiling knowledge into a persistent, interlinked wiki that
compounds over time instead of re-deriving answers via RAG on each query — was
inspired by Andrej Karpathy's ["LLM Wiki"](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
gist. Thanks for the clear articulation of the pattern.
## License
MIT — see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues