{
  "markdown": "# contextweaver\n\n<!-- mcp-name: io.github.dgenio/contextweaver -->\n\n[![CI](https://github.com/dgenio/contextweaver/actions/workflows/ci.yml/badge.svg)](https://github.com/dgenio/contextweaver/actions/workflows/ci.yml)\n[![PyPI version](https://img.shields.io/pypi/v/contextweaver.svg)](https://pypi.org/project/contextweaver/)\n[![Python versions](https://img.shields.io/pypi/pyversions/contextweaver.svg)](https://pypi.org/project/contextweaver/)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/dgenio/contextweaver/badge)](https://scorecard.dev/viewer/?uri=github.com/dgenio/contextweaver)\n[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://dgenio.github.io/contextweaver)\n[![GitHub Discussions](https://img.shields.io/github/discussions/dgenio/contextweaver)](https://github.com/dgenio/contextweaver/discussions)\n\n> **Capture an agent's effective capability surface, commit it, and see semantically meaningful changes before deployment.**\n\nContextWeaver is currently testing a deliberately narrow product hypothesis:\n**capability snapshot + semantic drift**.\n\nGiven an OpenAPI document, a captured MCP `tools/list` response, or a native\nContextWeaver catalog, the D1 experiment produces a deterministic normalized\nsnapshot that you can inspect, verify, and compare with a later candidate.\nIt does not require a model account, a gateway, a tool executor, or the Weaver\nStack.\n\n**Status:** alpha, and specifically a **product experiment**. The implementation\nworks and is tested; the user-value hypothesis is not yet proven. The project is\nactively measuring whether independent users keep this workflow after trying it\non real projects.\n\n## Try the capability-drift experiment\n\nClone the repository and install that checkout so the maintained example\nfixtures and the code under evaluation are guaranteed to match:\n\nCommands below use `python3`, matching the repository's documented default (`docs/agent-context/workflows.md`). On Windows installations that expose Python through the launcher, replace `python3` with `py -3`; if your environment already exposes the intended interpreter as `python`, use that consistently.\n\n```bash\ngit clone --depth 1 https://github.com/dgenio/contextweaver.git\ncd contextweaver\npython3 -m pip install .\n```\n\nRun the maintained OpenAPI example:\n\n```bash\npython3 -m contextweaver.d1 snapshot examples/d1/openapi_before.json --source-type openapi --output ./cw-before.json\npython3 -m contextweaver.d1 snapshot examples/d1/openapi_after.json --source-type openapi --output ./cw-after.json\npython3 -m contextweaver.d1 inspect ./cw-after.json\npython3 -m contextweaver.d1 verify ./cw-after.json\npython3 -m contextweaver.d1 diff ./cw-before.json ./cw-after.json\n```\n\nThe candidate fixture intentionally:\n\n- makes `customer_id` required on the existing `listInvoices` capability;\n- changes its description;\n- adds a new `getInvoice` capability.\n\nThe diff separates capability additions/removals from changes to an existing\nlogical capability and reports the structured paths that changed. Contract\nchanges are separated from documentation-only changes. Changes involving fields\nsuch as `required`, `type`, or `enum` are flagged as **potentially breaking** for\nreview.\n\nThat flag is intentionally conservative: ContextWeaver does **not** claim to be\na complete JSON-Schema compatibility checker.\n\nFull walkthrough: [Capability drift experiment](docs/d1_capability_drift.md).\n\n## Use it on your own source\n\n### OpenAPI\n\n```bash\npython3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities.json\npython3 -m contextweaver.d1 verify ./capabilities.json\n```\n\nAfter the API changes:\n\n```bash\npython3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities-candidate.json\npython3 -m contextweaver.d1 diff ./capabilities.json ./capabilities-candidate.json\n```\n\n### Captured MCP tools\n\nIf you already have an MCP `tools/list` response saved as JSON:\n\n```bash\npython3 -m contextweaver.d1 snapshot ./tools-list.json \\\n  --source-type mcp \\\n  --output ./capabilities.json\n```\n\nFor MCP, D1 compares tools by their upstream logical name so an input-schema\nedit appears as a change to the same capability rather than an unexplained\nremove/add pair. The historical schema-sensitive routing ID is retained\nseparately as `normalized_id` for inspection.\n\nCapturing a live MCP server is a separate operation. `snapshot`, `inspect`,\n`diff`, and `verify` do not execute discovered capabilities.\n\n### Native ContextWeaver catalog\n\n```bash\npython3 -m contextweaver.d1 snapshot ./catalog.json \\\n  --source-type native \\\n  --output ./capabilities.json\n```\n\n## What `verify` means\n\n`verify` checks the D1 snapshot contract: structure, deterministic ordering,\nlogical-ID uniqueness, and the canonical capability digest.\n\nIt is **not**:\n\n- deployment approval;\n- security certification;\n- authentication or authorization;\n- a guarantee that a tool implementation is correct;\n- routing-quality evaluation;\n- production runtime attestation.\n\n## When not to use ContextWeaver D1\n\nA negative answer is useful evidence for this project. Do **not** add\nContextWeaver just because capability snapshots sound tidy.\n\nUse something simpler when:\n\n- **ordinary Git diff, config review, and tests already make your capability\n  changes obvious;**\n- your tool/API surface is tiny and rarely changes;\n- provider-native tool search is the only problem you are trying to solve;\n- you need an agent loop, tool executor, IAM layer, or production orchestrator;\n- maintaining another committed artifact costs more than the review/debugging\n  problem it removes.\n\nIf you try D1 and conclude that Git/tests are cheaper, that is a valid product\nresult — please say so.\n\n## What is being tested\n\nThe current survival experiment asks a stronger question than whether the code\nworks:\n\n> Do capability snapshots and semantic drift reports improve a real\n> review/manual/risk process enough that independent users keep them?\n\nThe project distinguishes:\n\n```text\nqualified exposure\n  -> understood the problem\n  -> chose to evaluate\n  -> attempted setup\n  -> reached first useful output\n  -> used on a real project\n  -> retained independently / removed\n```\n\nStars, forks, downloads, a successful demo, and maintainer-created integrations\nare not treated as retained adoption.\n\nThe controlling product decision is tracked in\n[#758](https://github.com/dgenio/contextweaver/issues/758), and the distribution\nquality gate is [#855](https://github.com/dgenio/contextweaver/issues/855).\nUnassisted first success and retention are tracked in\n[#658](https://github.com/dgenio/contextweaver/issues/658) and genuine adoption\nin [#551](https://github.com/dgenio/contextweaver/issues/551).\n\n## What about routing, context compilation, and the MCP gateway?\n\nContextWeaver already contains substantial historical runtime functionality.\nThat code still exists and currently shipped behavior should remain truthful and\nsafe, but **existing implementation is not evidence that the project should\nkeep expanding it**.\n\nTwo broader hypotheses are explicitly evidence-first:\n\n- **D2 — bounded / phase-aware context compilation:** conditional. It must show\n  consequential value beyond contemporary provider/runtime-native mechanisms.\n- **D3 — custom deterministic tool selection:** a falsification track. It must\n  beat modern provider-native tool search/deferred loading or a simple retrieval\n  baseline on something target users actually care about.\n\nDuring the D1 experiment, the project is not expanding routing sophistication,\nruntime bundle machinery, memory/session surfaces, framework breadth, gateway\nscope, vector stores, or model-assisted enrichment without a concrete external\nblocker or approved falsification experiment.\n\nIf you are maintaining an existing integration that uses those historical\nsurfaces, the relevant documentation remains available:\n\n- [Which historical pattern fits?](docs/which_pattern.md)\n- [Context firewall](docs/context_firewall.md)\n- [MCP Context Gateway architecture](docs/architectures/mcp_context_gateway.md)\n- [MCP gateway security model](docs/security_model.md)\n- [Comparison / alternatives](docs/comparison.md)\n- [Ecosystem map](docs/ecosystem.md)\n\n## Evidence and claims\n\nThe D1 implementation supports scoped engineering claims such as deterministic\nsnapshot construction under the documented source/adapter contract and\nstructured semantic-diff output. It does **not** yet support the stronger claim\nthat users need or retain the product.\n\nThe historical token-reduction headline is intentionally not used to sell D1.\nThe current evidence-integrity work for those older benchmark claims is tracked\nin [#841](https://github.com/dgenio/contextweaver/issues/841).\n\nSee [Claims & evidence](docs/claims.md) for the claim registry and\n[Capability drift experiment](docs/d1_capability_drift.md) for the exact D1\ncontract and limitations.\n\n## Python API stability\n\nD1 is intentionally exposed through:\n\n```bash\npython3 -m contextweaver.d1 ...\n```\n\nrather than being promoted immediately into the historical top-level CLI or a\nlarge new public Python API. That is deliberate. The experiment should earn a\npermanent surface through real retained use before the project takes on another\ncompatibility obligation.\n\n## Part of the Weaver Stack — optionally\n\nContextWeaver can be used standalone. It has no hard dependency on the sibling\nWeaver projects.\n\nThe wider Weaver Stack contains adjacent experiments/components for planning,\nexecution boundaries, guardrails, lessons, and evaluation. That ecosystem is\n**not required** to evaluate D1, and Stack coherence is not a reason to preserve\na ContextWeaver feature that does not justify itself independently.\n\nSee the [Ecosystem map](docs/ecosystem.md) only if you actually need those\nadjacent responsibilities.\n\n## Install and compatibility\n\n```bash\npip install contextweaver\n```\n\nPython 3.10–3.14 are covered by the repository CI matrix.\n\nCurrent package version: **0.18.2**\n\n| Project | Release |\n|---|---|\n| ContextWeaver (this repo, [v0.18.2](https://github.com/dgenio/contextweaver/releases/tag/v0.18.2)) | current package release |\n\nThe repository is pre-1.0. Prefer the latest supported patch release for bug and\nsecurity fixes, and check the changelog before relying on historical runtime\nAPIs.\n\n## Current roadmap\n\nThe roadmap is intentionally a product-decision sequence, not a feature queue.\n\n| Milestone | Status | Meaning |\n|---|---|---|\n| **v0.18.1 — D1 survival experiment baseline** | ✅ complete | Offline snapshot/inspect/diff/verify exists; user value remains unverified. |\n| **v0.18.2** | ✅ current (v0.18.2) | D1 survival experiment and release-path recovery |\n| **D1 distribution gate** | 🔬 evidence first | Make the front door understandable, recruit qualified evaluators, measure first success and retention. |\n| **D1 decision** | ⏸ next decision | Continue, shrink further, or kill based on retained value after competent distribution. |\n| **D2 / D3** | 🧪 conditional | Run only if D1 evidence or independent problem discovery justifies bounded falsification experiments. |\n\nA green CI run does not advance this roadmap by itself.\n\n## Contributing\n\nThe most valuable contributions during the survival experiment are narrow and\nevidence-linked:\n\n- a real D1 evaluator blocker;\n- a semantic-diff case that is currently misleading or silently lost;\n- deterministic normalization correctness;\n- security/release maintenance for behavior the package still ships;\n- negative evidence showing a simpler alternative wins.\n\nPlease do not add a framework adapter, routing policy, storage backend, runtime\nphase, or ecosystem integration solely for completeness.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for repository\nengineering conventions.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for supported-version and vulnerability-reporting\nguidance. Do not include credentials, customer data, proprietary schemas, or\nprivate prompts in public adoption/evaluation reports.\n\n## Documentation\n\n- [Documentation site](https://dgenio.github.io/contextweaver)\n- [Capability drift experiment](docs/d1_capability_drift.md)\n- [Claims & evidence](docs/claims.md)\n- [Daily Driver guide](docs/daily_driver.md) — historical/runtime users\n- [Cookbook](docs/cookbook.md) — broader shipped surfaces\n- [FAQ](docs/faq.md)\n- [Changelog](CHANGELOG.md)\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n",
  "bytes": 12575,
  "sha": "6b7141293ba5515605c64aee819e48c008c2bb7f3d5edf643be421f42a6bbdaf",
  "repo_slug": "dgenio/contextweaver",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dgenio_contextweaver_58d6dad0/readme"
}