Commitment-Preserving, Position-Aware Semantic Substrate
Context is not a buffer. It is a graph of active commitments — and every compression must prove what it keeps.
LLMs treat context as a passive buffer. That is the wrong abstraction.
When a long-horizon agent runs, the context accumulates goals, constraints, decisions, safety boundaries, and tool results. These are not just text — they are commitments. And every current tool ignores that distinction:
- headroom — compresses by content type, but doesn't know which constraint survived
- LLMLingua-2 — prunes by perplexity, never noticing that the line "never use Redis" looks unimportant
- Letta/MemGPT — summarizes, but doesn't measure what the summary lost
- Anthropic compact-2026 — its own documentation says: "it is hard to know which tokens will be needed"
The result has been measured: when structural facts are compressed 36.7×, 60% are unrecoverable regardless of their importance (arXiv:2603.17781). The loss of a single constraint — "never move data outside the EU", "don't touch auth.py" — invalidates the entire architecture.
Worse, even preserved information goes unread if it lands in the middle of the context. Liu et al. (TACL 2024) measured a drop of more than 20% in multi-document QA. And although this calibration has been known since 2024, it has never been built into any context-management tool.
COMPASS unifies these two problems — commitment preservation and position bias — in a single layer for the first time.
Raw context (messages + tool results + retrieved docs)
│
▼
┌─────────────────────────────────────────────────────┐
│ Component 1 — Atom Extractor (Python) │
│ │
│ Splits context into 11 types of semantic atoms: │
│ goal · constraint · decision · entity · │
│ procedure · preference · state · │
│ output_contract · open_question · │
│ safety_boundary · verbatim_snippet │
│ │
│ Each atom: [type, subject, predicate, value, │
│ modality, scope, evidence-span, confidence, risk] │
│ Basis: Context Codec (arXiv:2605.17304) │
└─────────────────────┬───────────────────────────────┘
│ atoms
▼
┌─────────────────────────────────────────────────────┐
│ Component 2 — Criticality Scorer (Python) │
│ │
│ Assigns a risk-if-lost score to each atom. │
│ Targets the Weighted Atom Recall objective. │
│ Basis: Context Codec metrics; │
│ KVzip importance score (arXiv:2505.23416); │
│ Global utility estimation (arXiv:2602.08585)│
└─────────────────────┬───────────────────────────────┘
│ scored atoms
▼
┌─────────────────────────────────────────────────────┐
│ Component 3 — Position-Aware Placer (Rust) │
│ │
│ High-criticality atoms → head / tail │
│ (the high-attention regions of the U-curve) │
│ Low-risk blocks → middle │
│ (the compression zone) │
│ │
│ Basis: Found in the Middle (arXiv:2406.16008); │
│ Layer-Specific RoPE (arXiv:2503.04355); │
│ SemanticZip (arXiv:2605.24541) │
└─────────────────────┬───────────────────────────────┘
│ re-ordered context
▼
┌─────────────────────────────────────────────────────┐
│ Component 4 — Runtime Verifier (Python + Rust) │
│ │
│ Measures round-trip Critical Atom Recall (CAR) │
│ after compression with an independent decoder. │
│ CAR < threshold → REJECT the compression or │
│ re-insert that atom as a raw span. │
│ │
│ Basis: Context Codec round-trip definition; │
│ Prompt preservation measurement (2503.19114)│
└─────────────────────┬───────────────────────────────┘
│ verified + compressed context
▼
┌─────────────────────────────────────────────────────┐
│ Component 5 — Reversible Store (Rust) │
│ │
│ Discarded atoms are restored on demand. │
│ Decompression is O(1), lossless. │
│ Basis: ClusterKV (arXiv:2412.03213); │
│ EDU source-index anchoring (2512.14244) │
└─────────────────────┬───────────────────────────────┘
│
▼
LLM API (any provider)
Python — orchestration and the pluggable, offline intelligence:
- Atom extraction (deterministic rules + local-embedding zero-shot classification)
- Criticality scoring policy (pluggable; heuristic + graph centrality)
- Verifier orchestration (embedding round-trip recall)
- Public API
Rust (PyO3) — everything that runs on the proxy hot-path of every LLM call:
- Atom matching and normalization (fuzzy matching, canonical identity)
- Positional placement solver (budget-constrained combinatorial optimization)
- Token counting and store indexing
pip install compass-ctxfrom compass_core import COMPASS
ctx = COMPASS()
compressed = ctx.prepare(
messages=conversation_history,
tool_results=tool_outputs,
retrieved_docs=rag_chunks,
token_budget=8000,
min_car=0.95, # minimum Critical Atom Recall threshold
reorder=True, # position-aware placement
)
# Use it with any OpenAI-compatible API
response = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=compressed.messages,
)
# Compression statistics
print(compressed.stats)
# {
# "atoms_extracted": 47,
# "atoms_protected": 12,
# "car_achieved": 0.97,
# "token_reduction": 0.61,
# "verifier_rejections": 2, # how many times compression was rejected
# }
# Lossless restore of the original context
original = ctx.decompress(compressed)Fully offline. COMPASS needs no API keys and no LLM calls — extraction,
scoring and verification are deterministic + embedding-based. For semantic
recall install the embeddings extra (pip install "compass-ctx[embeddings]",
local sentence-transformers); without it the engine degrades to a fast lexical
mode. The Rust hot-path (placer, matcher, compressor) is optional too — a pure
Python fallback is used when it isn't built.
from compass_core import COMPASS, EngineConfig
ctx = COMPASS(engine=EngineConfig(embeddings="local", store="disk"))pip install "compass-ctx[proxy]"
compass proxy --port 8788 --target https://api.anthropic.com --min-car 0.95Compresses every inbound request before forwarding upstream and returns the
achieved recall in X-COMPASS-CAR / X-COMPASS-Token-Reduction headers.
pip install "compass-ctx[mcp]"
compass mcp # exposes compass_prepare / compass_verify / compass_decompress| Metric | Baseline | COMPASS Target |
|---|---|---|
| Critical Atom Recall (CAR) | — (not measured) | ≥ 0.95 |
| Weighted Atom Recall (WAR) | LLMLingua-2 (comparison) | Statistically significant improvement |
| Critical-atom loss rate | 60% @ 36.7× (2603.17781) | ≤ 10% |
| Token reduction (tool-heavy) | Headroom ~80% | ≥ 70% (verified) |
| Downstream accuracy preservation | — | ≥ 95% of the no-compression upper bound |
| Verifier overhead (p50) | — | < 100ms |
Benchmarks: LongBench v2 (arXiv:2412.15204), RULER (arXiv:2404.06654), ACON position-controlled recall test.
In-repo benchmark (python tests/bench/harness.py, synthetic needle-in-chatter,
offline lexical mode): on an early-stated critical requirement buried under 20 filler
turns at a 400-token budget, COMPASS keeps the requirement in 8/8 cases versus
0/8 for naive keep-recent truncation, at 63% token reduction, CAR 1.0,
p50 latency ~2 ms.
Questions that have no answer yet but must be addressed while developing this technology:
- The extractor is deterministic + embedding-based (no LLM). How much recall does this trade away versus an LLM extractor, and where is the crossover where an optional LLM extractor would be worth the cost?
- Does positional re-placement break prefix-cache consistency? (Anthropic caching on Sonnet: $3.00/M → $0.30/M; re-placement may forfeit that discount.) The proxy keeps role order stable to avoid this — is atom-level placement recoverable without busting the cache?
- The verifier measures recall with local embeddings. How close does embedding-cosine round-trip track an LLM-judge round-trip, and when is the judge actually needed?
- "Criticality" is subjective; can the heuristic risk score be replaced by a learned, task-independent scorer?
- In multi-agent handoff, can atom-level commitments be combined with KV-cache handoff?
| Paper | What we implement |
|---|---|
| Context Codec (arXiv:2605.17304) | Atom schema, CAR/WAR metrics, round-trip verification |
| Found in the Middle (arXiv:2406.16008) | PARE position calibration |
| Layer-Specific RoPE (arXiv:2503.04355) | Positional placement scoring |
| KVzip (arXiv:2505.23416) | Query-independent importance scoring |
| EDU Compression (arXiv:2512.14244) | Atom source-index anchoring |
| SemanticZip (arXiv:2605.24541) | Preserved/lossy channel separation |
| Facts as First Class Objects (arXiv:2603.17781) | Commitment-amnesia motivation |
| ClusterKV (arXiv:2412.03213) | Reversible store |
| ACON (arXiv:2510.00615) | Failure-driven guideline loop |
| Context Engineering Survey (arXiv:2507.13334) | Taxonomy and framing |
Full research document: papers/RESEARCH.md
compass/
├── compass_core/
│ ├── api.py — COMPASS.prepare() / verify() / decompress() facade
│ ├── cli.py — `compass proxy` / `compass mcp` / `compass info`
│ ├── tokens.py — TokenCounter (tiktoken)
│ ├── core/ — pipeline.py (orchestration), config.py, result.py
│ ├── atoms/ — Component 1: schema, classify, extractor, to_scg
│ ├── scorer/ — Component 2: criticality policy + budget planning
│ ├── reorder/ — Component 3: placer.py (facade) + pare.py (fallback)
│ ├── verifier/ — Component 4: runtime_verifier.py + recall.py
│ ├── store/ — Component 5: memory + sqlite reversible store
│ ├── embeddings/ — local (sentence-transformers) + noop providers
│ ├── compression/ — fallback.py (pure-Python compressor)
│ ├── proxy/ — FastAPI compressing proxy
│ └── mcp/ — MCP server
├── crates/
│ └── compass-rsc/src/ — Rust hot-path (PyO3):
│ ├── compress.rs reversible semantic compression
│ ├── placer.rs budget-constrained positional solver
│ ├── matcher.rs canonical hashing + fuzzy matching
│ └── text.rs EDU segmentation + similarity
├── tests/{unit,integration,bench}/
├── papers/RESEARCH.md — academic basis and gap analysis
└── pyproject.toml
- v0.1 — SCG + PARE (Python) → COMPASS foundation
- v0.2 — Atom Extractor (11-type Context Codec schema) + runtime CAR
- v0.3 — All five components implemented (offline), Rust placer + matcher, embedding verifier, reversible store, working proxy + MCP server
- v0.4 — Optional LLM extractor/judge; prefix-cache-safe atom placement
- v0.5 — Learned criticality scorer
- v0.6 — Multi-agent commitment handoff
- v1.0 — LongBench v2 + RULER + ACON benchmark suite
See CONTRIBUTING.md for details. Contributions we are especially looking for:
- Code and structured-data segmentation for atom extraction
- Reducing the verifier to a small distilled model (Open Question 3)
- LangChain / LangGraph / Agno integrations
- LongBench v2 benchmark contributions
@software{compass2026,
title = {COMPASS: Commitment-Preserving, Position-Aware Semantic Substrate},
year = {2026},
url = {https://github.com/cgntanriverdi/compass},
note = {Academic foundations: Context Codec (arXiv:2605.17304),
Found in the Middle (arXiv:2406.16008),
Layer-Specific RoPE (arXiv:2503.04355)}
}Apache 2.0 — LICENSE