dsh-context-guardian

dsh plugin --profile web add dsh-context-guardian

<h1 align="center">Context Guardian</h1>

<p align="center"><b>Your local-model session hits the context limit and dies. This stops that.</b></p>

<p align="center">

<a href="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/test.yml"><img alt="tests (pytest) on Ubuntu, Windows, macOS" src="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/test.yml/badge.svg"></a>

<a href="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/node.yml"><img alt="node smoke tests on Ubuntu, Windows, macOS" src="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/node.yml/badge.svg"></a>

<a href="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/privacy.yml"><img alt="privacy scan of every tracked file" src="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/privacy.yml/badge.svg"></a>

<a href="https://pypi.org/project/context-guardian/"><img alt="PyPI" src="https://img.shields.io/pypi/v/context-guardian.svg"></a>

<img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-yellow.svg">

<img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">

<img alt="OpenAI-compatible proxy" src="https://img.shields.io/badge/OpenAI--compatible-proxy-2ea44f.svg">

<img alt="Fails open" src="https://img.shields.io/badge/fails-open-6f42c1.svg">

<a href="https://hub.xerj.org/contributors/LuminariSoftwares"><img alt="XERJ Corpus Hub contributor" src="https://hub.xerj.org/contributors/LuminariSoftwares/badge.svg"></a>

<a href="https://glama.ai/mcp/servers/LuminariSoftwares/context-guardian"><img alt="context-guardian MCP server – quality and maintenance score on Glama" src="https://glama.ai/mcp/servers/LuminariSoftwares/context-guardian/badges/score.svg"></a>

</p>

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

<p align="center">

<a href="#quick-start">Quick start</a> &middot;

<a href="#prove-it">Prove it</a> &middot;

<a href="#point-your-client-at-the-proxy">Client settings</a> &middot;

<a href="#claude-code">Claude Code</a> &middot;

<a href="#deepseek-harness">DeepSeek Harness</a> &middot;

<a href="#recall-skim-search-open">Recall</a> &middot;

<a href="#mcp-server">MCP server</a> &middot;

<a href="#configure">Configure</a> &middot;

<a href="#what-this-does-not-do">Limits</a> &middot;

<a href="#what-is-stored-where-and-how-to-delete-it">Your data</a> &middot;

<a href="#troubleshooting">Troubleshooting</a> &middot;

<a href="CHANGELOG.md">Changelog</a>

</p>

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):

<!-- demo-overflow:start -->

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.

Quick start

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](llms.txt) is the whole install, configure, recall and limits story in one short file an agent can read.

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

Another backend or window: see [examples/](examples/) or [Configure](#configure). Your client's settings: [Point your client at the proxy](#point-your-client-at-the-proxy). After a compaction, context-guardian-recall "<term>" searches the a

…(truncated)