Context Guardian

Context Guardian

Status: active development -- changelog

mcp-name: io.github.LuminariSoftwares/context-guardian

A 40-turn session: 1,130,722 tokens sent upstream without it, 161,141 with it.

A compaction proxy for OpenAI-compatible local backends that fails open, so a long session stops dying at the context limit.

Quick start (60 seconds)

Local model CLI, through the proxy:

pip install context-guardian && context-guardian   # proxy on :8786 in front of Ollama on :11434; set OPENAI_BASE_URL=http://localhost:8786/v1

context-guardian-doctor # second terminal: checks the install and the running proxy, prints a fix: line for anything wrong

With an AI agent: paste one line, "Install context-guardian (docs: https://raw.githubusercontent.com/LuminariSoftwares/context-guardian/main/llms.txt) and point my client at it". llms.txt is the whole install, configure, recall and limits story in one short file an agent can read.

Another backend or window: see examples/ or Configure. Your client's settings: Point your client at the proxy. After a compaction, context-guardian-recall " " searches the archived originals (the summary the model receives names the exact command and the MCP tools).

DeepSeek Harness: dsh plugin --profile web add dsh-context-guardian, then npm run setup -- --apply in the installed package. Full steps: Install both.

Claude Code:

pip install context-guardian

context-guardian-claude-code install # prints the hooks and the claude mcp add command; changes nothing context-guardian-claude-code install --apply # backs up ~/.claude/settings.json, merges the hooks, prints the diff claude mcp add --scope user --transport stdio context-guardian -- uvx context-guardian mcp

Details: Claude Code.

Proof

python scripts/bench_proxy.py --turns 40 --seed 1

turns=40 tokens_before=1130722 tokens_after=161141 compactions=27

Run 2026-11-05 on v0.15.0, Python 3.11, against a stub upstream.

623 passed, 1 warning in 106.22s (0:01:46)

python -m pytest -q, run 2026-11-05.

The bench runs against a stub upstream, not a real model; the token figures are the same on any machine. Fails open. If a summary fails, comes back empty or anything in the proxy raises, the request goes upstream exactly as your client sent it. Ollama (daily use) and DeepSeek Harness 0.1.2-alpha.2 are tested; the other backends and clients in Compatibility are configured from their documentation and marked untested.

Quick start · Prove it · Client settings · Claude Code · DeepSeek Harness · Recall · MCP server · Configure · Limits · Your data · Troubleshooting · Changelog

What it does. When a conversation is about to outgrow the model's context window, Context Guardian summarises the older turns, keeps the recent ones verbatim and forwards a request that fits. Everything it folds away is archived on disk, sealed in a hash chain you can verify, and indexed so a model can skim it in a few hundred tokens and open only what it needs. It runs on your machine, with no telemetry: nothing leaves it except the requests you were already sending to your own backend, and one cached PyPI version check you can turn off.

Who it is for.

• Local-model coding CLIs behind any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, LiteLLM): the proxy sits in between and compacts before the backend rejects the request.
• DeepSeek Harness users: a native compaction engine, one row in your agent preset, same archive.
• Claude Code users: Claude Code compacts its own window; its hooks archive every session into the same sealed, searchable archive, without changing how Claude Code connects, and the MCP server lets it search what was archived.

One scripted session, sent straight to a backend with an 8,192-token window and then through the proxy (python examples/demo_overflow.py: a stub backend on 127.0.0.1 that rejects anything over its window; tests/test_demo_overflow.py checks this block is what it prints):

stub backend on 127.0.0.1, 8192-token window, one scripted session sent twice

turn tokens direct to backend through context-guardian 1 1075 ok ok 2 2226 ok ok 3 3376 ok ok 4 4526 ok ok 5 5676 ok ok 6 6827 ok ok 7 7977 ok ok, compactions so far: 1 8 9127 400 overflow ok, compactions so far: 2 9 10278 400 overflow ok, compactions so far: 3 10 11451 400 overflow ok, compactions so far: 4 11 12624 400 overflow ok, compactions so far: 5 12 13798 400 overflow ok, compactions so far: 6 direct: rejected from turn 8 on. proxy: 12/12 turns answered, 6 originals archived.

<!-- demo-overflow:end -->

Fails open. If a summary fails, comes back empty or anything in the proxy raises, the request goes upstream exactly as your client sent it. The same holds for every seal, index, receipt and journal write: one that fails logs a warning, and the request goes ahead unchanged.

Prove it

Three commands turn "lossless on disk" and "it helps" from claims into numbers you can check.

context-guardian-recall --verify --all     # every run: OK, or the first break and what kind

context-guardian-recall --receipts --since 7d context-guardian-recall --savings --since 7d # how much smaller the requests were; add --json for scripts

`--verify` walks each run's chain.jsonl: one line per archived file with the SHA-256 of its bytes on disk, chained to the line before it. It reports OK per run, or the first break: content-changed, file-missing (deleted with no prune record), entry-edited, entry-reordered, chain-forked, unsealed-file or anchor-mismatch. Spans removed by GUARDIAN_KEEP_SPANS are reported as pruned, as expected. It exits 0 only when every checked run is OK. --heads prints each run's chain head, and --seal-existing seals an archive written before 0.12.0, with every line marked "backfilled": true because it was sealed late. The MCP tool get_seal_status runs the same check from inside a client.

The seal is tamper-evident, not tamper-proof. Anyone who can write the archive directory can edit a span and rehash every chain line after it. Set GUARDIAN_SEAL_ANCHOR_PATH to a file somewhere they cannot reach, such as synced storage with history or another disk: every new head is copied there, and --verify then catches a chain that was rewritten afterwards. The format is specified in docs/ARCHIVE_FORMAT.md, so you can check it with a verifier of your own.

`--receipts` adds up the counts every recall and every compaction leave behind: archive size, recall calls (CLI and MCP), spans opened, the share of the archive actually read back, tokens kept out of the window, recall tool calls the model made through the proxy, and seal status. Receipts hold numbers only: no message text, no query text, no paths and no run ids, and nothing is sent anywhere. `--share` prints the same as a five-line block you can paste anywhere:

Context Guardian receipts (last 7d)

• 40 compactions, ~512,000 tokens kept out of the window
• 85 spans archived (2.3 MB), sealed, all runs verify
• 14 recall calls opened 6 spans; 3.2% of the archive was read back
• local only: no telemetry, nothing left this machine

(Illustrative numbers. Your own come from --receipts --share.)

`--savings` is the other half: how much smaller the forwarded requests were. It reads the compaction log (GUARDIAN_LOG_PATH) and the receipts, and every figure is counted, none estimated: the request sizes before and after each compaction (the proxy's own count for the request, exact on llama.cpp and vLLM and an estimate elsewhere, see What this does *not* do), the oversized pasted messages cut to head + tail, summaries reused without a summariser call, and recall reads. A dry run never counts, because it forwards the request unchanged. --since AGE takes 30m, 24h, 7d or 2w; a bad AGE exits 2. --json prints one object with the keys window, compactions, tokens_before, tokens_after, tokens_kept_out, pct_smaller, oversized_spills, summaries_reused, recall_calls and chars_returned.

Context Guardian savings (last 7d)

compactions 35 requests 145,332 -> 14,819 tokens (89.8% smaller) kept out 130,513 tokens oversized 1 pasted message(s) cut to head + tail summaries 0 reused (no summariser call) recall 3 call(s), 3,170 chars returned

(Output from a scripted 40-turn stub session against a fake backend, not a real log. Your own come from --savings.)

Point your client at the proxy

The proxy compacts OpenAI-style POST /v1/chat/completions requests. Every client below is configured from its own documented settings; none of these four has been tested against the proxy yet, so please open an issue with what you see.

| Claude Code | environment | Claude Code speaks the Anthropic Messages API (/v1/messages). The proxy compacts it too when GUARDIAN_UPSTREAM_URL serves that API (the summary call goes to the same upstream's /messages with your key and goes into system):