A short, symptom-based decision tree. Each branch ends in one concrete next step. If your problem isn't listed, jump to the 10-minute quickstart.
contextweaver is built from composable pieces — you do not have to adopt all of it. Pick the smallest piece that fixes your symptom, then grow into the rest when you need it.
The three building blocks:
| Piece | What it does | When you need it |
|---|---|---|
| Routing engine | Bounded shortlist of tools from a large catalog | LLM picks badly with many tools |
| Context firewall | Keeps huge tool outputs out of the prompt; raw bytes go to an artifact store | One tool returns much more than fits the budget |
| Full pipeline | All eight context stages: candidates → closure → sensitivity → firewall → score → dedup → select → render | Long conversations + tool history that overflow the window |
If you're starting a brand-new agent, walk the 10-minute quickstart first, then come back here when a specific symptom shows up. If you operate the MCP gateway day to day, use the Daily Driver guide after choosing a pattern here.
Start with the full pipeline. Use ContextManager.build()
(or build_sync()) with phase-specific token budgets. The
select_and_pack stage drops low-scoring items first, so a 10K-turn history
collapses to a budgeted prompt deterministically.
Concrete next step: walk the 10-minute quickstart end-to-end,
then read the Phase section to tune per-phase budgets.
from contextweaver.context.manager import ContextManager
from contextweaver.types import Phase
mgr = ContextManager()
# … ingest events …
pack = mgr.build_sync(phase=Phase.answer, query="user question")
print(pack.prompt)
print(pack.stats) # what was kept, dropped, deduplicatedStart with routing-only. Build a Catalog, run
Router.route(), feed the shortlist into your existing
agent. You don't need the rest of the library.
Concrete next step: skim
examples/routing_demo.py,
then read Routing for the four-stage pipeline.
from contextweaver.routing.catalog import Catalog
from contextweaver.routing.router import Router
from contextweaver.routing.tree import TreeBuilder
catalog = Catalog()
# … register SelectableItem objects …
graph = TreeBuilder(max_children=8).build(catalog.all())
router = Router(graph, items=catalog.all(), top_k=5)
result = router.route("send a reminder email about unpaid invoices")
print(result.candidate_ids)Start with firewall-only. Ingest results through
ContextManager.ingest_tool_result_sync(); the firewall
stores raw bytes in the ArtifactStore and injects a compact summary into the
event log. Drill into the artifact when the agent asks for specifics.
Concrete next step: copy Cookbook recipe 4 — Firewall + drilldown verbatim and replace the mocked payload with your tool.
mgr.ingest_tool_result_sync(
tool_call_id="tc1",
raw_output=huge_json,
tool_name="logs.fetch",
firewall_threshold=2000,
)
# Later, drill into the artifact for a targeted slice:
mgr.drilldown_sync(handle=item.artifact_ref.handle,
selector={"type": "json_keys", "keys": ["errors"]},
inject=True, parent_id="tc1")Use the full pipeline, but run build_sync() off the event loop and tighten
the answer-phase budget. contextweaver's pipeline is sync-internally but
async-callable; the recommended pattern is asyncio.to_thread(mgr.build_sync, …)
so the 10–50 ms context build doesn't block your turn-taking loop.
Concrete next step: read the Pipecat guide for the
canonical pattern; tighten ContextBudget(answer=…) until your TTFT target is
met.
pack = await asyncio.to_thread(mgr.build_sync, phase=Phase.answer, query=q)Use the adapter + routing-only. Convert MCP tool definitions to
SelectableItem (adapters.mcp.mcp_tool_to_selectable / adapters.fastmcp.fastmcp_tools_to_catalog)
and serve a top-k shortlist instead of the full server tool list.
Concrete next step: pick the recipe that matches your runtime — MCP integration guide for raw MCP servers, FastMCP cookbook recipe for composed FastMCP servers.
Use the provider-message adapters. They take your existing chat history
(plain dicts, no SDK import required) and produce a populated
ContextManager in one call — five lines including imports.
Concrete next step: Adopting from an existing chat history shows the OpenAI, Anthropic, and Gemini variants side-by-side. The adapters ship inverse functions so you can hand the rebuilt array back to the provider SDK without changing the rest of your loop.
Use the bring-your-own-tools recipe. It's the canonical adapter shape:
register each callable as a SelectableItem, route over them, ingest the
result through the firewall.
Concrete next step: copy Cookbook recipe 3 — Bring-your-own-tools and adapt. This is also the right starting point for a fully custom runtime.
Skim a production reference architecture. The examples/architectures/
directory ships full worked examples that exercise the routing engine, the
firewall, persistent facts, and multi-turn investigation patterns together.
Concrete next step: read
Slack ops bot — ~50 internal tools, mocked
log/grep/deploy/oncall calls, multi-turn investigations, persistent facts.
Run it with python examples/architectures/slack_ops_bot/main.py.
Read the How contextweaver Fits positioning page — it answers "is this for me?" in five lines, then maps every component to the runtimes it hooks into. From there:
- Architecture overview — the two engines and eight stages
- Cookbook — four copy-paste recipes for common shapes
- Troubleshooting — 10 common issues with fixes
- Examples — all runnable scripts