Massive Context MCP

Handle massive contexts (10M+ tokens) with chunking, sub-queries, and free local inference via Ollama.

Based on the Recursive Language Model pattern. Inspired by richardwhiteii/rlm.

Core Idea

Instead of feeding massive contexts directly into the LLM:

1. Load context as external variable (stays out of prompt)

2. Inspect structure programmatically

3. Chunk strategically (lines, chars, or paragraphs)

4. Sub-query recursively on chunks

5. Aggregate results for final synthesis

Quick Start

Installation

Option 1: MCPB Bundle (Recommended)

Download the latest .mcpb from Releases and install via Claude Desktop or your MCP client.

Option 2: From Source

Or with pip:

Wire to Claude Code

First, find your installation path:

Add to ~/.claude/.mcp.json, replacing the example paths with your own:

Note: Replace /Users/your_username/projects/rlm with the output from pwd above. The RLM_DATA_DIR is where RLM stores contexts and results — you can use any directory you prefer.

Alternative (if not using uv):

Tools

Setup & Status Tools

Analysis Tools

Quick Analysis with rlm_auto_analyze

For most use cases, just use rlm_auto_analyze — it handles everything automatically:

What it does automatically:

1. Detects content type (Python, JSON, Markdown, logs, prose, code)

2. Selects optimal chunking strategy

3. Adapts the query for the content type

4. Runs parallel sub-queries

5. Returns aggregated results

Supported goals:

Programmatic Analysis with rlm_exec

For deterministic pattern matching and data extraction, use rlm_exec to run Python code directly against a loaded context. This is closer to the paper's REPL approach and provides full control over analysis logic.

Tool: rlm_exec

Purpose: Execute arbitrary Python code against a loaded context in a sandboxed subprocess.

Parameters:

• code (required): Python code to execute. Set the result variable to capture output.

• context_name (required): Name of a previously loaded context.

• timeout (optional, default 30): Maximum execution time in seconds.

Features:

• Context available as read-only context variable

• Pre-imported modules: re, json, collections

• Subprocess isolation (won't crash the server)

• Timeout enforcement

• Works on any system with Python (no Docker needed)

Example — Finding patterns in a loaded context:

Example Response:

Example — Extracting structured data:

When to use :

Tip: For large contexts, combine both — use rlm_exec to filter/extract, then rlm_sub_query for semantic analysis of filtered results.

Providers & Auto-Detection

RLM automatically detects and uses the best available provider:

How Auto-Detection Works

When you use provider="auto" (the default), RLM:

1. Checks if Ollama is running at OLLAMA_URL (default: http://localhost:11434)

2. Checks if gemma3:12b is available (or any gemma3 variant)

3. Uses Ollama if available, otherwise falls back to Claude SDK

The status is cached for 60 seconds to avoid repeated network checks.

Check Ollama Status

Use rlm_ollama_status to see what's available:

Response when Ollama is ready:

Response when Ollama is not available:

Transparent Provider Selection

All sub-query responses include which provider was actually used:

Autonomous Usage

Enable Claude to use RLM tools automatically without manual invocation:

1. CLAUDE.md Integration Copy CLAUDE.md.example content to your project's CLAUDE.md (or ~/.claude/CLAUDE.md for global) to teach Claude when to reach for RLM tools automatically.

2. Hook Installation Copy the .claude/hooks/ directory to your project to auto-suggest RLM when reading files >10KB:

The hook provides guidance but doesn't block reads.

3. Skill Reference Copy the .claude/skills/ directory for comprehensive RLM guidance:

With these in place, Claude will autonomously detect when to use RLM instead of reading large files directly into context.

Setting Up Ollama (Free Local Inference)

RLM can automatically install and configure Ollama on macOS with Apple Silicon. There are two installation methods with different trade-offs:

Choosing an Installation Method

Recommendation:

• Use Homebrew method if you have Homebrew and want managed updates

• Use Direct Download for automation, locked-down machines, or when you don't have admin access

Method 1: Homebrew Installation (Recommended if you have Homebrew)

What this does:

• Installs Ollama via Homebrew (brew install ollama)

• Starts Ollama as a managed background service (brew services start ollama)

• Pulls gemma3:12b model (~8GB download)

Requirements:

• macOS with Apple Silicon (M1/M2/M3/M4)

• 16GB+ RAM (gemma3:12b needs ~8GB to run)

• Homebrew installed

Method 2: Direct Download (Fully Headless, No Sudo)

What this does:

• Downloads Ollama from https://ollama.com/download/Ollama-darwin.zip

• Extracts to ~/Applications/Ollama.app (user directory, no admin needed)

• Starts Ollama via ollama serve (background process)

• Pulls gemma3:12b model

Requirements:

• macOS with Apple Silicon (M1/M2/M3/M4)

• 16GB+ RAM

• No special permissions needed!

Note on PATH: After direct installation, the CLI is at:

Add to your shell config if needed:

For Systems with Less RAM

Use a smaller model on either installation method:

Manual Setup

If you prefer manual installation or are on a different platform:

1. Install Ollama from https://ollama.ai or via Homebrew:

   brew install ollama

2. Start the service:

   brew services start ollama # or: ollama serve

3. Pull the model:

   ollama pull gemma3:12b

4. Verify it's working:

   rlm_ollama_status()

Provider Selection

RLM automatically uses Ollama when available. You can also force a specific provider:

Usage Example

Basic Pattern

Processing a 2MB Document

Tested with H.R.1 Bill (2MB):

Result: Comprehensive topic extraction at $0 cost (with Ollama) or ~$0.02 (with Claude).

Analyzing War and Peace (3.3MB)

Literary analysis of Tolstoy's epic novel from Project Gutenberg:

Result: Complete character arc across the novel — Pierre's journey from idealist to prisoner to husband, Natásha's growth, Prince Andrew's philosophical struggles — all for ~$0.03.

Data Storage

Contexts persist across sessions. Chunked contexts are cached for reuse.

Architecture

The key insight: context stays external. Instead of stuffing 2MB into your prompt, load it once, chunk it, and make targeted sub-queries. Claude orchestrates; sub-models do the heavy lifting.

Cost optimization: RLM automatically uses free local inference when Ollama is available, falling back to Claude API only when needed.

Learning Prompts

Use these prompts with Claude Code to explore the codebase and learn RLM patterns. The code is the single source of truth.

Understanding the Tools

Understanding the Architecture

Hands-On Learning

Extending RLM

License

MIT