上下文编织

Install

pip install contextweaver

contextweaver ships with a minimal, opinionated core: tiktoken, PyYAML, rank-bm25, mcp, jsonschema, Typer, and Rich. These power token budgeting, YAML catalog/config files, the default lexical retrieval backend, the MCP proxy/gateway runtime, schema validation, and the CLI.

Optional capabilities are gated behind extras so the core install stays small:

Or from source:

git clone https://github.com/dgenio/contextweaver.git
cd contextweaver
pip install -e ".[dev]"

Quickstart

10-Minute Quickstart

For a guided setup with prerequisites, three runnable examples, expected output, and next steps, see docs/quickstart.md.

Already have an agent and not sure which piece you need? See Which pattern fits my use case? — a symptom-based decision tree (long conversations → full pipeline; 50+ tools → routing-only; huge tool outputs → firewall-only) that points each branch to one concrete next step.

Examples

make example   # run all examples

---

Framework Integrations

Looking for "where does contextweaver fit alongside my runtime?" — start with the How contextweaver Fits positioning page, then jump into the Cookbook for copy-paste recipes.

---

7. Comparison

Snapshot of the launch landscape as of 2026-05-31 — see footnotes for the versions referenced and the evidence behind each non-trivial claim. Will be refreshed each minor release.

[^cw-route]: contextweaver.routing.router.Router ships a four-stage pipeline (retrieve → rerank → navigate → pack) with deterministic tie-break by id. Locked by tests/test_cards.py::test_make_choice_cards_byte_identical_stable_order. [^cw-bench]: Range from the committed scorecard (benchmarks/scorecard.md) using tiktoken.cl100k_base against the naïve baseline (scripts/baseline_naive.py). Average 64.3 %; min 41.6 % on long_conversation.jsonl; max 84.3 % on tiny_payload.jsonl. [^cw-fire]: contextweaver.context.firewall.apply_firewall plus ArtifactRef drilldown selectors (head / lines / json_keys / rows). See docs/context_firewall.md and the firewall_drilldown_recipe. [^cw-det]: Determinism is an invariant — see docs/agent-context/invariants.md and make scorecard-check in the CI gate. [^cw-mcp]: src/contextweaver/adapters/mcp_proxy.py, mcp_gateway.py, mcp_proxy_server.py, mcp_gateway_server.py. Bound by docs/gateway_spec.md. [^lg-mem]: LangGraph 0.6 docs ("Memory"): ConversationSummaryMemory requires an LLM round-trip to produce a summary; output is non-deterministic across runs even with temperature=0 due to model jitter. [^li-mem]: LlamaIndex 0.11 docs ("Chat memory"): ChatMemoryBuffer(token_limit=...) truncates oldest-first; no phase awareness and no dependency closure.

Most agent frameworks offer one or two of these capabilities. contextweaver ships all five as a composable, framework-agnostic layer that runs under whichever framework you already have.

---

FAQ

Q: What token budgets should I use? Start with the defaults (route=2000, call=3000, interpret=4000, answer=6000). Inspect pack.stats after each build and increase any phase that drops too many items.

Q: My tool result was summarized. Why? The context firewall intercepts every tool_result item (not just large ones). Raw data is stored out-of-band; access it via mgr.artifact_store.get("artifact:<item_id>"). Provide a custom Summarizer to control how the summary is generated.

Q: How do I debug what was kept or dropped? Inspect pack.stats (a BuildStats object) after every build_sync() / build() call: included_count, dropped_count, dropped_reasons, dedup_removed.

Q: Does this work with [framework X]? Yes, contextweaver is framework-agnostic — it compiles context; you send pack.prompt to any LLM or framework. See dedicated guides for MCP, A2A, LlamaIndex, LangChain + LangGraph, OpenAI Agents SDK, Google ADK / Vertex AI, Pipecat, CrewAI, Pydantic AI, smolagents, and Agno. If your runtime isn't listed, the bring-your-own-tools cookbook recipe is the canonical starting point.

Q: What's the performance overhead? Typically 10–50 ms for a context build (depends on event log size and deduplication). For real-time / async agents, run build_sync() in a worker thread (e.g. await asyncio.to_thread(mgr.build_sync, phase, query)) so the synchronous pipeline does not block the event loop. If an offline or air-gapped run prints a tiktoken cl100k_base encoding unavailable warning, see the troubleshooting note; the fallback keeps budget enforcement deterministic.

See docs/troubleshooting.md for the full troubleshooting guide, debugging techniques, optimisation tips, and 10+ common issues with solutions.

---