# jev-compactor

> Deterministic context compaction and safety gating for AI agents, powered by TypeSafe's Jev. A TypeScript library, CLI and MCP server that keeps an agent's messages verbatim, drops the ones Jev judges irrelevant to the goal, and flags or blocks destructive actions (rm -rf, force-push, secret exfiltration) in the same ~300 ms pass. Works with OpenAI, Anthropic, LangChain and plain {role, content} message arrays. MIT.

The canonical name is the npm package name `jev-compactor` (GitHub: edwardyen724-g/jev-compactor; the repository was called jev-context before 2026-09-18). The CLI binary is `jev-compactor` (`compact`, `inspect`), the MCP server binary is `jev-compactor-mcp` (tools: compact_context, inspect_context, check_action). A TypeSafe API key in TYPESAFE_API_KEY is required. Compaction sends an abridged copy of the conversation to api.typesafe.ai; nothing is sent when a run is skipped, and the regex safety floor runs locally.

Benchmark (2026-09-19, jev-1.13.0, one 64-message 12.7k-token session, 6k budget, controls = the products' own compaction mechanisms ported verbatim): jev-compactor saved 73% (53–76% across runs) in 350 ms for $0.0004 with all 4 early facts kept verbatim; Anthropic's compaction API, Codex CLI, OpenCode, Gemini CLI, Grok Build, LangChain, Hermes and goose saved 61–86% at $0.013–$0.099 and 1–61 s, half of them losing a fact; oldest-first truncation saved 53% with 1 of 4 facts. On a 61k-token session jev-compactor saved 95.4% with 4 of 4 in 593 ms for $0.0014 vs Anthropic's real threshold compaction at 97.6% with 3 of 4 in 14.6 s for $0.145.

## Docs

- [README](https://raw.githubusercontent.com/edwardyen724-g/jev-compactor/main/README.md): what it is, when to use it and when not to, benchmark vs truncation and LLM summarization, FAQ
- [Package README](https://raw.githubusercontent.com/edwardyen724-g/jev-compactor/main/packages/jev-compactor/README.md): install, withCompaction and compact(), CLI reference, MCP server config and tools, every option with its default, the CompactionResult / CompactionReport interfaces, failure policy
- [Architecture](https://raw.githubusercontent.com/edwardyen724-g/jev-compactor/main/docs/ARCHITECTURE.md): the pipeline, the === guarantee, trigger and failure policy, rejected alternatives, testing
- [Jev API notes](https://raw.githubusercontent.com/edwardyen724-g/jev-compactor/main/docs/JEV-API.md): TypeSafe endpoint, the noul / choice / score primitives, limits, pricing ($0.042 per million input tokens), measured latency, answer stability
- [Benchmark](https://raw.githubusercontent.com/edwardyen724-g/jev-compactor/main/docs/BENCHMARK.md): the three arms, metrics, long-noisy and short-fixture results, caveats, reproduce commands

## Optional

- [Tutorial](https://raw.githubusercontent.com/edwardyen724-g/jev-compactor/main/docs/TUTORIAL.md): step by step from install to the safety gate and use from Claude Code, Cursor or any MCP client
- [Product spec](https://raw.githubusercontent.com/edwardyen724-g/jev-compactor/main/docs/PRODUCT.md): the open-core plan; the Phase 2 cloud is not started
- [Public API source](https://github.com/edwardyen724-g/jev-compactor/blob/main/packages/jev-compactor/src/index.ts): exports of the npm package