context-the-ripper

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

{
  "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:

{
  "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:

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

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). Editorial use only. Original illustration c. 1891. Digitally edited by AI for this project.