Why this repo exists (vs one-shot long-context prompting)

RLMs avoid forcing the entire context through the model window at once. Instead, the model writes code to selectively inspect the context and can recursively call itself on targeted snippets.

This repo exposes that workflow as a reusable MCP tool: solve.

When you should use RLM

Use solve when:

• baseline one-shot truncates or becomes unreliable
• you need multi-step investigation across many files/logs
• you want evidence-backed extraction (paths + excerpts + hashes)

When you should NOT use RLM

Don’t use it for:

• small, trivial queries that fit comfortably in the context window
• tasks where grep/ripgrep is obviously sufficient
• situations where multiple recursive API calls would be cost-prohibitive

• Python 3.12+
• uv (recommended) or pip
• Docker (recommended for safe sandboxing)

We recommend using uv for automatic dependency and virtualenv management:

# Sync dependencies (RLM is automatically installed from upstream)
uv sync

# Build Docker Sandbox (recommended for safety)
docker build -t rlm-sandbox -f Dockerfile.rlm-sandbox .

Note: The project uses hatchling as the build backend for proper package discovery.

RLM method (in 30 seconds)

RLMs treat your repo/logs as an external environment. The model writes code to:

1. ingest context (files/globs/text)
2. probe specific subsets (regex/AST/search)
3. recursively call itself on small chunks
4. synthesize a final structured answer

See: https://arxiv.org/abs/2512.24601

Example mcp.json Configuration

If you prefer editing your mcp.json directly (usually found at ~/Library/Application Support/Cursor/User/globalStorage/moe.eucerin.cursor/mcp.json on macOS), here is the canonical configuration:

{
  "mcpServers": {
    "rlm": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/context-unlimited",
        "run",
        "context_unlimited/server.py"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "RLM_DEFAULT_RECURSION_MODEL": "openai/gpt-4o-mini"
      }
    }
  }
}

Handling API Keys in Cursor

Cursor does not automatically inherit environment variables from your shell. Use one of these methods:

• Method A (.env file - Recommended): Create a .env file in the project root with your keys:

  OPENAI_API_KEY=sk-...
  OPENROUTER_API_KEY=sk-...

  Note: OpenRouter uses Authorization: Bearer <OPENROUTER_API_KEY> for its API (see OpenRouter Authentication).
• Method B (Direct JSON): Add keys directly to the env object in your mcp.json (found via Cursor settings).
• Method C (Terminal Launch): Launch Cursor from your terminal using cursor . after exporting keys in your shell.

[!IMPORTANT] Common Failure (Environment Variables): Some MCP clients (including Claude Code and Cursor) may occasionally fail to pass variables from the env block to the subprocess. If you see "API Key not found" errors, we recommend using Method A or Method C.

Add to ~/.codex/config.toml:

[context_unlimited.rlm]
command = "python"
args = ["-u", "/path/to/context-unlimited/context_unlimited/server.py"]
cwd = "/path/to/context-unlimited"
[context_unlimited.rlm.env]
OPENAI_API_KEY = "..."

Choosing & Overriding Models

You can configure global defaults via environment variables or override them per-request.

• RLM_DEFAULT_MODEL: The primary model to use if none is specified.
• RLM_DEFAULT_RECURSION_MODEL: The model used for recursive sub-calls (highly recommended to use a cheaper model here).

Use the model_name argument in your prompt. RLM also supports an other_model_name for the recursive "sub-probes".

Example: Use Claude on OpenRouter

"Analyze the auth flow using RLM with model_name='anthropic/claude-3.5-sonnet'"

Example: Use a cheaper model for recursion

"Find the bug using RLM with model_name='gpt-4o' and other_model_name='gpt-4o-mini'"

{
  "query": "Analyze the project structure",
  "globs": ["**/*.py"],
  "provider_preset": "openai",
  "model_name": "gpt-4o"
}

{
  "query": "Deep investigation of the codebase",
  "provider_preset": "openrouter",
  "model_name": "anthropic/claude-sonnet-4.5"
}

{
  "query": "Analyze this file",
  "provider_preset": "ollama_local",
  "model_name": "qwen2.5-coder-32b",
  "environment": "local"
}

[!NOTE] Disclosure: These specific model combinations are provided as general recommendations based on current pricing and performance (January 2026). They have not been formally tested in every environment; your results may vary.

[!WARNING] 404 Model Not Found: If you receive a 404 error, ensure the model ID is correct for your provider. For OpenRouter, some models have :free suffixes or might be temporarily unavailable. Check the OpenRouter Models List for the latest IDs.

Example: Balanced Power Setup (mcp.json)

{
  "env": {
    "RLM_DEFAULT_MODEL": "openai/gpt-5.2-codex",
    "RLM_DEFAULT_RECURSION_MODEL": "deepseek/deepseek-r1-0528:free"
  }
}

Ollama's default context (4096 tokens) can make comparisons unfair. Use a custom model file:

1. ollama create qwen2.5-coder-32k -f Modelfile.qwen3-32k
2. Run benchmark with --model qwen2.5-coder-32k.

flowchart LR
  A[Agent framework<br/>Cursor / Claude Code / Codex] -->|MCP stdio| B[context-unlimited server]
  B --> C[Ingest: files/text/globs]
  C --> D[RLM loop<br/>probe → recurse → synthesize]
  D --> E[Provider<br/>OpenAI / OpenRouter / Ollama / vLLM]
  E --> D --> B --> A

• context_unlimited/server.py: FastMCP server entrypoint.
• context_unlimited/ingest.py: Secure file ingestion with repo boundaries.
• context_unlimited/validate.py: JSON schema validation.
• schemas/: JSON schemas for request/result.

Disclaimer & User Responsibility

[!IMPORTANT] By using this software, you acknowledge and agree to the following:

1. Financial Responsibility: RLM works by making multiple recursive calls to LLM APIs. You are solely responsible for all costs incurred on your API accounts. We highly recommend setting usage limits on your provider dashboards.
2. Verification Mandate: AI-generated outputs (especially code and technical analysis) can contain errors, omissions, or "hallucinations." You must manually verify all outputs before relying on them or applying them to production systems.
3. Execution Risk: RLM executes LLM-generated code to probe your context. While we provide a Docker sandbox, no sandbox is 100% secure. You assume all risk associated with the execution of AI-generated code on your infrastructure.
4. Data Privacy: Do not input sensitive personal data, trade secrets, or highly confidential information unless you have verified the privacy policy of your chosen LLM provider.
5. No Liability: This software is provided "as is," without warranty of any kind. The authors and contributors are not liable for any damages, financial losses, or security breaches resulting from the use of this tool.

Security Policy & Sandboxing

• Execution Environment: Default execution uses a Docker sandbox. This is the primary defense against malicious or buggy AI-generated code. Always prefer Docker for untrusted queries.
• Local Execution: Running with environment: local executes code directly on your host machine. Use this only for trusted local development on non-sensitive codebases.
• API Keys: Keys should be scoped to least privilege. Never pass keys directly in tool arguments; use environment variables or a .env file.

🔎 Keywords

RLM, Recursive Language Models, long context, MCP, Model Context Protocol, REPL, agentic coding, structured outputs, code mode, OpenRouter, Ollama, vLLM.