Where contextweaver fits (and where it doesn't)

A short, honest map of the agent-stack landscape and where contextweaver sits in it. If you arrived from a launch post, this is the page that answers "do I need this in addition to what I already use?"

contextweaver is a context-compilation layer: it takes events (user turns, tool calls, tool results, facts, episodes) and tools (a catalog of SelectableItems) and produces a bounded, phase-specific prompt. It is not an agent framework, not a memory database, not an LLM SDK, and not a generic RAG library. The point of this page is to make those boundaries concrete.

For an adopter-facing decision matrix with more public-positioning language, see the Ecosystem Map. This page stays closer to the technical boundaries between layers.

TL;DR

                     ┌──────────────────────────────────────────────┐
                     │   Your agent loop (LangGraph / CrewAI /      │
                     │   Pydantic AI / your own code)               │
                     │                                              │
                     │   ┌──────────────────────────────────────┐   │
                     │   │   contextweaver                      │   │
                     │   │   • Router → ChoiceCards             │   │
                     │   │   • ContextManager → ContextPack     │   │
                     │   │   • Firewall → ArtifactRef           │   │
                     │   └──────────────────────────────────────┘   │
                     │                                              │
                     │   Tools: MCP servers / FastMCP / plain Python│
                     │   Memory: Mem0 / Zep / LangMem / your store  │
                     │   Retrieval: LlamaIndex / your vector DB     │
                     │   Model: OpenAI / Anthropic / Gemini SDK     │
                     └──────────────────────────────────────────────┘

contextweaver is a thin layer inside the agent loop. It does not run the loop and does not call the LLM. It assembles the prompt the loop gives to the LLM.

Per-category comparison

Agent frameworks

Question	Answer
Does contextweaver replace an agent framework?	No.
Should I keep using my agent framework?	Yes.
What's the relationship?	contextweaver runs inside the agent loop your framework defines. The framework owns the control flow (when to call which tool, when to stop, how to retry); contextweaver owns prompt assembly (which events / tools / facts / summaries enter the prompt at each phase).

If you do not yet have an agent framework, start with one that fits your shape (LangGraph for graphs of tool calls, CrewAI for multi-agent flows, Pydantic AI for typed agents). contextweaver does not opine on which. See the LangChain, OpenAI Agents SDK, Google ADK, Pipecat, and A2A integration guides for wiring patterns.

Memory systems

Question	Answer
Does contextweaver replace a memory database?	No — it does not persist memory across sessions out of the box.
Does it have facts / episodes?	Yes, in-session: `ContextManager.add_fact_sync(...)` and `add_episode_sync(...)`.
How do I get cross-session persistence?	Plug a persistent backend behind the `FactStore` / `EpisodicStore` / `EventLog` protocols. SQLite-backed `EventLog` / `ArtifactStore` ship today; external backends (Mem0 / Zep / LangMem) are tracked under issue #195.

contextweaver's stores are protocol-based interfaces, not concrete backends. A real deployment usually points the FactStore / EpisodicStore at a memory system designed for cross-session persistence.

RAG / vector retrieval

Question	Answer
Is contextweaver RAG?	No. RAG retrieves documents relevant to a question. contextweaver compiles agent-loop events and tools into a phase-budgeted prompt.
Can I combine them?	Yes. Run RAG to retrieve documents, ingest the retrieved chunks as `ContextItem(kind=doc_snippet, ...)`, and let contextweaver score them against the current query under the same budget pressure as everything else.
Does contextweaver ship embeddings?	No. The default scorer is lexical (`tfidf` / `bm25`); an embedding-based retrieval backend is tracked under #8.

The shape of the work is different: RAG produces a list of relevant documents; contextweaver produces the exact prompt the LLM sees, which may include some, all, or none of those documents depending on how they score against the current query, the budget, and what else is competing for the budget that turn.

MCP servers and gateways

Question	Answer
Is contextweaver an MCP server?	No.
Is it an MCP gateway?	It can be. `contextweaver.adapters.ProxyRuntime` implements the gateway shape (`tool_browse` / `tool_execute` / `tool_view` meta-tools per `gateway_spec.md`) and runs in front of upstream MCP servers.
Does it speak the MCP wire protocol?	The runtime accepts and produces MCP-shaped tool defs and tool results. The stdio transport itself is provided by `mcp_gateway_server.py` / `mcp_proxy_server.py` (or by the `mcp` Python SDK).
Can it sit beside FastMCP?	Yes. Use FastMCP for tool discovery and execution upstream; use contextweaver in front to bound which tool cards reach the agent and to firewall large results. See `examples/fastmcp_adapter_demo.py` and the MCP integration guide.

In production, MCP servers expose your tools; contextweaver decides which tool cards the agent sees this turn and how their results are summarised before the next turn.

Prompt templates

Question	Answer
Does contextweaver replace prompt templates?	No. It produces a block of text (the `ContextPack.prompt`) you splice into your existing template.
Where does the template wrap the contextweaver output?	Typically: `system: <your instructions>\n\n<contextweaver-produced events block>\n\nuser: <current turn>`. The events block is what contextweaver assembles.
Can I render contextweaver output myself?	Yes. A `ContextPack` exposes `.events` (typed) and `.prompt` (rendered string). Use the typed list with your own template if the default `render_context` output doesn't match your prompt shape.

Observability tools

Question	Answer
Is contextweaver observability?	No — it is observable.
What does it emit?	Every build produces a `BuildStats` record: which events were considered, included, dropped, deduplicated, the reasons, the per-section token breakdown, the budget utilisation.
OpenTelemetry support?	First-class — see Observability. Emits GenAI semantic-convention attributes (`gen_ai.operation.name`, `gen_ai.client.token.usage`, …) so existing OTel-aware dashboards (LangSmith, Honeycomb, Datadog, Grafana) light up without custom mappers.
What does it not observe?	Anything outside contextweaver itself: model latency, model cost, downstream user satisfaction, business KPIs. Those belong in your existing observability stack.

Interop matrix (one-line summary)

Layer	Best-in-class	contextweaver's role
Agent control flow	LangGraph, CrewAI, Pydantic AI, OpenAI Agents SDK	Runs inside their loop
Tool execution	MCP servers, FastMCP, plain Python	Reads their tool defs; firewalls their results
Memory persistence	Mem0, Zep, LangMem	Stores plug behind contextweaver's protocols
Document retrieval	LlamaIndex, vector DBs	Ingests retrieved docs as `ContextItem`s
LLM SDK	OpenAI / Anthropic / Gemini official	Hands them the assembled prompt; never calls itself
Tracing / metrics	OpenTelemetry-aware dashboards	Emits OTel attributes; doesn't ship its own dashboard
Prompt templating	Your framework or plain strings	Produces a text block your template wraps

What contextweaver claims (and doesn't)

It claims:

Compile a phase-specific, budget-aware prompt from events and tools.
Bound the tool catalog to a small ChoiceCard shortlist at the route phase so the model never sees the whole catalog.
Run a context firewall so large tool results never reach the prompt raw.
Preserve dependency chains (parent_id) so tool calls and their results stay paired.
Deterministic, network-free, LLM-free in core paths — every benchmark number ships with the harness that produces it.

It does not claim:

To replace your agent framework, your model SDK, your memory system, or your retrieval stack.
To "make agents X % cheaper" or "solve tool selection at scale" — the benchmark scorecard reports specific scenarios under specific configurations, and the Known limits section documents where the default scorers degrade.
To improve answer quality. Better prompts can; that depends on the model and the agent loop. contextweaver gives you the prompt; the loop uses it.