ContextSage

Information-aware context summarization for AI agents. ContextSage compresses long conversation histories while preserving important facts, tool relationships and provenance. Its asynchronous, framework-agnostic core uses a neutral message model and can be adapted to any agent framework.

Install

pip install contextsage

Install optional integrations only when you use them:

pip install "contextsage[langchain]"  # LangChain and LangGraph
pip install "contextsage[otel]"       # OpenTelemetry SDK and OTLP exporter
pip install "contextsage[all]"        # both optional integrations

The core requires Python 3.12 or newer and does not install an agent framework.

Framework-neutral quickstart

Implement parsefabric.LanguageModel with your summary provider, convert your framework's history to contextsage.Message, then call the async engine before the next model turn:

from contextsage import ContextSummarizer, ModelBudget


async def summarize_history(summary_model, messages):
    async with ContextSummarizer(
        summary_model,
        target_budget=ModelBudget(128_000),
        summary_budget=ModelBudget(64_000),
        trigger=("tokens", 100_000),
    ) as engine:
        result = await engine.summarize(messages, thread_id="conversation-42")
        if result is not None:
            messages = list(result.messages)

The engine parses text and structured content, compacts repetitive material, preserves facts such as identifiers and corrections, validates the result, and records lineage. If the history does not meet the trigger, summarize returns None. See the runnable quickstart and the core concepts.

The budgets above are illustrative: configure the actual agent and summary model limits, provider overhead, and model-specific token counters. If compaction is not enough, ContextSage can reduce oversized context using sequential, hierarchical, or explicitly grouped passes. It raises ReductionError when the configured constraints cannot be met safely. Summarization cannot guarantee semantic equivalence; protect exact text and choose a trusted provider when needed. See oversized-context reduction.

Integrations

The optional LangChain integration wraps the same core engine:

from contextsage import ModelBudget
from contextsage.integrations.langchain import IntelligentSummarizationMiddleware


def make_middleware(summary_model):
    return IntelligentSummarizationMiddleware(
        summary_model,
        target_budget=ModelBudget(128_000),
        summary_budget=ModelBudget(64_000),
        trigger=("tokens", 100_000),
        keep=("messages", 20),
    )

Or implement FrameworkAdapter for your framework's message type. The adapter maps between native messages and the neutral Message model; no framework dependency is needed by the core. See the LangChain integration and custom framework example.

Downstream customization

ContextSage exposes the extension points of its dependencies rather than restricting them to built-in choices:

Use ParsingOptions to configure parsefabric and create_agxai_runtime(...) to configure agxai. The downstream customization example demonstrates custom components from both packages.

Examples and documentation

The examples include framework adapters, LangChain, PostgreSQL provenance, OpenTelemetry, Prometheus, native reduction, custom parsing, policies, and safe failure. Scripted examples run without API keys and their output is verified in CI. The documentation site includes installation, configuration, integration guides, operations guidance and the API reference.

ContextSage also publishes an Agent Skill for coding agents that need to integrate or extend the package.

Development

uv sync --locked --all-extras --all-groups
uv run pytest
uv run ruff check .
uv run pyrefly check

See contributing and testing. ContextSage is licensed under the Apache License 2.0.