contextweaver

# contextweaver

> Dynamic context management for tool-using AI agents.

contextweaver is a Python library that provides two integrated engines: a
phase-specific, budget-aware Context Engine and a bounded-choice Routing Engine
for large tool catalogs. Zero runtime dependencies, deterministic output,
Python ≥ 3.10.

## Docs

- [Architecture](docs/architecture.md): Package layout, pipeline stages, design principles
- [Concepts](docs/concepts.md): ContextItem, phases, firewall, ChoiceGraph, sensitivity enforcement
- [Quickstart](docs/quickstart.md): 10-minute guide to context builds, firewall, and routing
- [Daily Driver](docs/daily_driver.md): Operator workflow, client instructions, fit guidance, and debugging
- [MCP Security Model](docs/security_model.md): Gateway data flow, trust boundaries, artifact exposure, and hardening
- [MCP Gateway Security Guide](docs/security_mcp_gateway.md): Least-privilege gateway ops: secrets, destructive tools, policy gate
- [Sensitivity & Redaction](docs/sensitivity.md): Levels, floor/action, redaction hooks, verification, and limits
- [MCP Client Recipes](docs/recipes/index.md): Claude Desktop, Claude Code, GitHub Copilot, and Cursor setup
- [Knowledge Bundle Recipes](docs/recipes/okf_bundle.md): OKF, repository knowledge, lessons, and expertise-pack context sources
- [MCP Integration](docs/integration_mcp.md): MCP adapter functions, JSONL format, end-to-end example
- [A2A Integration](docs/integration_a2a.md): A2A adapter functions, multi-agent sessions
- [Agent Loop Guide](docs/guide_agent_loop.md): Flow diagram and phase guidance for building a complete agent loop
- [Error Reference](docs/errors.md): Exception hierarchy with stable error codes, causes, and fixes

## Agent Context

- [Agent Architecture](docs/agent-context/architecture.md): Non-obvious architectural guidance, design tradeoffs, and async/sync boundaries
- [Invariants](docs/agent-context/invariants.md): Hard constraints and forbidden shortcuts in the codebase
- [Workflows](docs/agent-context/workflows.md): Authoritative commands, sequencing, and definition of done
- [Lessons Learned](docs/agent-context/lessons-learned.md): Recurring failure patterns and how to avoid them
- [Review Checklist](docs/agent-context/review-checklist.md): Self-check and review gates for contributors

## API

- [Types](src/contextweaver/types.py): Core dataclasses (SelectableItem, ContextItem, Phase, ItemKind, Sensitivity)
- [Config](src/contextweaver/config.py): Configuration dataclasses (ContextBudget, ContextPolicy, ScoringConfig)
- [Protocols](src/contextweaver/protocols.py): Protocol interfaces (TokenEstimator, EventHook, Summarizer, Extractor)
- [Envelope](src/contextweaver/envelope.py): Result types (ResultEnvelope, BuildStats, ContextPack, ChoiceCard)
- [Context Manager](src/contextweaver/context/manager.py): Main entry point for context builds (build, ingest, ingest_tool_result)
- [Router](src/contextweaver/routing/router.py): Beam search routing over ChoiceGraph
- [Catalog](src/contextweaver/routing/catalog.py): Tool catalog management and hydration

## Examples

- [Minimal Loop](examples/minimal_loop.py): Basic event ingestion → context build
- [Tool Wrapping](examples/tool_wrapping.py): Context firewall in action
- [Routing Demo](examples/routing_demo.py): Build catalog → route queries → choice cards
- [Before/After](examples/before_after.py): Comparing raw vs. firewall-processed context
- [MCP Adapter Demo](examples/mcp_adapter_demo.py): End-to-end MCP session ingestion and context build
- [A2A Adapter Demo](examples/a2a_adapter_demo.py): End-to-end A2A multi-agent session demo
- [Hydrate Call Demo](examples/hydrate_call_demo.py): Enrich a tool call with context-aware hydration
- [Full Agent Loop](examples/full_agent_loop.py): End-to-end 4-phase runtime loop (route → call → interpret → answer)
- [LangChain Memory Demo](examples/langchain_memory_demo.py): Replacing LangChain InMemoryChatMessageHistory with contextweaver budgets