How contextweaver Fits

May 27, 2026 · View on GitHub

Where does contextweaver sit relative to my agent runtime, my LLM provider, and my tool catalog? What does it own, and what does it deliberately leave to the rest of the stack? This page is the orientation map.

In a hurry? Which pattern fits my use case? is a symptom-based decision tree that lands each branch on one concrete next step.

Positioning — policy vs. execution

contextweaver is a policy layer. It decides what tools to expose, what context to compile, and what to compact. It never executes tools, never calls LLMs, and never carries transport or auth.

Runtimes are the execution layer. FastMCP, LangChain, LangGraph, LlamaIndex, the OpenAI Agents SDK, Google's ADK / Vertex AI Agent Builder, and Pipecat all sit on the outside, driving the agent loop, invoking tools, and talking to model providers. contextweaver sits inside that loop and is composed in, not composed over.

Boundary diagram

┌──────────────────────────────────────────────────────────────┐
│ Runtime (FastMCP / LangChain / LangGraph / LlamaIndex / ADK /│
│          Pipecat / your custom loop)                          │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ contextweaver — policy layer                           │  │
│  │                                                        │  │
│  │   Router.route(query)            → RouteResult         │  │
│  │     └─ ContextManager.build_route_prompt → ChoiceCards │  │
│  │   ContextManager.build(phase, q) → ContextPack         │  │
│  │   Firewall (in ingest_tool_result) → summarised events │  │
│  │                                                        │  │
│  └────────────────────────────────────────────────────────┘  │
│                       ↕ plain callables / protocol objects   │
│                                                              │
│  Tool execution, LLM calls, transport, auth, streaming       │
└──────────────────────────────────────────────────────────────┘

The runtime hands events to contextweaver and receives back compact RouteResults, ContextPacks, and (when assembled via ContextManager.build_route_prompt() / contextweaver.routing.cards.make_choice_cards()) ChoiceCards. contextweaver never reaches outward.

Interop matrix

Runtime	Hook type	contextweaver component used	Guide / example	Status
MCP servers	Adapter (dict → `SelectableItem`)	`adapters.mcp` + Router + ContextManager	MCP Integration, `examples/mcp_adapter_demo.py`	Available
A2A peers	Adapter (agent card → `SelectableItem`)	`adapters.a2a` + Router + ContextManager	A2A Integration, `examples/a2a_adapter_demo.py`	Available
FastMCP	Adapter (FastMCP tool list → `Catalog`)	`adapters.fastmcp` + Router	FastMCP cookbook recipe, `examples/fastmcp_adapter_demo.py`	Available
FastMCP CodeMode	Custom discovery tool	Router	FastMCP CodeMode adapter	Planned (#87)
LlamaIndex	Agent subclass / tool callback	ContextManager + Router	LlamaIndex Integration	Available
LangChain	Callback handler / memory replacement	ContextManager (+ Router)	LangChain + LangGraph Integration, `examples/langchain_memory_demo.py`	Available
LangGraph	State node	ContextManager + Router	LangChain + LangGraph Integration	Available
OpenAI Agents SDK	Function wrapper / pre-call hook	Router + Firewall	OpenAI ADK Integration	Available
Google ADK / Vertex AI	Tool list filter / pre-call hook	Router + Firewall	Google ADK Integration	Available
Pipecat	Frame processor	ContextManager (async)	Pipecat Integration	Available
CrewAI	Adapter (`BaseTool` → `SelectableItem`)	`adapters.crewai` + Router + Firewall	CrewAI Integration, `examples/crewai_adapter_demo.py`	Available
Pydantic AI	Adapter (`Tool` → `SelectableItem`, `ModelMessage` round-trip)	`adapters.pydantic_ai` + Router + ContextManager	Pydantic AI Integration, `examples/pydantic_ai_adapter_demo.py`	Available
smolagents	Adapter (`Tool` → `SelectableItem`, step-log ingest)	`adapters.smolagents` + Router + ContextManager	smolagents Integration, `examples/smolagents_adapter_demo.py`	Available
Agno	Adapter (`Function` / `Toolkit` → `SelectableItem`, session ingest)	`adapters.agno` + Router + ContextManager	Agno Integration, `examples/agno_adapter_demo.py`	Available
Mem0 (external memory)	`EpisodicStore` / `FactStore` backend	`extras.memory.mem0`	External Memory	Available
Zep / Graphiti (external memory)	`EpisodicStore` / `FactStore` backend	`extras.memory.zep` (planned)	External Memory	Planned (#195)
LangMem (external memory)	`EpisodicStore` / `FactStore` backend	`extras.memory.langmem` (planned)	External Memory	Planned (#195)
MCP Proxy / Gateway	Standalone server	Full pipeline	—	Planned (#13, #28, v1.0)

If your runtime is not listed, the bring-your-own-tools cookbook recipe is the canonical pattern — register Python callables as SelectableItems and drive the loop yourself.

Minimal integration patterns

You do not have to adopt every contextweaver feature at once. Each of these patterns is independently useful and composes cleanly with the others.

Just routing — bounded tool shortlists

from contextweaver.routing.catalog import Catalog
from contextweaver.routing.router import Router
from contextweaver.routing.tree import TreeBuilder

catalog = Catalog()
for item in my_tools:
    catalog.register(item)

graph = TreeBuilder().build(catalog.all())
router = Router(graph, items=catalog.all(), top_k=5)
result = router.route("send a reminder email about unpaid invoices")
shortlist_ids = result.candidate_ids   # feed these into your existing loop

Just firewall — keep large tool outputs out of the prompt

from contextweaver.context.manager import ContextManager

mgr = ContextManager()
item, envelope = mgr.ingest_tool_result_sync(
    tool_call_id="tc-001",
    raw_output=large_tool_response_text,
    tool_name="search_database",
    firewall_threshold=2000,
)
# item.text now holds a compact summary;
# the raw bytes live in mgr.artifact_store under item.artifact_ref.handle.

Full pipeline — phase-specific compiled context

from contextweaver.context.manager import ContextManager
from contextweaver.types import ContextItem, ItemKind, Phase

mgr = ContextManager()
mgr.ingest_sync(ContextItem(id="u1", kind=ItemKind.user_turn, text="user query"))
# ... (tool call / tool result ingestion) ...
pack = mgr.build_sync(phase=Phase.answer, query="user query")
prompt = pack.prompt          # send to your LLM
stats = pack.stats            # BuildStats — what was kept, dropped, why

Non-goals

These are deliberate scope boundaries. Use your runtime for them.

Tool execution. contextweaver never invokes a tool. Your runtime — or your own code — calls the tool and feeds the raw output back via ingest_tool_result().
LLM orchestration. contextweaver does not call models, manage function-calling loops, or stream tokens. You drive the loop; we hand you a budgeted prompt.
Transport and authentication. MCP transports, HTTP, gRPC, OAuth, service accounts — all belong to the runtime. contextweaver consumes already-authenticated tool definitions and results.
Schema validation. contextweaver preserves args_schema / output_schema on SelectableItem and ResultEnvelope but does not validate them. Use the runtime's validator (or pydantic / jsonschema) before invoking a tool.
Persistence. Stores are pluggable, and v0.3 ships only in-memory implementations. Durable stores (SQLite, Redis, S3) are on the roadmap (#41, #42, #174); until then, persist event_log.to_dict() and friends yourself.