Stop context rot before it silently breaks your agents.
A context compiler for LLM agents — score · compress · reorder · budget.

Quickstart · Benchmark · Guard · Docs · Use cases · Strategy · License

---

ContextForge is a context compiler that sits between your app and the model. It scores, compresses, reorders, and budgets everything entering the context window — so the model performs as if the input were short and clean.

Think compiler + linter for context, not another vector store.

---

The problem: context rot

Every frontier model degrades as input grows — not at the window limit, but well before it. Accuracy can fall 30–50% before the documented limit, with a sharp knee well under the advertised "1M-token" ceiling. Counterintuitively, coherent, well-structured input can degrade attention more than shuffled input, and the failures show up in long, multi-tool agent sessions — exactly where standard needle-in-a-haystack benchmarks miss them.

The result: a support agent that quietly starts giving wrong answers after a long chat. Nobody touched the prompt. The context just rotted.

What ContextForge does

   raw trace                         compiled context
 ┌───────────┐   ┌─────────────────────────────────┐   ┌───────────┐
 │ 280k tok  │   │ score → compress → reorder →     │   │  ~30k tok │
 │ tangled   │ ─▶│ budget   (auditable, lossless-ish)│ ─▶│ edge-     │
 │ history   │   │                                  │   │ anchored  │
 └───────────┘   └─────────────────────────────────┘   └───────────┘
       rot risk: 62/100 (high)            rot risk: 18/100 (low)

1. Score — a transparent 0–100 rot risk per call, broken into load, redundancy, middle_burial, and fragmentation. Put it in CI.
2. Compress — remove near-duplicates and trim provably stale, low-salience material. v0 is extractive and auditable — it never paraphrases away the one fact that mattered. (Abstractive LLM summarization is an opt-in upgrade.)
3. Reorder — fight "lost in the middle": lift load-bearing facts to a state header at the front and a recap at the back, where attention is strongest. Dialogue order is preserved; free-floating docs get arranged edges-in.
4. Budget — enforce a hard token ceiling, dropping the least-salient, non-pinned items first. Every drop is logged.

Everything is recorded in an action log — the "what the model actually saw" audit trail.

Quickstart

pip install -e .            # core has zero dependencies
# optional: exact token counts + real-model benchmarking
pip install -e ".[all]"

# 1. Score a trace's rot risk
contextforge score examples/sample_trace.json

# 2. Compile it down to a 30k-token budget and see the deltas
contextforge compile examples/sample_trace.json --budget 30000 --out compiled.json

# 3. See it on the bundled sample in one command
contextforge demo

Library

from contextforge import ContextCompiler, Trace

trace  = Trace.load("examples/sample_trace.json")
result = ContextCompiler(target_tokens=30_000).compile(trace)

print(result.summary())
messages = result.to_messages()      # hand straight to your model SDK
print(result.rot_before.total, "→", result.rot_after.total)

A Trace is just an ordered list of items (chat turns, tool results, retrieved docs, memories). Mark anything you must never lose with pinned: True.

The benchmark

The proof is a measured accuracy + token delta on real traces. The harness runs your model on the raw vs. compiled context and reports both:

# zero-setup proxy model (deterministic, runs in CI)
python -m bench.benchmark bench/datasets/sample_suite.json --model stub

# real frontier model
export ANTHROPIC_API_KEY=...
contextforge bench bench/datasets/sample_suite.json --model claude-opus-4-8

On the bundled buried-fact suite, the modeled agent misses the load-bearing fact in the raw 250k-token trace and recovers it after compilation — at a fraction of the tokens. Point it at your traces and find out what you'd win.

The bundled sample is filler-heavy by design to make rot legible; real traces vary. The number that matters is the one you measure on your own data.

Drop-in proxy (zero-code adoption)

Don't want to touch your code? Point your SDK's base_url at ContextForge. It parses each request, compiles the context, forwards the smaller request upstream, and returns the response unchanged — with the deltas in x-contextforge-* headers.

# Anthropic-compatible, compiling everything to a 30k budget
contextforge proxy --api anthropic --port 8788 --budget 30000

# Inspect what it *would* send, with no API key and no upstream call:
contextforge proxy --api anthropic --budget 30000 --dry-run

from anthropic import Anthropic
client = Anthropic(base_url="http://localhost:8788")   # that's the whole change

Works for --api openai too. Response headers report x-contextforge-rot-before/after and x-contextforge-tokens-before/after/saved.

The proxy streams (SSE passthrough with incremental egress redaction), exposes Prometheus /metrics, and can be network-hardened — TLS, client-key auth, rate limiting, --host bind. It ships a Dockerfile + Helm chart (deploy/) so it deploys as a real security/egress gateway or per-app sidecar (see docs/security.md).

Content blocks are flattened to text. Anchoring is best-effort from raw messages (no pinned/kind metadata); for maximum control, use the SDK with a curated Trace.

Per-model rot calibration

The degradation knee is a property of the model, not a constant. Measure it, then the rot score reflects how your model actually degrades.

# 1. Sweep accuracy vs. context size to get a degradation curve
python -m bench.sweep --model claude-opus-4-8 --out profiles/opus.json

# 2. Fit a knee and save it to the profile registry
contextforge calibrate profiles/opus.json --model claude-opus-4-8 --save

# 3. score/compile now auto-load the profile for that model
contextforge score examples/sample_trace.json --model claude-opus-4-8

Profiles live in profiles/profiles.json (override with $CONTEXTFORGE_PROFILES). This is the start of the real moat: a corpus of per-model knees fitted from evals.

Security governance — Guard

The proxy is also the perfect place to govern your AI traffic. ContextForge Guard is an agentic firewall — a WAF/antivirus for LLM traffic — that inspects every prompt, tool result, attachment, and response for secret leaks, PII, prompt injection, and data exfiltration, then redacts or blocks them inline.

# scan a trace (CI, audits) — exits non-zero if blocked
contextforge scan trace.json

# OWASP LLM Top 10 (2025) coverage report for a trace
contextforge audit trace.json

# enforce at the gateway (start with --guard-mode monitor to log-only)
contextforge proxy --api anthropic --guard --guard-mode enforce

• Detects API keys (OpenAI/Anthropic/AWS/GCP/GitHub/Slack/Stripe), JWTs, private keys, DB URIs, passwords, high-entropy blobs; email/SSN/credit-cards (Luhn); and injection/jailbreak/exfiltration patterns.
• Actions escalate allow < warn < redact < block; secrets are masked in logs.
• monitor mode logs everything and blocks nothing — measure before you enforce.
• A leaked key is [REDACTED:…] before it reaches the model provider; blocked requests return 403 and never forward. Results ride along as x-contextforge-guard-* headers.
• Mapped to the OWASP LLM Top 10 (2025) and the OWASP Agentic AI Threats taxonomy — contextforge audit --framework both reports coverage, honestly marking architectural risks it can't detect from traffic as advisory.
• Enterprise-ready: optional LLM-judge for obfuscated attacks (--judge), per-tenant policies (--tenants), a secret-free audit log (--audit-log), and a one-command HTML compliance report (contextforge report).

Full details: docs/security.md.

Use cases

Each is a written walkthrough plus a runnable, dependency-free demo.

• OpenClaw — a 24/7 personal agent whose context balloons across endless tool calls. 228k → 20k tokens (~91% smaller), rot moderate → low, a forgotten standing rule lifted back to the window edge. → examples/openclaw_proxy.py
• OpenHands — an autonomous coding agent that buries an early "don't touch the frozen module" constraint under steps of test output. 171k → 20k (~88%), constraint re-anchored to the edge. → examples/openhands_demo.py
• Support agent — a long support chat where the load-bearing refund fact rots mid-window. 252k → 20k (~92%); pairs with the benchmark to measure the accuracy delta, not just tokens. → examples/support_agent_demo.py

Documentation

• User Guide — install, CLI reference, SDK, the proxy, configuration, troubleshooting.
• Architecture — components, data model, the compiler pipeline, the request lifecycle, and extension points.
• Security (Guard) — detectors, OWASP LLM Top 10 + Agentic coverage, and deploying as a security proxy.
• Deployment — Docker, docker-compose, Helm.
• Use cases — OpenClaw · OpenHands · Support agent

Why this is defensible

The moat isn't any single model call — it's the eval data and the policies: a growing corpus of context-rot evals across models and tasks, learned compression/ordering tuning per model, and the switching cost once a team trusts your rot score in CI. Own the benchmark and the fix together.

Status

v0.1 — the 30-day smallest test, made real: an open context-rot benchmark and a CLI that, given a long-context trace, returns a compressed/re-ordered context with a measured accuracy + token delta. See STRATEGY.md for the wedge→platform plan and bench/README.md for the benchmark methodology.

Layout

contextforge/        the compiler (score · compress · reorder · budget)
  tokens.py          token counting (tiktoken or heuristic)
  salience.py        per-item importance scoring
  rot.py             context-rot risk score
  compress.py        normalize · dedup · truncate
  reorder.py         edge-anchoring + free-item reorder
  budget.py          hard token-ceiling enforcement
  compiler.py        the pipeline orchestrator
  adapters.py        Anthropic/OpenAI request <-> Trace conversion
  proxy.py           drop-in compiling proxy server (+ Guard firewall)
  firewall.py        security firewall (secrets · PII · injection · exfil)
  judge.py           LLM-judge hooks for obfuscated attacks
  owasp.py           OWASP LLM Top 10 (2025) taxonomy + coverage
  agentic.py         OWASP Agentic AI threats taxonomy + coverage
  tenants.py         per-tenant Guard policies
  audit_log.py       secret-free JSONL audit trail
  report.py          HTML compliance report from the audit log
  stream.py          streaming egress redaction (holdback scrubber)
  ratelimit.py       per-client sliding-window rate limiter
  metrics.py         Prometheus /metrics for guard decisions
deploy/              Dockerfile, docker-compose, Helm chart
  profiles.py        per-model rot-profile registry
  calibrate.py       fit a degradation knee from measurements
  cli.py             `contextforge` command
bench/               the reproducible benchmark harness
  benchmark.py       accuracy + token delta on a suite
  sweep.py           accuracy-vs-size sweep for calibration
profiles/            fitted per-model rot profiles
docs/use-cases/      integration use cases (e.g. OpenClaw)
assets/              logo, app icons, favicon, social card
examples/            sample trace + openclaw_proxy.py
tests/               pytest suite

License

Apache-2.0 (open-source core).