A retrieval layer for AI agents. Local first, token efficient, open source.
Portuguese version: 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.
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.
npx @king-context/cli initThis 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.
Add your keys:
cp .king-context/.env.example .env
# FIRECRAWL_API_KEY=... scraping
# EXA_API_KEY=... research
# OPENROUTER_API_KEY=... optional, automated enrichmentPrefer running enrichment locally? Ollama is supported as beta. See docs/ollama.md for setup.
Build a corpus from a docs site or a topic:
king-scrape https://docs.stripe.com --name stripe --yes
king-research "prompt engineering techniques" --high --yesThen search and read:
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 3Or 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.
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.
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 with the URL, the command, and the error. Improvements are welcome.
Default (Firecrawl, no install needed beyond init):
king-scrape https://docs.example.comRequires FIRECRAWL_API_KEY in .env.
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):
.king-context/core/venv/bin/crawl4ai-setupThen pick the backend per run:
king-scrape https://docs.example.com --provider=crawl4aiOr set it as the default for the project:
SCRAPE_PROVIDER=crawl4ai king-scrape https://docs.example.comCloned the repo for development? From the repo root:
pip install -e ".[crawl4ai]" && crawl4ai-setupA standalone PyPI distribution (pip install king-context) is on the roadmap.
SCRAPE_DISCOVER_PROVIDER=crawl4ai SCRAPE_FETCH_PROVIDER=firecrawl king-scrape https://docs.example.comUseful when one backend handles a stage better than the other (for example, Crawl4AI for SPA discovery, Firecrawl for stable fetch).
| 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.
Every section of every scraped page or researched source ends up annotated:
{
"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.
Two rounds against Context7, the most widely used documentation tool for code agents.
| 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% |
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. Per-round analysis and discussion in docs/benchmarks.md.
Community registry. Anyone who scrapes a lib or researches a topic can publish the enriched corpus. Others install with one command:
kctx install stripe@v1
kctx install prompt-engineering-2026Versioned, 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.
- Community registry with versioned doc and research packages
pip install king-contextdistribution- 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 for active work.
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.
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.
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 by @Vadelo. Ask an agent for an ebook on any topic. The
ebook-factoryskill creates the required corpora withking-research, queries indexed knowledge throughkctx, 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.
MIT. Use it, fork it, improve it.