rlm-rs

Recursive Language Model (RLM) CLI for Claude Code - handles long-context tasks via chunking and recursive sub-LLM calls.

Based on the RLM pattern from arXiv:2512.24601, enabling analysis of documents up to 100x larger than typical context windows.

Features

• Hybrid Semantic Search: Combined semantic + BM25 search with RRF fusion
• Auto-Embedding: Embeddings generated automatically during load (BGE-M3 model)
• Pass-by-Reference: Retrieve chunks by ID for efficient subagent processing
• Multiple Chunking Strategies: Fixed, semantic, code-aware, and parallel chunking
• Code-Aware Chunking: Language-aware chunking at function/class boundaries
• HNSW Vector Index: Optional scalable approximate nearest neighbor search
• Incremental Embedding: Efficient partial re-embedding for updated content
• Agentic Workflow Support: dispatch/aggregate commands for parallel subagent processing
• SQLite State Persistence: Reliable buffer management across sessions
• Regex Search: Fast content search with context windows
• Memory-Mapped I/O: Efficient handling of large files
• JSON/NDJSON Output: Machine-readable output for integration

How It Works

Installation

Via Cargo (Recommended)

cargo install rlm-rs

Via Homebrew

brew tap zircote/tap
brew install rlm-rs

From Source

git clone https://github.com/zircote/rlm-rs.git
cd rlm-rs
make install

Quick Start

# Initialize the database
rlm-rs init

# Load a large document (auto-generates embeddings)
rlm-rs load document.md --name docs --chunker semantic

# Search with hybrid semantic + BM25
rlm-rs search "your query" --buffer docs --top-k 10

# Retrieve chunk by ID (pass-by-reference)
rlm-rs chunk get 42

# Check status
rlm-rs status

# Regex search content
rlm-rs grep docs "pattern" --max-matches 20

# View content slice
rlm-rs peek docs --start 0 --end 3000

Commands

Command	Description
init	Initialize the RLM database
status	Show current state (buffers, chunks, DB info)
load	Load a file into a buffer with chunking (auto-embeds)
search	Hybrid semantic + BM25 search across chunks
update-buffer	Update buffer content with re-chunking
dispatch	Split chunks into batches for parallel subagent processing
aggregate	Combine findings from analyst subagents
chunk get	Retrieve chunk by ID (pass-by-reference)
chunk list	List chunks for a buffer
chunk embed	Generate embeddings (or re-embed with --force)
chunk status	Show embedding status
list	List all buffers
show	Show buffer details
delete	Delete a buffer
peek	View a slice of buffer content
grep	Search buffer content with regex
write-chunks	Write chunks to individual files
add-buffer	Add text to a new buffer
export-buffers	Export all buffers to JSON
var	Get/set context variables
global	Get/set global variables
reset	Delete all RLM state

Chunking Strategies

Strategy	Best For	Description
semantic	Markdown, prose	Splits at natural boundaries (headings, paragraphs)
code	Source code	Language-aware chunking at function/class boundaries
fixed	Logs, plain text	Splits at exact byte boundaries
parallel	Large files (>10MB)	Multi-threaded fixed chunking

# Semantic chunking (default)
rlm-rs load doc.md --chunker semantic

# Code-aware chunking for source files
rlm-rs load src/main.rs --chunker code

# Fixed chunking with overlap
rlm-rs load logs.txt --chunker fixed --chunk-size 150000 --overlap 1000

# Parallel chunking for speed
rlm-rs load huge.txt --chunker parallel --chunk-size 100000

Supported Languages (Code Chunker)

Rust, Python, JavaScript, TypeScript, Go, Java, C/C++, Ruby, PHP

Claude Code Integration

rlm-rs is designed to work with the rlm-rs Claude Code plugin, implementing the RLM architecture:

RLM Concept	Implementation
Root LLM	Main Claude Code conversation (Opus/Sonnet)
Sub-LLM	rlm-subcall agent (Haiku)
External Environment	rlm-rs CLI + SQLite

Development

Prerequisites

• Rust 1.88+ (2024 edition)
• cargo-deny for supply chain security

Build

# Using Makefile
make build          # Debug build
make release        # Release build
make test           # Run tests
make check          # Format + lint + test
make ci             # Full CI check
make install        # Install to ~/.cargo/bin

# Or using Cargo directly
cargo build --release
cargo test
cargo clippy --all-targets --all-features

Project Structure

src/
├── lib.rs           # Library entry point
├── main.rs          # CLI entry point
├── error.rs         # Error types
├── core/            # Core types (Buffer, Chunk, Variable)
├── chunking/        # Chunking strategies
├── storage/         # SQLite persistence
├── io/              # File I/O with mmap
└── cli/             # Command implementations

tests/
└── integration_test.rs

MSRV Policy

The Minimum Supported Rust Version (MSRV) is 1.88.

License

MIT License - see LICENSE for details.

Documentation

Getting Started

• Examples - Practical examples and workflows
• CLI Reference - Complete command documentation
• Troubleshooting - Common issues and solutions

Configuration

• Features Guide - Feature flags and build options
• Plugin Integration - Integration with Claude Code and other tools

Design & Architecture

• RLM-Inspired Design - How rlm-rs builds on the RLM paper
• Architecture - Internal architecture and design
• API Reference - Rust library documentation
• ADRs - Architectural Decision Records

Acknowledgments

• claude_code_RLM - Original Python RLM implementation by Brainqub3 that inspired the creation of this project
• RLM Paper (arXiv:2512.24601) - Recursive Language Model pattern by Zhang, Kraska, and Khattab (MIT CSAIL)
• Claude Code - AI-powered development environment