RLM-MCP: Recursive Language Model Server for Claude Code

Status: ✅ v0.2.2 - Production-Ready for Team Environments

A Model Context Protocol (MCP) server implementing the Recursive Language Model pattern from Zhang et al. (2025), enabling LLMs to process arbitrarily long contexts by treating prompts as external environment objects.

What's New in v0.2.x:

• v0.2.2: Exact BM25 doc_ids filtering • Highlight bounds clamping • Server config defaults • Budget exemption for session.close
• v0.2.1: Atomic budget enforcement • chunk_index persistence • Truncation warnings • Error message improvements
• v0.2.0: Persistent indexes • Concurrent session safety • Structured logging • Batch document loading (2-3x faster)

Key Insight

Long prompts should not be fed into the neural network directly but should instead be treated as part of the environment that the LLM can symbolically interact with.

Features

Core Capabilities

• Session-based document management — Load files, directories, or inline content with batch processing
• On-demand chunking — Fixed, line-based, or delimiter-based strategies with intelligent caching
• BM25 search — Lazy-built, persistently cached, survives server restarts
• Artifact storage — Store derived results with complete span provenance

Production Features (v0.2.0)

• Persistent indexes — BM25 indexes saved to disk with atomic writes and corruption recovery
• Concurrent session safety — Per-session locks prevent race conditions in multi-user environments
• Structured logging — JSON output with correlation IDs for production observability
• Batch document loading — Concurrent file loading with memory-bounded semaphores (2-3x faster)

Status & Validation

v0.2.2 production-ready validation:

• ✅ 103/103 tests passing (100% functionality + production features)
• ✅ All 13 core tools implemented with canonical naming
• ✅ MCP protocol integration confirmed with real clients
• ✅ Large corpus tested — 1M+ chars loaded and indexed
• ✅ Performance validated — Sub-second searches, <100ms index loads from disk
• ✅ Concurrency tested — 50 concurrent operations, no race conditions
• ✅ Memory safety — Bounded semaphores prevent OOM on large batches
• ✅ Production logging — JSON structured logs with correlation tracking

Test Coverage

• Error handling: 13 tests
• Concurrency safety: 9 tests
• Index persistence: 10 tests
• Integration workflows: 14 tests
• Large corpus performance: 5 tests
• Structured logging: 13 tests
• Batch loading: 7 tests
• Provenance tracking: 8 tests
• Storage layer: 11 tests
• v0.2.2 bug fixes: 13 tests

See MIGRATION_v0.1_to_v0.2.md for upgrade guide.

Installation

pip install rlm-mcp

Or with development dependencies:

pip install rlm-mcp[dev]

Quick Start

from rlm_mcp import run_server

# Start the MCP server
run_server()

Tools

All tools use canonical naming: rlm.<category>.<action>

Category	Tools
rlm.session	create, info, close
rlm.docs	load, list, peek
rlm.chunk	create
rlm.span	get
rlm.search	query
rlm.artifact	store, list, get

Workflow Pattern

1. Initialize: rlm.session.create with config
2. Load: rlm.docs.load documents
3. Probe: rlm.docs.peek at structure
4. Search: rlm.search.query to find relevant sections
5. Chunk: rlm.chunk.create with appropriate strategy
6. Process: rlm.span.get + client subcalls
7. Store: rlm.artifact.store results with provenance
8. Close: rlm.session.close

Configuration

Configuration file: ~/.rlm-mcp/config.yaml

# Data storage
data_dir: ~/.rlm-mcp

# Session limits (per-session overridable)
default_max_tool_calls: 500
default_max_chars_per_response: 50000
default_max_chars_per_peek: 10000

# Batch loading (v0.2.0)
max_concurrent_loads: 20   # Max concurrent file loads (memory safety)
max_file_size_mb: 100      # Reject files larger than this

# Logging (v0.2.0)
log_level: "INFO"              # DEBUG, INFO, WARNING, ERROR
structured_logging: true       # JSON format (true) vs human-readable (false)
log_file: null                 # Optional: "/var/log/rlm-mcp.log"

# Tool naming: strict by default (fails if SDK doesn't support canonical names)
# Only set to true for experimentation with older MCP SDKs
allow_noncanonical_tool_names: false

Tool Naming (Strict vs Compat Mode)

By default, RLM-MCP requires an MCP SDK that supports explicit tool naming (e.g., FastMCP). This ensures tools are discoverable as rlm.session.create, not rlm_session_create.

• Strict mode (default): Server fails to start if SDK doesn't support tool(name=...)
• Compat mode: Falls back to function names with a warning. Use only for experimentation.

# ~/.rlm-mcp/config.yaml
allow_noncanonical_tool_names: true  # Enable compat mode (not recommended)

Logging (v0.2.0)

RLM-MCP produces structured JSON logs for production observability. Each operation gets a unique correlation ID for tracing related events.

JSON Log Format

{
  "timestamp": "2026-01-15T10:30:45.123456Z",
  "level": "INFO",
  "logger": "rlm_mcp.server",
  "message": "Completed rlm.session.create",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "session-123",
  "operation": "rlm.session.create",
  "duration_ms": 42,
  "success": true
}

Filtering Logs

# Filter by session
cat /var/log/rlm-mcp.log | jq 'select(.session_id == "session-123")'

# Filter by operation
cat /var/log/rlm-mcp.log | jq 'select(.operation == "rlm.search.query")'

# Track operation with correlation ID
cat /var/log/rlm-mcp.log | jq 'select(.correlation_id == "a1b2c3d4...")'

# Only errors
cat /var/log/rlm-mcp.log | jq 'select(.level == "ERROR")'

See docs/LOGGING.md for detailed logging guide.

Session Config

{
    "max_tool_calls": 500,           # Budget enforcement
    "max_chars_per_response": 50000, # DOS protection
    "max_chars_per_peek": 10000,     # DOS protection
    "chunk_cache_enabled": True,
    "model_hints": {                 # Advisory for client
        "root_model": "claude-opus-4-5-20251101",
        "subcall_model": "claude-sonnet-4-5-20250929",
        "bulk_model": "claude-haiku-4-5-20251001"
    }
}

Architecture

┌─────────────────────────────────────────┐
│  Claude Skills (policy layer)           │
├─────────────────────────────────────────┤
│  MCP Server (RLM Runtime)               │
│  • Session management + concurrency     │
│  • Document/span operations             │
│  • BM25 search (lazy, persisted)        │
│  • Batch loading with semaphores        │
│  • Response size caps                   │
├─────────────────────────────────────────┤
│  Local Persistence (v0.2.0)             │
│  • SQLite: sessions, docs, spans        │
│  • Blob store: content-addressed        │
│  • Index cache: persistent BM25         │
│  • Structured logs: JSON + correlation  │
└─────────────────────────────────────────┘

Design Principles

1. Local-first — All reads/writes hit local storage
2. Client-managed subcalls — MCP is the "world", client makes LLM calls
3. Immutable documents — Content-addressed, never modified
4. On-demand chunking — Chunk at query time, cache results
5. DOS protection — Hard caps on response sizes

Development

# Clone and install with uv (recommended)
git clone https://github.com/yourorg/rlm-mcp.git
cd rlm-mcp
uv sync --extra dev

# Run tests
uv run pytest

# Or with pip (editable install required for tests)
pip install -e ".[dev]"
pytest

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

Smoke Test with MCP Inspector

To validate tool discovery and schemas from a real client:

# Start server
uv run rlm-mcp

# In another terminal, use MCP Inspector
npx @anthropic/mcp-inspector

Verify:

• Tool names appear as rlm.session.create, not rlm_session_create
• Schemas match expected input/output structures
• truncated and index_built fields appear in responses

License

MIT

References

• Zhang, A. L., Kraska, T., & Khattab, O. (2025). Recursive Language Models. arXiv:2512.24601