king-context

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #typescript #android #machine-learning #linux #docker #nodejs #windows #vue #mcp #ios

(★ 51)

Open-source Context7 alternative with 3x token efficiency

king-context Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://raw.githubusercontent.com/deandevz/king-context/main/LICENSE)
[![npm](https://img.shields.io/npm/v/@king-context/cli?label=installer&color=blue)](https://www.npmjs.com/package/@king-context/cli)
[![Status](https://img.shields.io/badge/status-active-brightgreen.svg)](https://github.com/deandevz/king-context)

A retrieval layer for AI agents. Local first, token efficient, open source.

Portuguese version: [README-pt-br.md](README-pt-br.md).

---

Agents work better when they see the right context, not all of it. King Context indexes any corpus you give it (vendor docs, open web research, internal notes, architectural decisions) and hands the agent back exactly the slice it needs. Every section is annotated with structured metadata, so the agent searches before it reads, previews before it pulls full content, and never burns its budget on a file dump.

## Why this exists

King Context started as an internal tool for my own company. I run YouTube automation at scale, and my agents needed retrieval that didn't hallucinate, didn't burn the context window on file dumps, and didn't depend on opaque embedding similarity. I tried the existing options. None of them held up.

So I built this for myself first. It's been in production on my own systems for months before any of it was public.

A few things follow from that, and they're worth knowing before you adopt it:

- **The same King Context you clone is the King Context I use.** No private fork, no internal branch with extra features, no premium build. If something breaks in a release, it breaks for me first.
- **I don't depend on this project to pay rent.** My income comes from elsewhere. That means no investor pressure to ship features that don't earn their place, no urgency to compromise the license, no incentive to capture users into a SaaS.
- **The core stays MIT, permanently.** If I ever build something that's paid, it lives outside this repo. What's in the repo is open. What I add to the repo is open. That's not a strategy I might revisit: **IT'S A CONSTRAINT.**
- **I review every line because if it breaks, it breaks my workflow tomorrow.** Quality here isn't discipline. It's incentive alignment.

The project ships when shipping helps me, my agents, or my own skills built on top of it. That's the filter. If you have the same itch I had agents that need precise, structured retrieval without the embedding lottery, **King Context is built for you the same way it's built for me.**

## Quick start

```bash
npx @king-context/cli init
```

This sets up `.king-context/` in any project: Python venv, CLI tools, agent skills, config templates. Zero manual wiring.

Windows is supported as **beta** since 0.3.1. Report any platform-specific issue at [github.com/deandevz/king-context/issues](https://github.com/deandevz/king-context/issues).

Add your keys:

```bash
cp .king-context/.env.example .env
# FIRECRAWL_API_KEY=...     scraping
# EXA_API_KEY=...           research
# OPENROUTER_API_KEY=...    optional, automated enrichment
```

Prefer running enrichment locally? Ollama is supported as **beta**. See [docs/ollama.md](docs/ollama.md) for setup.

Build a corpus from a docs site or a topic:

```bash
king-scrape https://docs.stripe.com --name stripe --yes
king-research "prompt engineering techniques" --high --yes
```

Then search and read:

```bash
kctx list
kctx search "authentication" --doc stripe
kctx read stripe authentication --preview     # ~400 tokens
kctx read stripe authentication                # full section
kctx grep "Bearer" --doc stripe --context 3
```

Or drive it through your agent of choice. The CLI is shell native, so any agent that runs commands can use it. Skills ship for Claude Code today, with Codex support and a portable skill format on the roadmap.

Full command reference in [`docs/CLI_GUIDE.md`](docs/CLI_GUIDE.md).

## What you get

**Scrape any docs site.** `king-scrape` discovers pages, fetches them, chunks the content, and enriches each chunk with keywords, use cases, tags, and priority.

**Research any topic.** `king-research` pulls sources from the open web via Exa, chunks them, and indexes the result the same way. Effort levels go from `--basic` (~30 sources) to `--extrahigh`.

**Search without dumping.** Metadata search hits in single-digit milliseconds. The agent previews ~400 tokens before pulling the full section. A query cache learns common paths and collapses repeats to sub-millisecond reads.

**Self-evolving retrieval.** Agents write `.king-context/_learned/<corpus>.md` shortcuts as they work, mapping common questions to exact section paths. The next session skips the search phase. The cache warms itself.

**Architectural decision memory.** `kctx adr` records project decisions as ADRs and indexes them alongside docs and research. Agents check the decision log before changing architecture, so context survives across sessions and contributors.

**One retrieval surface, many corpora.** Vendor docs, research sweeps, internal runbooks, and ADRs are all reachable through the same CLI primitives.

## Scraper providers

`king-scrape` supports pluggable scraper backends. The default is Firecrawl (cloud, zero-config, pay per page). Crawl4AI is the first local opt-in backend, added so users can index documentation without external credits, without sending HTML through a third party, and with full transparency over the HTML to Markdown conversion. It also unblocks indexing private or internal docs that should not leave your machine.

Crawl4AI support is **beta**. If something breaks or feels off, open an issue at [github.com/deandevz/king-context/issues](https://github.com/deandevz/king-context/issues) with the URL, the command, and the error. Improvements are welcome.

Default (Firecrawl, no install needed beyond `init`):

```bash
king-scrape https://docs.example.com
```

Requires `FIRECRAWL_API_KEY` in `.env`.

### Enable Crawl4AI

If you installed via `npx @king-context/cli init`, the Crawl4AI Python package is already in the project venv (bundled by `[all]`). You only need to download the Playwright browser once (~300MB):

```bash
.king-context/core/venv/bin/crawl4ai-setup
```

Then pick the backend per run:

```bash
king-scrape https://docs.example.com --provider=crawl4ai
```

Or set it as the default for the project:

```bash
SCRAPE_PROVIDER=crawl4ai king-scrape https://docs.example.com
```

Cloned the repo for development? From the repo root:

```bash
pip install -e ".[crawl4ai]" && crawl4ai-setup
```

A standalone PyPI distribution (`pip install king-context`) is on the roadmap.

### Mixing providers per stage

```bash
SCRAPE_DISCOVER_PROVIDER=crawl4ai SCRAPE_FETCH_PROVIDER=firecrawl king-scrape https://docs.example.com
```

Useful when one backend handles a stage better than the other (for example, Crawl4AI for SPA discovery, Firecrawl for stable fetch).

### Environment variables

| Variable | Effect |
|----------|--------|
| `SCRAPE_PROVIDER` | Sets provider for both stages. Default `firecrawl`. |
| `SCRAPE_DISCOVER_PROVIDER` | Overrides `SCRAPE_PROVIDER` for the `discover` stage only. |
| `SCRAPE_FETCH_PROVIDER` | Overrides `SCRAPE_PROVIDER` for the `fetch` stage only. |

Stage-specific variables take precedence over `SCRAPE_PROVIDER` and over the `--provider` flag. Full reference in [`docs/CLI_GUIDE.md`](docs/CLI_GUIDE.md).

## How it works

Every section of every scraped page or researched source ends up annotated:

```json
{
  "keywords": ["api-key", "bearer-token", "authentication"],
  "use_cases": ["Configure API authentication", "Rotate API keys"],
  "tags": ["security", "setup"],
  "priority": 10
}
```

The agent matches its query against keywords, use cases, and tags first. No full-text scan, no vector similarity on roughly 90% of lookups. It only reads content when metadata says it should, and previews before reading the full thing.

That structured metadata is the core of the idea. It makes progressive disclosure work without losing recall, and it lets the same machinery serve a vendor doc site, a cross-web research sweep, and the project's own decision log.

## Benchmarks

Two rounds against Context7, the most widely used documentation tool for code agents.

### Round 1: MCP vs MCP

| Metric | King Context | Context7 | Improvement |
|---|---|---|---|
| Average tokens per query | 968 | 3,125 | 3.2x less |
| Latency (metadata hit) | 1.15ms | 200 to 500ms | 170x faster |
| Latency (full text search) | 97.83ms | 200 to 500ms | 2 to 5x faster |
| Duplicate results | 0 | 11 | zero waste |
| Relevance | 3.2 / 5 | 2.8 / 5 | +14% |
| Implementability | 4.4 / 5 | 4.0 / 5 | +10% |

### Round 2: skill vs skill

Both tools driven by the same agent (Opus 4.7) through CLI plus skill, on Gemini API docs.

| Metric | Context7 | King Context |
|---|---|---|
| Average tokens per query | ~1,896 | ~1,064 |
| Median tokens per query | 1,750 | 901 |
| Correct facts | 32 / 38 (84%) | 38 / 38 (100%) |
| Hallucinations per query | 0.33 | 0.0 |
| Composite quality (0 to 5) | 3.46 | 4.79 |

The takeaway: progressive disclosure plus structured metadata gives the agent checkpoints to backtrack, refuse to hallucinate, and surface multiple versions of the same parameter. Semantic similarity alone cannot.

Methodology and raw data in [BENCHMARK.md](BENCHMARK.md). Per-round analysis and discussion in [docs/benchmarks.md](docs/benchmarks.md).

## Where this is going

**Community registry.** Anyone who scrapes a lib or researches a topic can publish the enriched corpus. Others install with one command:

```bash
kctx install stripe@v1
kctx install prompt-engineering-2026
```

Versioned, pre-enriched, current. Vendor docs are a starting point, not a ceiling.

**Specialist skills from corpora.** Feed an indexed corpus to an agent and it can produce a portable skill that knows the lib's idioms, gotchas, and patterns. From a research sweep, a skill that encodes the consensus and the disagreements across 30+ sources. Corpus in, skill out, agent agnostic.

**Living inside the dev loop.** Pin doc versions to the project so the agent never drifts. Surface relevant sections as you work. Notify when upstream docs change in a way that affects code you already shipped.

The aim is not "agent asks, corpus answers". The aim is that your agent always has the right context on hand, quietly, without you having to ask.

## Roadmap

- Community registry with versioned doc and research packages
- `pip install king-context` distribution
- Agent-generated skills built from indexed corpora
- Incremental doc updates without full re-scrape
- Windows installer general availability (currently beta)
- Benchmark suite covering docs, ADRs, and research corpora
- Workflow hooks that surface relevant sections during active coding
- Indexing for user content (md, txt, pdf, docx, video transcripts)

See [open issues](https://github.com/deandevz/king-context/issues) for active work.

## Interfaces

The CLI is the canonical interface. Any agent that can run shell commands can use King Context: today that means Claude Code via dedicated skills, with Codex support and a unified skill format on the roadmap. The MCP server still ships and runs on the same corpus, useful for non-coding agents and IDE integrations that expect an MCP endpoint. Same corpus, same retrieval shape, pick what fits your environment.

For humans browsing the index, `kctx ui` opens a local, read-only web UI for ADRs, docs, and research. See [docs/ui-local.md](docs/ui-local.md).

## Contributing

Three areas where help moves the project the most.

- **Corpus packages.** Scrape or research something you use a lot, open a PR. The community library is the biggest lever.
- **Pipeline reliability.** Edge cases in URL discovery, chunking strategies, JavaScript-rendered pages, source filtering.
- **Skills.** Skill workflows are still improving. Better sub-agent reliability, error handling, parallel enrichment, and a unified format that works across agent platforms.

This project is open source because retrieval infrastructure for LLMs should be transparent, community driven, and independent of any single provider.

## Cookbooks

Real projects built on top of King Context. Useful as starting points, and as evidence that the retrieval layer holds up under a full workflow.

- [ebook-factory](https://github.com/Vadelo/ebook-factory) by [@Vadelo](https://github.com/Vadelo). Ask an agent for an ebook on any topic. The `ebook-factory` skill creates the required corpora with `king-research`, queries indexed knowledge through `kctx`, writes the manuscript in Markdown, and hands it off to a PDF generator. End-to-end use of King Context as the local knowledge layer for a real content pipeline.

Built something with King Context? Open a PR adding it to this list.

## License

MIT. Use it, fork it, improve it.

king-context

king-context Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

king-context

king-context Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README