rlm-claude-code

RLM-Claude-Code

Transform Claude Code into a Recursive Language Model (RLM) agent with intelligent orchestration, unbounded context handling, persistent memory, and REPL-based decomposition.

rlm-core integration: This project bundles rlm-core as a required dependency, providing shared Rust-based implementations with recurse. rlm-core provides 10-50x faster pattern classification via PyO3 bindings. Pre-built wheels are available for common platforms.

What is RLM?

RLM (Recursive Language Model) enables Claude to handle arbitrarily large contexts by decomposing complex tasks into smaller sub-queries. Instead of processing 500K tokens at once, RLM lets Claude:

• Peek at context structure before deep analysis
• Search using patterns to narrow focus
• Partition large contexts and process in parallel via map-reduce
• Recurse with sub-queries for verification
• Remember facts and experiences across sessions

This results in better accuracy on complex tasks while optimizing cost through intelligent model selection.

---

Quick Start

Prerequisites

• Python 3.12+: brew install python@3.12 or python.org
• uv (Python package manager): curl -LsSf https://astral.sh/uv/install.sh | sh
• Rust 1.75+ (for dev builds): rustup update stable — not needed if installing from pre-built wheels

Installation (from pre-built wheel)

Download the wheel for your platform from GitHub Releases, then:

pip install rlm_claude_code-*.whl

Installation (from source, requires Rust)

# Clone with submodules (rlm-core is bundled)
git clone --recurse-submodules https://github.com/rand/rlm-claude-code.git
cd rlm-claude-code

# Build and install (compiles rlm-core Rust library)
maturin develop --release

# Install Python dependencies
uv sync --all-extras

# Verify
python -c "import rlm_core; print(rlm_core.version())"
uv run pytest tests/ -v

As a Claude Code Plugin

Step 1: Install the Plugin

# Add the marketplace (one-time setup)
claude plugin marketplace add github:rand/rlm-claude-code

# Install the plugin
claude plugin install rlm-claude-code@rlm-claude-code

Step 2: Set Up the Plugin Environment

The plugin includes rlm-core (bundled via maturin). After installation:

# Navigate to the plugin directory (adjust version number as needed)
PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
cd "$PLUGIN_DIR"

# Create venv and install (includes rlm-core)
uv venv && uv sync

# Verify rlm-core is available
"$PLUGIN_DIR/.venv/bin/python" -c "import rlm_core; print('rlm_core OK:', rlm_core.version())"

Step 3: Verify Installation

Restart Claude Code. You should see "RLM initialized" on startup.

Test the hooks manually:

PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
"$PLUGIN_DIR/.venv/bin/python" "$PLUGIN_DIR/scripts/init_rlm.py"
# Should print: RLM initialized

Updating the Plugin

When updating, you'll need to re-create the venv:

claude plugin update rlm-claude-code@rlm-claude-code

# Re-setup the new version
PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
cd "$PLUGIN_DIR" && uv venv && uv sync

# rlm-core is bundled — no extra linking needed

---

Architecture

User Query
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│              INTELLIGENT ORCHESTRATOR                   │
│  ┌───────────────────┐   ┌───────────────────────────┐  │
│  │ Complexity        │   │ Orchestration Decision    │  │
│  │ Classifier        │   │ • Activate RLM?           │  │
│  │ • Token count     │──►│ • Which model tier?       │  │
│  │ • Cross-file refs │   │ • Depth budget (0-3)?     │  │
│  │ • Query patterns  │   │ • Tool access level?      │  │
│  └───────────────────┘   └───────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
    │
    ▼ (if RLM activated)
┌─────────────────────────────────────────────────────────┐
│                 RLM EXECUTION ENGINE                    │
│                                                         │
│  ┌──────────────────┐    ┌──────────────────────────┐   │
│  │  Context Manager │    │     REPL Sandbox         │   │
│  │  • Externalize   │───►│  • peek(), search()      │   │
│  │    conversation  │    │  • llm(), llm_batch()    │   │
│  │  • files, tools  │    │  • map_reduce()          │   │
│  └──────────────────┘    │  • find_relevant()       │   │
│                          │  • memory_*() functions  │   │
│                          └──────────────────────────┘   │
│                                     │                   │
│                                     ▼                   │
│  ┌──────────────────┐    ┌──────────────────────────┐   │
│  │ Recursive Handler│    │    Tool Bridge           │   │
│  │ • Depth ≤ 3      │    │  • bash, read, grep      │   │
│  │ • Model cascade  │    │  • Permission control    │   │
│  │ • Sub-query spawn│    │  • Blocked commands      │   │
│  └──────────────────┘    └──────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│                  PERSISTENCE LAYER                      │
│                                                         │
│  ┌──────────────────┐    ┌──────────────────────────┐   │
│  │  Memory Store    │    │   Reasoning Traces       │   │
│  │  • Facts, exps   │    │  • Goals, decisions      │   │
│  │  • Hyperedges    │    │  • Options, outcomes     │   │
│  │  • SQLite + WAL  │    │  • Decision trees        │   │
│  └──────────────────┘    └──────────────────────────┘   │
│           │                         │                   │
│           ▼                         ▼                   │
│  ┌──────────────────┐    ┌──────────────────────────┐   │
│  │ Memory Evolution │    │   Strategy Cache         │   │
│  │ task → session   │    │  • Learn from success    │   │
│  │ session → long   │    │  • Similarity matching   │   │
│  │ decay → archive  │    │  • Suggest strategies    │   │
│  └──────────────────┘    └──────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│                  BUDGET & TRAJECTORY                    │
│  • Token tracking per component                         │
│  • Cost limits with alerts                              │
│  • Streaming trajectory output                          │
│  • JSON export for analysis                             │
└─────────────────────────────────────────────────────────┘
    │
    ▼
Final Answer

---

rlm-core Integration

RLM-Claude-Code bundles rlm-core, a Rust library providing high-performance pattern classification, memory storage, and trajectory tracking via PyO3 bindings.

rlm-core is a required dependency — there is no Python fallback mode.

Configuration

Setting	Behavior
activation.mode	"complexity" (default), "always", "never"
depth.default	Default recursion depth (default: 2)
depth.max	Maximum recursion depth (default: 3)

Performance

Component	Implementation
Pattern Classifier	Rust via PyO3
Trajectory Events	Rust types via PyO3
Memory Store	rlm_core SQLite (nodes/edges) + Python SQLite (auxiliary tables)

Benefits

• Consistency: Same classification logic as recurse TUI
• Performance: Rust pattern matching is significantly faster
• Shared Codebase: Bug fixes benefit both projects

Python Bindings Usage

from src.complexity_classifier import should_activate_rlm, extract_complexity_signals
from src.types import SessionContext, Message, MessageRole

# Delegates to rlm_core.PatternClassifier
ctx = SessionContext(messages=[Message(role=MessageRole.USER, content="test")])
signals = extract_complexity_signals("Find security vulnerabilities", ctx)
activate, reason = should_activate_rlm("Find security vulnerabilities", ctx)

---

Core Components

REPL Environment

The REPL provides a sandboxed Python environment for context manipulation:

Context Variables:

• conversation - List of message dicts with role and content
• files - Dict mapping filenames to content
• tool_outputs - List of tool execution results
• working_memory - Scratchpad for intermediate results

Helper Functions:

Function	Description
peek(var, start, end)	View a slice of any context variable
search(var, pattern, regex=False)	Find patterns in context
summarize(var, max_tokens)	LLM-powered summarization
llm(query, context, spawn_repl)	Spawn recursive sub-query
llm_batch([(q1,c1), (q2,c2), ...])	Parallel LLM calls
map_reduce(content, map_prompt, reduce_prompt, n_chunks)	Partition and aggregate
find_relevant(content, query, top_k)	Find most relevant sections
extract_functions(content)	Parse function definitions
run_tool(tool, *args)	Safe subprocess (uv, ty, ruff)

Memory Functions (when enabled):

Function	Description
memory_query(query, limit)	Search stored knowledge
memory_add_fact(content, confidence)	Store a fact
memory_add_experience(content, outcome, success)	Store an experience
memory_get_context(limit)	Retrieve relevant context
memory_relate(node1, node2, relation)	Create relationships

Available Libraries:

Library	Alias	Description
re	-	Regular expressions
json	-	JSON encoding/decoding
pydantic	BaseModel, Field	Data validation
hypothesis	given, st	Property-based testing
cpmpy	cp	Constraint programming
numpy	np	Numerical computing
pandas	pd	DataFrames and analysis
polars	pl	Fast DataFrames
seaborn	sns	Statistical visualization

Memory System

Persistent storage for cross-session learning:

• Node Types: facts, experiences, procedures, goals
• Memory Tiers: task → session → longterm → archive
• Session Isolation: task/session tiers are isolated per terminal; longterm/archive shared (see docs/session-isolation.md)
• Hyperedges: N-ary relationships with typed roles
• Storage: SQLite with WAL mode for concurrent access

from src import MemoryStore, MemoryEvolution

# Create and use memory
store = MemoryStore(db_path="~/.claude/rlm-memory.db")
fact_id = store.create_node(
    node_type="fact",
    content="This project uses FastAPI",
    confidence=0.9,
)

# Evolve memory through tiers
evolution = MemoryEvolution(store)
evolution.consolidate(task_id="current-task")  # task → session
evolution.promote(session_id="current-session")  # session → longterm
evolution.decay(days_threshold=30)  # longterm → archive

Reasoning Traces

Track decision-making for transparency and debugging: