ContextSage

ContextSage is an intelligent, production-grade replacement for LangGraph's built-in SummarizationMiddleware. It adds an information-aware planning layer on top of LangGraph/LangChain's existing summarization mechanism, so that when an agent's context grows too large, ContextSage decides what should be preserved, compressed, or left untouched — instead of blindly summarizing "the oldest messages first".

from langchain.agents import create_agent
from contextsage import IntelligentSummarizationMiddleware

middleware = IntelligentSummarizationMiddleware(
    model=model,
    trigger=("tokens", 100_000),
    keep=("messages", 20),
)

agent = create_agent(
    model=model,
    tools=tools,
    middleware=[middleware],
)

That's it. Everything else — context decomposition, importance scoring, preservation requirements, provenance tracking, validation, and recovery — happens automatically inside the middleware.

Why ContextSage?

Modern agents accumulate heterogeneous context: natural language, JSON, logs, stack traces, tool metadata, tables, and code, often mixed together in a single large tool result. LangGraph's SummarizationMiddleware is a solid, general-purpose building block, but it does not:

• distinguish between critical and disposable information,
• protect user corrections and active constraints from being lost,
• deterministically compress structured/log content instead of paying for an LLM call on data an LLM doesn't need to read,
• validate that a summary didn't silently drop something important,
• recover gracefully if summarization fails or a summary is invalid.

ContextSage adds exactly this intelligence layer, while reusing — not reimplementing or forking — LangGraph's own semantic summarization for the parts only an LLM can do well.

Principle

Information preservation > raw token reduction.

A smaller summary that loses a customer ID, a user correction, or a root cause is a failure, even if it saves tokens. ContextSage's planner is budget-aware and information-aware.

Installation

pip install contextsage

langgraph-xai is installed automatically as a direct dependency and used internally for provenance/evidence tracking — no separate setup required. Authoritative OpenAI-compatible token counting via tiktoken, and real code-structure detection via tree-sitter, are also core dependencies — no optional extras to install for ContextSage's default behavior.

How it works

Complete context
      |
      v
Heterogeneous context decomposition -> Context units
      |
      v
Structural signals -> Importance -> Relationships / Provenance
      |
      v
Preservation requirements -> Summarization plan
      |
      v
Selective deterministic transformation
      |
      v
LangGraph semantic summarization (reused, not forked)
      |
      v
Validation -> Recovery (if needed) -> Reconstruction

See docs/architecture.md for the full design and docs/ for component-level documentation.

Examples

Runnable examples live in examples/ and call a real, network-backed chat model (via examples/_llm.py) so their output reflects genuine model behavior rather than a scripted fake. Install the examples extra, then copy .env.example to .env and set EXPLABS_API_KEY:

pip install -e ".[examples]"
cp .env.example .env  # then fill in EXPLABS_API_KEY
python examples/basic.py

What ContextSage is not

• Not an agent framework, memory framework, or a replacement for LangGraph/LangChain.
• Not a general-purpose parser/document-processing framework.
• Not a new plugin platform — there is no public plugin registry.

ContextSage stays narrowly focused on one job: intelligent context summarization for LangGraph/LangChain agents.

Contributing

See CONTRIBUTING.md for development setup and pull request guidelines. This project follows the Code of Conduct. For security issues, see SECURITY.md instead of opening a public issue.

License

Apache License 2.0. See LICENSE.