claude-praetorian-mcp

A Model Context Protocol (MCP) server for aggressive context compaction in Claude Code. Save 90%+ tokens by compacting web research, task outputs, and conversations into beautiful, structured snapshots.

Inspired by this talk by Dexter Horthy from HumanLayer, and his team's work on ACE: Advanced Context Engineering for Coding Agents, 12-Factor Agents & the recent release of the TOON (Token-Oriented Object Notation) Format.

install

Requirements:

• Claude Code

npm install -g claude-praetorian-mcp

From shell:

claude mcp add claude-praetorian-mcp -- bunx claude-praetorian-mcp

From inside Claude (restart required):

Add this to our global mcp config: bunx claude-praetorian-mcp

Install this mcp: https://github.com/Vvkmnn/claude-praetorian-mcp

From any manually configurable mcp.json: (Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "praetorian": {
      "command": "bunx",
      "args": ["claude-praetorian-mcp"],
      "env": {}
    }
  }
}

features

MCP server for aggressive context compaction. Generates structured incremental snapshots to yield 90%+ token savings and easily refresh context with "frequent intentional compaction".

Currently runs project by project and saves artifacts to {$project}/.claude/praetorian via the following tools (and a royal guard ⚜️):

praetorian_compact

(Incrementally) compact context using the TOON format to get the most valuable tokens from an activity.

⚜️ praetorian_compact type=<type> title=<title>
  > "ACE Framework research - save 1,450 tokens"
  > "Icon rendering bug investigation - compact the findings"
  > "Database architecture decisions - preserve the rationale"
  > "WebFetch results from authentication docs"
  > "Task output from explore subagent - code structure analysis"

⚜️ compact | Created

┌─ ⚜️  ────────────────────────────────────────────────── Created ─┐
│ Compacted: "ACE Framework Research" • 1,450 tokens saved
│ Type: web_research • ID: cpt_1765245902396_nxetoc
└───────────────────────────────────────────────────────────────────┘

⚜️ compact | Merged

┌─ ⚜️  ───────────────────────────────────────────────────── Merged ─┐
│ Compacted: "Authentication Patterns" • 890 tokens saved
│ Type: decisions • ID: cpt_1765245903512_xk9mp1
│ Merged with: cpt_1765245903512_xk9mp1
└────────────────────────────────────────────────────────────────────┘

praetorian_restore

Search and restore context by injecting TOON tokens back into current context as needed.

⚜️ praetorian_restore query=<query>
  > "What did we learn about authentication?"
  > "Find the Docker container debugging session"
  > "Show recent architecture decisions"
  > "Search for MCP server implementation patterns"
  > "" (empty = recent compactions)

⚜️ restore | Search

┌─ ⚜️  ───────────────────────────────────────────────────── Search ─┐
│ Found 2 compactions
│ Query: "authentication"
└────────────────────────────────────────────────────────────────────┘

⚜️ restore | Recent

┌─ ⚜️  ───────────────────────────────────────────────────── Recent ─┐
│ Found 3 compactions
└────────────────────────────────────────────────────────────────────┘

Status indicators:

• Created - New compaction saved
• Merged - Updated existing compaction (>70% title similarity)
• Search - Search results returned (keyword matching)
• Recent - Recent compactions listed (by updated time)

usage

Praetorian is designed for heavy, frequent use. The more you compact, the more you save.

When to compact:

• ✅ After every WebFetch
• ✅ After every Task/subagent completes
• ✅ After reading multiple files
• ✅ After making decisions
• ✅ During long conversations (proactive compaction)
• ✅ Before context gets >60% full

Real-world example session:

| Compaction | Before | After | Saved | | --------------------- | ---------- | --------- | ---------------- | | Web research (3 URLs) | 4,500 | 300 | 4,200 | | Subagent outputs (2) | 3,500 | 300 | 3,200 | | Architecture debates | 5,000 | 300 | 4,700 | | Hook research | 1,500 | 150 | 1,350 | | Total | 14,500 | 1,050 | 13,450 (93%) |

Next session: restore() loads ~1,000 tokens. Instant resume, no re-research.

methodology

How claude-praetorian-mcp works:

                        claude-praetorian-mcp
              ======================================


  praetorian_compact (write)
  --------------------------

  INPUT ──> VALIDATE ──> DETECT ──> MERGE ──> ENCODE ──> INDEX ──> OUTPUT
              │            │          │         │          │
              │            │          │         │          └─ words -> IDs
              │            │          │         └─ .toon (30-60% smaller)
              │            │          └─ dedupe arrays, combine objects
              │            └─ Jaccard similarity > 70% = auto-merge
              └─ Zod schemas (CompactInput, Compaction)


  praetorian_restore (read)
  -------------------------

                      ┌─────────┐
  QUERY ──> SEARCH ───┤         ├──> DECODE ──> OUTPUT
                      │  INDEX  │
  (none) ──> RECENT ──┤         │
                      └─────────┘


  Storage: .claude/praetorian/
  ----------------------------

  index.json          Inverted word index + compaction metadata
  compactions/*.toon  TOON-encoded compaction files

Core optimizations:

• TOON format: 30-60% fewer tokens than YAML/JSON
• Zod validation: Production-grade runtime type safety
• Jaccard similarity: Smart deduplication via title matching (>70% threshold)
• Inverted index: Fast keyword search without vector embeddings
• Smart merging: Combine similar compactions without duplication

File access:

• Stores in: <project>/.claude/praetorian/
• TOON format: .toon files (40% fewer bytes than YAML/XML)
• Zero database dependencies (no db calls or filesystem)
• Never leaves your machine

development

git clone https://github.com/Vvkmnn/claude-praetorian-mcp && cd claude-praetorian-mcp
npm install && npm run build

Package requirements:

• Node.js: >=20.0.0 (ES modules)
• npm: >=10.0.0 (package-lock v3)
• Runtime: @modelcontextprotocol/sdk, @toon-format/toon, zod
• Zero external databases - works with bunx

Development workflow:

npm run build          # TypeScript compilation
npm run watch          # Watch mode with tsc --watch
node dist/index.js     # Run MCP server directly (stdio)

Contributing:

• Fork the repository and create feature branches
• Test with multiple compaction types before submitting PRs
• Follow TypeScript strict mode and MCP protocol

license

MIT

Tiberius Claudius Caesar Augustus Germanicus - Declared emperor by his Praetorian Guard