ckg-mcp

<!-- mcp-name: io.github.Yarmoluk/ckg-mcp -->

<div align="center">

# Context Optimization for AI Agents

### Agent traversal · Agent team orchestration · 97 domains · MCP-native

**Your agents retrieve. They should traverse.**

[![PyPI version](https://img.shields.io/pypi/v/ckg-mcp?color=0f6e56&label=PyPI)](https://pypi.org/project/ckg-mcp/)
[![Downloads](https://img.shields.io/pypi/dm/ckg-mcp?color=0f6e56&label=installs%2Fmo)](https://pypi.org/project/ckg-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/ckg-mcp?color=0f6e56)](https://pypi.org/project/ckg-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-0f6e56)](LICENSE)
[![Domains](https://img.shields.io/badge/domains-97-0f6e56)](https://graphifymd.com)
[![Free](https://img.shields.io/badge/free-68_domains-0f6e56)](https://pypi.org/project/ckg-mcp/)
[![F1: 0.471 · 4× RAG](https://img.shields.io/badge/F1-0.471_%C2%B74%C3%97_RAG-0f6e56)](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf)
[![KRB v0.6.2](https://img.shields.io/badge/benchmark-KRB_v0.6.2-13201c)](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf)
[![Built by Graphify.md](https://img.shields.io/badge/built_by-Graphify.md-0f6e56)](https://graphifymd.com)

> **Read-only.** The server can only return edges that exist in the data.
> It returns nothing rather than inferring a path that isn't there.

[**Get Pro →**](https://graphifymd.com/pro) · [**Benchmark →**](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf) · [**graphifymd.com →**](https://graphifymd.com)

</div>

<div align="center">
  <a href="https://yarmoluk.github.io/ckg-mcp/carousel.html">
    <img src="docs/demo.png" alt="ckg-mcp — Context Optimization for AI Agents" width="960">
  </a>
</div>

---

## Context Optimization — The Problem

Every agent that reasons about a domain — HIPAA, GPU inference, calculus, contract law — does one of three things:

| Approach | What breaks |
|---|---|
| Long system prompt | No structure. Drifts with every model update. Cannot traverse. |
| RAG retrieval | Probabilistic. Accuracy degrades at each hop. Expensive per query. |
| Fine-tuning | 6-month cycle. Stale by delivery. Retrains when knowledge shifts. |

All three share the same failure: the agent **re-infers** domain structure on every query instead of reading structure that was declared once.

In our open benchmark (KRB v0.6.2 — [reproduce it yourself](https://github.com/Yarmoluk/ckg-benchmark)):
RAG achieves **0.123 macro F1** on multi-hop domain queries. CKG achieves **0.471**. At 5 hops, the gap widens: RAG 0.170, CKG 0.772.

The token cost compounds the accuracy problem: the average RAG query costs **2,982 tokens**. The average CKG traversal costs **269** — measured across 19 benchmark domains.

These numbers are ours, on our benchmark. The dataset is [public on HuggingFace](https://huggingface.co/datasets/danyarm/ckg-benchmark). Run it yourself.

---

## Agent Traversal — The Solution

A **Compressed Knowledge Graph (CKG)** is a domain structured for traversal, not retrieval.

Not a document. Not a vector index. A pre-compiled DAG of concepts, typed dependency relationships, and prerequisite chains — compressed to the minimum tokens that carry the maximum structure. Served over MCP. Traversed deterministically.

```
Agent asks:   "What does TensorRT-LLM require to run on Hopper?"

CKG returns:  TensorRT-LLM
              ├─ [REQUIRES] CUDA Toolkit
              │    ├─ [ENABLES] cuBLAS
              │    └─ [ENABLES] CUDA Driver API
              ├─ [REQUIRES] FP8/FP4 Quantization
              │    └─ [REQUIRES] Hopper SM90 Architecture
              └─ [ENABLES] Triton Inference Server
                   └─ [ENABLES] NIM Microservice Runtime

              269 tokens · declared edges only · no inference at query time

RAG would:    ~2,982 tokens · probabilistic retrieval · degrades at 3+ hops
```

**You go from prompting the domain into existence to asking questions inside it.**

---

## One Use Case — Becoming Nemotron-Enabled

Perplexity is a model aggregator. Shortest route to Nemotron — click the dropdown, select the model, query. But it's their pipeline, their infrastructure. Your queries go through their system.

If you want to run Nemotron yourself — sovereign, private, on your own hardware — you need to navigate NVIDIA's stack: NGC API key, NIM container, Enterprise License, inference endpoint. The dependency chain is non-obvious. Most developers hit the wrong door first.

**Without CKG:** search the docs, hit the Enterprise License wall, spend two hours finding `build.nvidia.com`.

**With CKG:**
```
query_ckg("Nemotron Model", "nvidia-nim")
→ [REQUIRES] Model Weights
  → [REQUIRES] NGC Container Registry
    → [REQUIRES] NGC API Key        ← start here

query_ckg("NIM Docker Container", "nvidia-nim")
→ [REQUIRES] NGC API Key
→ [REQUIRES] NVIDIA AI Enterprise License   ← production path
→ [ENABLES]  NIM Microservice               ← what you're building toward
```

Two traversals. Correct path. No wrong doors. The graph knew — the model just told you.

### Typed edges carry semantic meaning

| Edge type | Meaning | Agent use |
|---|---|---|
| `REQUIRES` | Hard prerequisite — must exist first | Sequencing, gap detection |
| `ENABLES` | Unlocks a downstream capability | Optimization paths |
| `RELATES_TO` | Conceptual proximity | Disambiguation |
| `IMPLEMENTS` | Concrete realization of an abstraction | Architecture mapping |
| `CONTRASTS_WITH` | Meaningful opposition | Tradeoff reasoning |

### Every domain is a plain-text DAG

```
ConceptID, ConceptLabel,      Dependencies,      TaxonomyID
1,         Taylor Series,     "",                Analysis
2,         Power Series,      "",                Analysis
3,         Convergence,       "2:REQUIRES",      Analysis
4,         Higher-Order Der., "5:REQUIRES",      Calculus
5,         Derivative,        "6:REQUIRES",      Calculus
6,         Continuity,        "7:REQUIRES",      Calculus
```

No embeddings. No probabilistic retrieval. Built once, reviewed once, traversed forever.

<div align="center">
  <img src="docs/slide-edges.png" alt="ckg-mcp — Every edge is a decision: REQUIRES · ENABLES · RELATES_TO · IMPLEMENTS" width="860">
</div>

---

## Agent Team Orchestration — The Scale Story

Single-agent traversal is the efficiency gain. Multi-agent orchestration is where it compounds.

Liu et al. ([arXiv:2606.30986](https://arxiv.org/abs/2606.30986)) measure **Context Transaction Cost (CTC)**: the tax paid every time context crosses an agent boundary. Their finding: context efficiency collapses from 18.2 in Q1 to 1.6 by Q4 across pipeline stages — **91% degradation with no model change**.

CKG addresses all three root causes they identify:

| CTC component | What it is | CKG's response |
|---|---|---|
| Token Latency Burden | Compute cost of transmitting context | 269 tokens instead of 2,982 |
| Handoff Cost | Serialization loss at agent boundaries | `get_prerequisites()` replaces re-retrieval |
| Compression Loss | Information destroyed when context is summarized | The graph is the compressed form — done once, offline |

When agent A hands off to agent B, neither re-retrieves the domain. They both traverse the same declared graph. **Structured context doesn't consume your context window — it opens it.**

<div align="center">
  <img src="docs/slide-tokens.png" alt="ckg-mcp — 11× fewer tokens: 269 vs 2,982 per query" width="860">
</div>

---

## Quickstart

```bash
uvx ckg-mcp          # no install — runs immediately
# or
pip install ckg-mcp  # Python ≥ 3.10
```

### Claude Desktop

```json
{
  "mcpServers": {
    "ckg": { "command": "uvx", "args": ["ckg-mcp"] }
  }
}
```

### Claude Code

```bash
claude mcp add ckg -- uvx ckg-mcp
```

### Cursor / Cline / Windsurf / any MCP client

```json
{ "mcpServers": { "ckg": { "command": "uvx", "args": ["ckg-mcp"] } } }
```

### System prompt snippet

```
You have access to the ckg MCP server — a typed dependency graph catalog
of 97 domains (mathematics, GPU inference, healthcare, law, robotics,
regulatory, AI tooling, and more). When answering questions about any of
these domains, call query_ckg() or get_prerequisites() before responding.
Do not infer dependency chains — traverse the graph instead.
```

### Try it immediately

```
list_domains()
→ see all 68 free domains

query_ckg("Taylor Series", "calculus", 3)
→ prerequisite chain: Function → Limit → Continuity → Derivative →
  Higher-Order Derivatives → Convergence → Power Series → Taylor Series

get_prerequisites("Business Associate Agreement", "hipaa-compliance")
→ Covered Entity → PHI Definition → Minimum Necessary Standard →
  Access Controls → Breach Notification Rule → BAA

query_ckg("FlashAttention-3", "nvidia-gpu-inference", 3)
→ SRAM Tiling · On-Chip Memory Budget · Transformer Attention ·
  Softmax Stability → FlashAttention-3 → Multi-Head Attention → KV Cache
```

---

## Source provenance — verifiable to the byte

Every node carries a `source_url` and a `source_hash` (SHA-256 of source bytes at extraction time) where available. The full audit chain: edge answer → graph commit hash → source_content_hash → knowledge_source_ref.

```bash
# For domains with per-node hashes:
curl -s <source_url> | sha256sum
# compare to source_hash — mismatch = stale edge or silent upstream edit
```

Via MCP — `verify_source(concept, domain)` returns source URL, hash, and verification command. Run `scripts/refresh_hashes.py` to recompute.

Reference implementation from [GuardrailDecisionV1](https://github.com/crewAIInc/crewAI/issues/4877).

---

## Benchmark

> These are our numbers on our open benchmark. The dataset is on HuggingFace. Run it yourself before citing them.

```bash
git clone https://github.com/Yarmoluk/ckg-benchmark && cd ckg-benchmark
pip install -r evaluation/requirements.txt
python evaluation/ckg_harness.py --domain calculus
python evaluation/analyze_results.py
```


| System | Macro F1 | Tokens / query | Cost / 1K q