RLM Mem Server

An MCP (Model Context Protocol) server implementing the TRUE Recursive Language Model (RLM) technique for ultimate context management with Claude Code.

⚖️ Licensing & Pricing

Free Use (MIT License)

• ✅ Personal projects
• ✅ Academic research
• ✅ Non-commercial open source
• ✅ Non-profit organizations
• ✅ Annual revenue < $50K

Commercial Use (Revenue Sharing Required)

• 💰 10% Revenue Share for services/products using this technology
• 🏢 Commercial licenses required for companies/enterprises
• 📧 Contact: [email protected]
• 🌐 Website: recordandlearn.info
• 📄 Commercial License Details

Important: Commercial use without proper licensing voids all warranties and may result in legal action.

v2.9 Status: 🚀 Optimization Initiative Underway

• ✅ Code organization complete (5 new modules, 1,524 LOC)
• 📊 Performance roadmap planned (60-100% cumulative gain)
• 🎯 3 optimization phases documented
• 📋 16 implementation tasks ready

See .claude/claude.md for detailed optimization roadmap.

Based on:

• arXiv:2512.24601 - Recursive Language Models (Zhang, Kraska, Khattab - MIT, 2025)
• Anthropic MCP Documentation
• Anthropic Prompt Caching

The Problem

Claude Code has a context window of ~200k tokens. When analyzing large codebases (500k+ tokens), Claude either:

• Fails to process everything
• Experiences "context rot" (degraded performance)
• Runs out of space for reasoning

The TRUE RLM Solution

Key Insight: Content is stored as a VARIABLE in a Python REPL, NOT in LLM context.

Traditional Summarization (NOT what we do):
    Large content → LLM summarizes → Information LOST

TRUE RLM Technique:
    Large content → Stored as `prompt` variable
    LLM writes Python CODE to examine portions
    Sub-LLM responses stored as VARIABLES (NOT summarized)
    Full data PRESERVED - accessible at any time

The LLM acts as a programmer, writing code to search and analyze the content rather than trying to hold it all in context.

Features

• TRUE RLM Processing: Content stored as variables, LLM writes code to examine it
• Prompt Caching: Leverages caching for cost reduction on repeated content
• Intelligent Chunking: Respects file/function/section boundaries when splitting
• Memory Store: Persist important findings across conversations (SQLite-backed)
• Robust Architecture: Circuit breakers, rate limiters, exponential backoff
• Async Pipeline: Fully async with connection pooling and concurrent operations
• Claude Haiku 4.5: Default model with 90% cost savings via prompt caching

Installation

Prerequisites

• Python 3.10+
• Claude Code CLI
• OpenRouter API key (or Anthropic API key for direct access)

Setup

# Clone the repository
git clone https://github.com/mosif16/RLM-Mem_MCP.git
cd RLM-Mem_MCP

# Install Python dependencies
cd python
pip install -e .

# Set your API key (OpenRouter recommended for flexibility)
export OPENROUTER_API_KEY=sk-or-...

# Or use Anthropic directly
# export ANTHROPIC_API_KEY=sk-ant-...

Configure Claude Code

Add the MCP server to Claude Code:

# Using the CLI
claude mcp add --transport stdio rlm -- python -m rlm_mem_mcp.server

# Or add to ~/.claude/mcp_servers.json manually

Manual configuration (~/.claude/mcp_servers.json):

{
  "mcpServers": {
    "rlm": {
      "command": "python",
      "args": ["-m", "rlm_mem_mcp.server"],
      "env": {
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}"
      }
    }
  }
}

Documentation

Complete documentation is available in the docs/ directory:

• Usage Guide - Practical examples and workflows (start here!)
• API Reference - Complete tool specifications
• Configuration Guide - Environment variables and setup
• Architecture - Technical deep-dive

Quick Usage

Tools Available

rlm_analyze

Analyze files or directories recursively.

Query: "Find all security vulnerabilities"
Paths: ["./src", "./api"]

rlm_query_text

Process large text blocks directly.

Query: "Extract all error messages with timestamps"
Text: <massive log file content>

rlm_status

Check server health and configuration.

rlm_memory_store / rlm_memory_recall

Persist and retrieve important findings.

Example Workflows

Security Audit:

User: "Check this repo for security vulnerabilities"

Claude uses rlm_analyze({
  "query": "security vulnerabilities: SQL injection, XSS, CSRF,
            hardcoded secrets, insecure deserialization, path traversal",
  "paths": ["./src", "./api"]
})

Architecture Review:

User: "Explain the architecture of this project"

Claude uses rlm_analyze({
  "query": "describe architecture: main components, data flow,
            dependencies, entry points, design patterns used",
  "paths": ["."]
})

Log Analysis:

User: "Here's a 50MB log file. Find all errors."

Claude uses rlm_query_text({
  "query": "extract all ERROR and EXCEPTION entries with timestamps",
  "text": "<log content>"
})

Configuration

Environment Variables

Core Configuration

Variable	Default	Description
OPENROUTER_API_KEY	(required)	Your OpenRouter API key
RLM_MODEL	x-ai/grok-code-fast-1	Model for RLM processing
RLM_AGGREGATOR_MODEL	x-ai/grok-code-fast-1	Model for final aggregation
RLM_USE_CACHE	true	Enable prompt caching
RLM_CACHE_TTL	5m	Cache TTL (5m or 1h)
RLM_MAX_RESULT_TOKENS	4000	Max tokens in result
RLM_MAX_CHUNK_TOKENS	8000	Max tokens per chunk
RLM_OVERLAP_TOKENS	200	Overlap tokens between chunks

Commercial Licensing (Optional)

Variable	Default	Description
RLM_COMMERCIAL_LICENSE_KEY	(empty)	Commercial license key for revenue sharing
RLM_ORGANIZATION_NAME	(empty)	Organization name for commercial licensing
RLM_ENABLE_TELEMETRY	false	Enable usage telemetry for license compliance
RLM_LICENSE_SERVER_URL	https://recordandlearn.info/license	License validation server URL

File Filtering

Included extensions:

• Code: .py, .js, .ts, .tsx, .go, .rs, .java, .c, .cpp, etc.
• Config: .json, .yaml, .toml, .ini
• Docs: .md, .txt, .rst

Skipped directories:

• .git, node_modules, __pycache__, venv, dist, build, etc.

How It Works

TRUE RLM Architecture

+------------------+
|   Claude Code    |
|                  |
| - Sees RLM tools |
| - Decides to use |
| - Calls tool     |
+--------+---------+
         |
         | MCP Protocol (JSON-RPC over stdio)
         v
+------------------+     +------------------+
|  RLM MCP Server  |     |   REPL Environ   |
|                  |     |                  |
| - Collects files |---->| prompt = content |
| - Stores as var  |     | results = []     |
| - LLM writes code|     | llm_query(...)   |
| - Executes code  |     |                  |
+--------+---------+     +------------------+
         |
         | API calls (with caching, rate limiting, circuit breaker)
         v
+------------------+
|   OpenRouter /   |
|   Anthropic API  |
+------------------+

The TRUE RLM Technique (arXiv:2512.24601)

Unlike simple summarization, TRUE RLM:

1. Content as Variable: Files stored in prompt variable, NOT in LLM context
2. LLM Writes Code: The LLM generates Python to examine prompt
3. Sub-LLM Queries: llm_query() calls analyze specific portions
4. Results as Variables: Sub-LLM responses stored in full, NOT summarized
5. Full Preservation: Original data always accessible for re-examination

Processing Steps

1. File Collection: Async walk directories, filter by extension, respect limits
2. Variable Storage: Content stored in REPL environment as prompt variable
3. Code Generation: LLM writes Python code to search/analyze content
4. Sandboxed Execution: Code runs in restricted environment with llm_query()
5. Result Aggregation: Findings combined into coherent response
6. Truncation: Ensure result fits in context (max 4000 tokens)

Prompt Caching Strategy

The server uses Anthropic's prompt caching to optimize costs:

• System prompts are cached (90% cost reduction on hits)
• 5-minute TTL by default, refreshes on each use
• 1-hour TTL available for less frequent access
• Cache statistics tracked and reported via rlm_status

# Cache control is applied automatically to system prompts
system = [
    {
        "type": "text",
        "text": "You are a precise information extractor...",
        "cache_control": {"type": "ephemeral", "ttl": "5m"}
    }
]

Cost Comparison

Method	500k token input	Context Used	Cost
Direct (if possible)	Fails or degrades	200k+ (full)	N/A
Premium 1M context	Works	500k	~$15
RLM via MCP	Works	~4k summary	~$0.50-3

RLM is often cheaper and leaves context for reasoning. Using OpenRouter with Gemini Flash makes it even more cost-effective.

Robust Architecture

The server includes production-ready features:

• Circuit Breaker: Stops requests after consecutive failures, auto-recovers
• Rate Limiter: Respects API rate limits (requests/min, tokens/min)
• Exponential Backoff: Retries with increasing delays on 429/503 errors
• Connection Pooling: Reuses HTTP connections via httpx.AsyncClient
• LRU Response Cache: Caches LLM responses to avoid redundant calls
• Async Everything: Non-blocking I/O for file collection and API calls
• Graceful Shutdown: Proper resource cleanup on server stop

Adding to CLAUDE.md

Add guidance to your project's CLAUDE.md:

## Large Codebase Protocol

When to use `rlm_analyze`:
- Analyzing 50+ files
- Searching entire codebase
- Tasks with "all", "every", or "entire" scope
- Security audits
- Architecture reviews

When NOT to use:
- Working with 1-5 specific files
- Making targeted edits
- Quick lookups in known locations

## Query Tips

Be specific in RLM queries:

BAD:  "find problems"
GOOD: "find SQL injection, XSS, hardcoded secrets"

BAD:  "summarize"
GOOD: "summarize architecture, main components, data flow"

Development

Project Structure

RLM-Mem_MCP/
├── python/
│   ├── src/
│   │   └── rlm_mem_mcp/
│   │       ├── __init__.py          # Package exports
│   │       ├── server.py            # MCP server entry point
│   │       ├── rlm_processor.py     # Core RLM implementation
│   │       ├── repl_environment.py  # TRUE RLM REPL with llm_query()
│   │       ├── file_collector.py    # Async file collection
│   │       ├── cache_manager.py     # Prompt caching (Anthropic-style)
│   │       ├── memory_store.py      # SQLite-backed persistent memory
│   │       ├── agent_pipeline.py    # Claude Agent SDK integration
│   │       ├── config.py            # Environment configuration
│   │       └── utils.py             # Performance monitoring
│   ├── tests/
│   │   ├── test_integration.py      # End-to-end tests
│   │   ├── test_benchmark.py        # Performance benchmarks
│   │   ├── test_stress.py           # Stress tests
│   │   └── conftest.py              # Test fixtures
│   ├── requirements.txt
│   └── pyproject.toml
├── src/                             # TypeScript implementation (optional)
│   ├── index.ts                     # MCP server (Node.js)
│   ├── core/
│   │   └── rlm-context-manager.ts   # RLM tree-based context
│   ├── utils/
│   │   ├── tokenizer.ts             # Token counting
│   │   └── text-splitter.ts         # Document chunking
│   └── types/
│       └── index.ts                 # TypeScript interfaces
├── .mcp.json                        # Project MCP config
├── CLAUDE.md                        # Claude Code guidance
└── README.md

Running Tests

cd python
pip install -e ".[dev]"
pytest

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

References

Papers

• Recursive Language Models (arXiv:2512.24601) - Zhang, Kraska, Khattab - MIT, 2025

Anthropic Documentation

• Model Context Protocol
• Prompt Caching
• Advanced Tool Use
• Claude Code Best Practices

Related Projects

• Official RLM Library
• MCP SDK

License

Business Source License 1.1 with commercial licensing for monetization - see LICENSE for details.

• Free Use: MIT license for non-commercial personal/academic use
• Commercial Use: Revenue sharing required - see COMMERCIAL_LICENSE.md
• Terms of Service: TERMS_OF_SERVICE.md