<img align="right" src="claude-praetorian.svg" alt="claude-praetorian-mcp" width="220">

claude-praetorian-mcp

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

<br clear="right">

---

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 TOON (Token-Oriented Object Notation) Format.

install

Requirements:

From shell:

claude mcp add claude-praetorian-mcp -- npx claude-praetorian-mcp

From inside Claude (restart required):

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

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

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

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

There is no npm install required -- no external databases or services, only flat files.

However, if npx resolves the wrong package, you can force resolution with:

npm install -g claude-praetorian-mcp

skill

Optionally, install the skill to teach Claude when to proactively use praetorian:

npx skills add Vvkmnn/claude-praetorian-mcp --skill claude-praetorian --global
# Optional: add --yes to skip interactive prompt and install to all agents

This makes Claude automatically compact after research, subagent tasks, and before context resets. The MCP works without the skill, but the skill improves discoverability.

plugin

For full automation with hooks, install from the claude-emporium marketplace:

/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-praetorian@claude-emporium

The claude-praetorian plugin provides:

Hooks (targeted, fires only at high-value moments):

• Before EnterPlanMode → Restore prior compactions for this project
• Before context compaction → Save decisions/insights before context resets
• After WebFetch/WebSearch → Compact web research findings
• After SubagentStop → Compact subagent task results

Commands: /praetorian-compact, /praetorian-restore, /praetorian-search

Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.

features

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

Runs project by project, saves artifacts to {$project}/.claude/praetorian (with 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
└───────────────────────────────────────────────────────────────────┘

{
  "type": "web_research",
  "title": "ACE Framework Research",
  "source": "https://github.com/humanlayer/ace-fca",
  "key_insights": [
    "Frequent intentional compaction saves 90%+ tokens",
    "TOON format is 30-60% smaller than JSON/YAML",
    "Compaction should happen after every expensive operation"
  ],
  "refs": ["ace-fca.md:42 - compaction strategy", "toon-spec.md:1 - format definition"],
  "recommendations": ["Compact after every WebFetch", "Use type='decisions' for architecture choices"]
}

⚜️ compact | Merged

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

{
  "type": "decisions",
  "title": "Authentication Patterns",
  "decisions": [
    { "chose": "JWT with refresh tokens", "over": ["sessions", "API keys"], "reason": "Stateless, works across microservices" },
    { "chose": "httpOnly cookies", "over": ["localStorage"], "reason": "XSS protection" }
  ],
  "refs": ["src/middleware/auth.ts:45 - token validation", "src/routes/login.ts:23 - refresh flow"],
  "anti_patterns": ["Never store tokens in localStorage", "Never skip CSRF on cookie-based auth"]
}

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"
└────────────────────────────────────────────────────────────────────┘

{
  "compactions": [
    {
      "id": "cpt_1765245903512_xk9mp1",
      "type": "decisions",
      "title": "Authentication Patterns",
      "relevance": 0.85,
      "key_insights": ["JWT with refresh tokens", "httpOnly cookies for XSS protection"],
      "refs": ["src/middleware/auth.ts:45", "src/routes/login.ts:23"]
    },
    {
      "id": "cpt_1765245902396_nxetoc",
      "type": "web_research",
      "title": "OAuth2 Best Practices",
      "relevance": 0.72,
      "key_insights": ["PKCE flow for public clients", "Token rotation every 15min"]
    }
  ],
  "total": 2
}

⚜️ restore | Recent

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

Status indicators:

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

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

When to compact:

• [x] After every WebFetch
• [x] After every Task/subagent completes
• [x] After reading multiple files
• [x] After making decisions
• [x] During long conversations (proactive compaction)
• [x] 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
              ════════════════════════


        compact (save)          restore (load)
        ──────────────          ──────────────

            INPUT                   QUERY
              │                       │
              ▼                       ▼
          ┌─────────┐           ┌─────────┐
          │   Zod   │           │ Inverted│
          │Validate │           │  Index  │
          └────┬────┘           └────┬────┘
               │                     │
               ▼                     ▼
          ┌─────────┐           ┌─────────┐
          │ Jaccard │           │  TOON   │
          │ >70% ?  │           │ Decode  │
          └──┬───┬──┘           └────┬────┘
             │   │                   │
          new│   │match              ▼
             │   │                OUTPUT
             ▼   ▼
          ┌─────────┐
          │  TOON   │
          │ Encode  │
          └────┬────┘
               │
               ▼
          ┌─────────┐
          │  Index  │
          │ Update  │
          └────┬────┘
               │
               ▼
            OUTPUT


        storage: .claude/praetorian/
        ────────────────────────────
        index.json            word index + metadata
        compactions/*.toon    encoded compaction files

Core optimizations:

• TOON format: 30-60% fewer tokens than YAML/JSON
• Zod validation: Production-grade runtime type safety
• [Ja