contextweaver

# contextweaver

<!-- mcp-name: io.github.dgenio/contextweaver -->

[![CI](https://github.com/dgenio/contextweaver/actions/workflows/ci.yml/badge.svg)](https://github.com/dgenio/contextweaver/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/contextweaver.svg)](https://pypi.org/project/contextweaver/)
[![Python versions](https://img.shields.io/pypi/pyversions/contextweaver.svg)](https://pypi.org/project/contextweaver/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://dgenio.github.io/contextweaver)
[![GitHub Discussions](https://img.shields.io/github/discussions/dgenio/contextweaver)](https://github.com/dgenio/contextweaver/discussions)

> **The MCP context gateway for tool-heavy agents.** Drop contextweaver in
> front of your MCP servers and the model sees a bounded `ChoiceCard` shortlist
> instead of every tool schema, plus an artifact-backed firewall that swaps a
> huge raw tool result for a compact summary. Deterministic, no model in the
> loop, and 42-84 % fewer prompt tokens on the committed benchmarks.

**Who it's for:** anyone whose agent — Claude Desktop, Cursor, VS Code, or a
custom loop — keeps tripping over *"too many tools"* or *"a 16 KB tool result
blew up my prompt."*

```bash
uvx contextweaver demo --scenario killer  # zero-install trial

# Or install it:
pip install contextweaver
python -c "import contextweaver; print(contextweaver.__version__)"
contextweaver demo --scenario killer   # 60-second taste — no API key, no network
```

**Use it for real →** the **[MCP gateway quickstart](docs/recipes/index.md)**
(Claude Desktop / Copilot / custom MCP clients), backed by the
[MCP Context Gateway architecture](docs/architectures/mcp_context_gateway.md).
Already have a loop and not sure which piece you need? The two engines also work
[routing-only or firewall-only](docs/which_pattern.md).
For day-to-day operating guidance, see the [Daily Driver guide](docs/daily_driver.md);
for deployment boundaries, see the [MCP Gateway Security Model](docs/security_model.md).

<p align="center">
  <img src="docs/assets/hero.svg" alt="contextweaver architecture: Context Engine plus Routing Engine, with the Context Firewall storing large tool outputs out of band and the Routing Engine narrowing a 100-tool catalog to 5 ChoiceCards."/>
</p>

**1150+ tests passing · minimal core dependencies · deterministic by default · Python 3.10–3.13**

#### More tools ≠ better answers

<p align="center">
  <img src="docs/assets/context_rot.svg" width="660" alt="Context-rot curve: as the tool catalog grows from 83 to 1328 tools, a naive route prompt carries every schema (line climbs on a log scale) while contextweaver stays flat at 5 ChoiceCards; contextweaver's correct-tool recall@5 erodes from 36 percent to 10 percent as distractor tools accumulate."/>
</p>

> As an agent's tool catalog grows, a naive "show every schema" route prompt
> balloons while the right tool gets harder to find — *context rot*.
> contextweaver keeps the model-visible surface bounded (5 `ChoiceCard`s, not
> 1,328 schemas), so the route prompt stays flat and deterministic. Reproduce
> the curve with no API key: [`docs/context_rot.md`](docs/context_rot.md).

<p align="center">
  <img src="docs/assets/demo.svg" alt="Animated terminal recording of `python -m contextweaver demo`: load a 40-tool catalog, build a 9-node routing graph, narrow to 5 ChoiceCards for the query 'find unpaid invoices and send a reminder email', build a phase-answer context pack, and print the 321-character compiled prompt."/>
</p>

<p align="center">
  <img src="docs/assets/before_after.svg" alt="Before vs after token comparison from examples/before_after.py: 417 raw prompt tokens without contextweaver vs 126 final prompt tokens with contextweaver — a 70 percent reduction, 291 tokens saved, budget compliant."/>
</p>

[📖 Docs](https://dgenio.github.io/contextweaver) · [🎬 Showcase](docs/showcase.md) · [🧩 Where it fits](docs/comparison.md) · [🗺️ Ecosystem map](docs/ecosystem.md) · [❓ FAQ](docs/faq.md) · [📊 Scorecard](benchmarks/scorecard.md) · [📈 Adopter benchmark report](docs/benchmark_report.md) · [🧭 Which pattern fits?](docs/which_pattern.md) · [🛠 Cookbook](docs/cookbook.md) · [🍳 Recipes](docs/recipes/index.md) · [📉 Context rot demo](docs/context_rot.md) · [🎬 Replay demo (.cast)](docs/assets/demo.cast)

---

## Part of the Weaver Stack

contextweaver is the **context** layer of the **Weaver Stack** — small,
deterministic, independently-usable building blocks for tool-using agents. The
core request path runs:

```text
contextweaver ─▶ ChainWeaver ─▶ agent-kernel ─▶ agentfence
```

| Stage | Component | Responsibility |
|---|---|---|
| **Context** | **contextweaver** (this repo) | Route a catalog to bounded `ChoiceCard`s, firewall large tool results, compile a budgeted prompt. |
| Execution | ChainWeaver | Run the selected capability as a deterministic tool/flow. |
| Boundary | agent-kernel | Own the execution boundary; hand contextweaver `Frame`s, not raw output. |
| Guardrails | agentfence | Apply output guardrails to the response. |

The contextweaver → ChainWeaver handoff is **advisory**: contextweaver routes
(it recommends a capability) and ingests results behind its firewall; the
runtime owns authorization and execution. A runnable end-to-end example —
route a catalog of tools + imported ChainWeaver flows, hand the selection to a
(stubbed) ChainWeaver runtime, then ingest the result — lives at
[`examples/architectures/contextweaver_to_chainweaver/`](examples/architectures/contextweaver_to_chainweaver/),
and the contract boundary is documented in
[`docs/weaver_spec_mapping.md`](docs/weaver_spec_mapping.md).

Adjacent tools: **vibeguard** (code-diff safety gate), **lessonweaver** (lesson
capture), and **skdr-eval** (offline evaluation). Every piece works
**standalone** — contextweaver has **no hard dependency** on any sibling, so you
can use it on its own or slot it into the stack. See the
[Ecosystem Map](docs/ecosystem.md) for how the pieces compose.

---

## The 60-second failure mode

See why a naive tool-using agent loop breaks down — and what contextweaver
does about it — in one command (no API keys, no network):

```bash
contextweaver demo --scenario killer
```

An internal ops agent with **100 tools** and a running conversation is asked
to *"find unpaid invoices, check the account notes, and draft a reminder."*
A naive loop pays for all 100 tool descriptions, the full history, and a
huge raw tool result at once:

| | Naive | contextweaver | Reduction |
|---|---|---|---|
| Tools in the route prompt | all 100 (6,326 chars) | 5 ChoiceCards (491 chars) | **92.2%** |
| The huge tool result | raw (14,430 chars) | firewalled summary (60 chars) | **99.6%** |
| The full answer prompt | everything raw (21,332 chars) | compiled (814 chars) | **96.2%** |

Full walkthrough: [The 60-second failure mode](docs/killer_demo.md). For the
same story as a runnable, inspectable script, see the
[catalog showcase architecture](docs/architectures/catalog_showcase.md).

---

## The Problem

Even with 200K-token context windows, dumping everything into the prompt is expensive,
slow, and degrades output quality. More context ≠ better answers — **context engineering**
(deciding what the model sees, when, and at what cost) is the lever that actually moves
quality and latency.

Imagine a tool-using agent with a 100-tool catalog and a 50-turn conversation history.
At each step the agent must answer four questions:

1. **Route** — which tool should I call?
2. **Call** — what arguments?
3. **Interpret** — what did it return?
4. **Answer** — how do I respond to the user?

**Naive approach A — concatenate everything:**

```
100 tool schemas (≈50k tokens) + 50 turns (≈30k tokens) = 80k tokens
Cost: $0.48/request at GPT-4o rates  ·  Latency: 3–5s TTFT
Quality: LLM loses focus — needle-in-haystack accuracy drops with context size
Token limit: 8k → 10× overflow
```

**Naive approach B — cherry-pick manually:**

```
Pick 10 tools, last 5 turns → lose dependency chains
Agent hallucinates tool calls, repeats questions, forgets context
```

**contextweaver approach — phase-specific budgeted compilation:**

```
Route phase:  5 tool cards (≈500 tokens), no full schemas
Answer phase: 3 relevant turns + dependency closure (≈2k tokens)
Result:       2.5k tokens, complete context, deterministic
Cost:         41.6 %-84.3 % fewer prompt tokens [^naive-baseline]  ·  Latency: sub-second  ·  Quality: relevant context only
```

[^naive-baseline]: Measured against the "concatenate all tool schemas + full
    conversation history" baseline using `tiktoken.cl100k_base` on the six
    committed benchmark scenarios. Range 41.6 %-84.3 %, average 64.3 %.
    Reproducible via `make benchmark-matrix && make scorecard` — see the
    *vs. naïve concat baseline* section of
    [`benchmarks/scorecard.md`](benchmarks/scorecard.md) and the
    methodology in [`scripts/baseline_naive.py`](scripts/baseline_naive.py).

See [`examples/before_after.py`](examples/before_after.py) for a runnable side-by-side comparison.

---

## How contextweaver Solves It

contextweaver provides two cooperating engines:

```
                ┌────────────────────────────┐
  Events ──────>│      Context Engine         │──> ContextPack (prompt)
                │  candidates → closure →     │
                │  sensitivity → firewall →   │
                │  score → dedup → select →   │
                │  render                     │
                └────────────────────────────┘
                           ▲ facts / episodes
                ┌──────────┴─────────────────┐
  Tools ───────>│      Routing Engine         │──> ChoiceCards
                │  Catalog → TreeBuilder →    │
                │  ChoiceGraph → Router       │
                └────────────────────────────┘
```

**Context Engine** — eight-stage pipeline:

1