Content
<p align="center">
<img src="./context-the-ripper.jpeg" alt="context-the-ripper" width="500" />
</p>
<p align="center">
<strong>Strip dead context. Keep signal.</strong>
</p>
<p align="center">
An MCP server that manages your conversation context automatically —<br>
pruning dead branches, logging every cut, keeping the audit trail. You just work.
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat" alt="License"></a>
<a href="https://www.npmjs.com/package/context-the-ripper"><img src="https://img.shields.io/npm/v/context-the-ripper?style=flat&label=npm" alt="npm"></a>
<a href="https://github.com/M4NT/context-the-ripper/actions"><img src="https://img.shields.io/github/actions/workflow/status/M4NT/context-the-ripper/ci.yml?style=flat&label=tests" alt="CI"></a>
</p>
<p align="center">
<strong>English</strong> ·
<a href="README.pt-BR.md">Português</a>
</p>
<p align="center">
<strong>Skill:</strong>
<a href="skills/context-the-ripper/SKILL.md">EN</a> ·
<a href="skills/context-the-ripper/SKILL.pt-BR.md">PT-BR</a> ·
<a href="skills/context-the-ripper/SKILL.es.md">ES</a> ·
<a href="skills/context-the-ripper/SKILL.zh.md">ZH</a> ·
<a href="skills/context-the-ripper/SKILL.ja.md">JA</a>
</p>
<p align="center">
Part of the <strong>ripper ecosystem</strong> → <a href="https://github.com/M4NT/token-the-ripper">token-the-ripper</a>
</p>
---
## The problem
Long sessions fill up with noise: replaced code, resolved questions, failed hypotheses. Every tool either prunes automatically (opaque, can't audit) or leaves it to you (friction, breaks flow).
context-the-ripper does both: **automatic by default, auditable on demand.**
---
## Requirements
- Node.js >= 22.5.0 (uses built-in `node:sqlite`)
---
## Install
<details>
<summary><strong>Claude Desktop</strong></summary>
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"context-the-ripper": {
"command": "npx",
"args": ["-y", "context-the-ripper"]
}
}
}
```
Restart Claude Desktop. The MCP is active.
</details>
<details>
<summary><strong>Claude Code</strong></summary>
Add to your project's `CLAUDE.md`:
```
@CONTEXT.md
```
Then add the MCP to your Claude Code config:
```json
{
"mcpServers": {
"context-the-ripper": {
"command": "npx",
"args": ["-y", "context-the-ripper"]
}
}
}
```
After the first `context_prune` or `context_checkpoint`, `CONTEXT.md` is written to your project root. Every new session reads it automatically — no onboarding command needed.
</details>
<details>
<summary><strong>.gitignore</strong></summary>
If you install as a local dependency (`npm install context-the-ripper`), a `postinstall` script adds `CONTEXT.md` to your `.gitignore` automatically.
For `npx` users, add it manually:
```bash
echo "CONTEXT.md" >> .gitignore
```
</details>
---
## How it works
1. The agent scores each message as you work (explicit markers, DDL patterns, failed hypotheses)
2. Resolved questions and dead branches are marked `candidate` automatically
3. When context exceeds 40% noise, `context_prune` fires silently
4. Every cut is logged to `~/.context-the-ripper/context.db`
5. `CONTEXT.md` is written to the project root after every prune or checkpoint
6. The next session starts from `CONTEXT.md` — no context lost
**You never type a pruning command. You just work.**
---
## Tools
| Tool | What it does |
|---|---|
| `context_session_id` | Generate `<project>-<date>-<fingerprint>` unique per machine |
| `context_add` | Register a message, auto-score it |
| `context_mark` | Override status: `dead` / `keep` / `candidate` / `live` |
| `context_prune` | Remove dead/candidate messages, write `CONTEXT.md` |
| `context_checkpoint` | Compress a milestone into a named summary, write `CONTEXT.md` |
| `context_restore` | Undo a cut by ID |
| `context_status` | Token usage, noise %, checkpoint count |
| `context_get` | Return all live messages for the session |
---
## Scoring rules
**Automatically marked candidate (pruned on next prune):**
- `[resolved]`, `[done]`, `[fixed]` markers
- `[dead]` marker
- "didn't work", "won't work" patterns
**Never pruned:**
- `[!]` irreversible action markers
- `[keep]` markers
- `[checkpoint]` markers
- DDL statements (`CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`)
- TypeScript `interface` and `type` definitions
---
## Markers
Works with [token-the-ripper](https://github.com/M4NT/token-the-ripper) markers:
```
[dead] — mark this message for pruning
[keep] — protect from pruning
[!] — irreversible action — always kept
[checkpoint] — compress into named summary
[resolved] — auto-scored as candidate
[?] — source unverified — answer anyway, flag it
```
---
## Audit log
All cuts stored in `~/.context-the-ripper/context.db` (SQLite, local, no telemetry).
```
cuts { id, message_id, reason, rule, ts }
```
Every removal is reversible via `context_restore(cut_id)`. Messages pruned more than 30 days ago are vacuumed automatically on startup.
---
## Staleness detection
`CONTEXT.md` embeds a `written_at` timestamp. If the file is more than 24 hours old when read, the agent sees a `[!]` warning inline and triggers a refresh.
---
## Philosophy
> *"Information is a difference that makes a difference."* — Gregory Bateson, *Steps to an Ecology of Mind*, 1972
Dead context isn't information. It's entropy. The best tool removes it without asking — and logs every cut so you can undo it.
Invisible by default. Auditable on demand. Every cut earns its place in the log.
---
## Foundations
**Claude Shannon** — *A Mathematical Theory of Communication*, 1948
Every channel has a capacity. Tokens that carry no new information are noise — they consume capacity without increasing the model's ability to respond.
**Herbert Simon** — *"Designing Organizations for an Information-Rich World"*, 1971
*"A wealth of information creates a poverty of attention."* Context pruning is an attention-allocation mechanism: finite attention lands on signal, not dead turns.
**George A. Miller** — *"The Magical Number Seven, Plus or Minus Two"*, 1956
Exceeding working memory limits degrades reasoning. Stuffing a context window past the model's effective span is the LLM equivalent of exceeding Miller's limit.
**Friedrich Nietzsche** — *"On the Uses and Disadvantages of History for Life"*, 1874
A healthy mind requires *active forgetting* — the capacity to dissolve the past so present action remains possible. A context that cannot forget becomes paralyzed by its own record.
**Jorge Luis Borges** — *"Funes the Memorious"*, 1942
Ireneo Funes, after gaining perfect memory, could no longer think in abstractions. Total recall destroys the ability to reason.
**William James** — *The Principles of Psychology*, 1890
*"My experience is what I agree to attend to."* Consciousness is selective. The session's experience is what survives the cut.
**Alan Baddeley & Graham Hitch** — *"Working Memory"*, 1974
Working memory is an active, capacity-limited workspace. The context window is an engineering analogue — the pruning policy is its central executive.
**Viktor Mayer-Schönberger** — *Delete: The Virtue of Forgetting in the Digital Age*, 2009
Forgetting is the natural default; retention requires effort. context-the-ripper applies the same asymmetry: forgetting is the default, retention must be earned.
---
## Development
```bash
npm test # run 41 tests (unit + integration)
npm run dev # start MCP server with --watch
```
Tests use `node:test` — no external test framework needed.
---
## License
MIT. Part of the ripper ecosystem.
---
## Banner art
The banner is an AI-edited version of a Victorian-era engraving depicting suspects being observed near a "MURDER" sign on the streets of Whitechapel, London — associated with the Jack the Ripper investigations of 1888. The figure's head was replaced with a cardboard box representing the LLM context window: anonymous, operating in the fog, stripping what doesn't matter.
© Stefano Bianchetti / Corbis Historical / Getty Images (ID [526614274](https://www.gettyimages.com.br/detail/526614274)). Editorial use only. Original illustration c. 1891. Digitally edited by AI for this project.
