<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.