recursive-rlm 0.1.0

RLM Runtime — turn any LLM into a Recursive Language Model

RLM: Agent Memory Infrastructure

Auto-rollback, episodic memory, and learned context selection for AI agents.

RLM watches any AI coding agent, catches test failures instantly, rolls back bad edits, and builds memory so the same mistake never happens twice. Works with Cursor, Claude Code, Codex, Aider, or any agent that writes files.

pip install rlm
rlm watch --test "pytest"

That's it. Your agent writes code. RLM guards the tests.

---

How It Works

Agent edits file → Tests run → Pass? Continue. Fail? Roll back instantly.
                                                     ↓
                                              Store in memory
                                                     ↓
                                         Next time agent touches
                                          this file → warn it:
                                       "this failed 3 times before"

Every rollback makes the next agent smarter. Memory persists across sessions, agents, and teammates.

---

Quickstart

pip install rlm
cd your-project

# Watch mode — guard any agent's edits
rlm watch --test "pytest tests/ -q"

# Or run a task directly with rollback protection
rlm run "fix the auth bug" --test "pytest tests/"

# Connect to your IDE
rlm setup cursor    # auto-configures Cursor MCP
rlm setup claude    # auto-configures Claude Desktop MCP

╭──────────────────── Recursive Labs ─────────────────────╮
│ RLM Watch — Active                                      │
│ Repo:  /your/project                                    │
│ Tests: pytest tests/ -q                                 │
╰─────────────────────────────────────────────────────────╯

  Changed: auth.py
  ✗ Newly failing: tests/test_auth.py::test_login
  ↩  Rolling back 1 file(s)...
  ✓ Repo restored. Failure saved to history.
     ~4,000 tokens saved · $0.012 · session total: 1 rollback

---

Features

Core

Command	What it does
rlm watch	Live filesystem guardian. Rolls back any agent's bad edits.
rlm run	Execute a task with rollback protection and memory injection.
rlm demo	Interactive demo: memory warnings + live rollback (no setup needed).
rlm demo --domain config	Same demo, but with JSON schema verification instead of pytest.
rlm status	Show memory, graph, selector, and token savings stats.
rlm report	Weekly summary: rollbacks, patterns learned, cost saved, risky files.

Memory & Intelligence

Command	What it does
rlm index	Index codebase for hybrid BM25 + semantic search.
rlm query "auth flow"	Search codebase and episodic memories.
rlm sync	Cross-repo memory sync — promote recurring failures globally.
rlm dashboard	Local web console: trajectories, call graph, selector weights.

Infrastructure

Command	What it does
rlm init	Scan repo, build dependency graph, prepare runtime.
rlm setup cursor/claude	Auto-configure MCP for your IDE.
rlm serve	Start MCP stdio server (10 tools for agent integration).
rlm benchmark	Score LLM before and after RLM.
rlm contribute	Opt in/out of anonymized trajectory sharing.

Advanced

Flag	What it does
--recursive --depth 2	Use recursive inference engine (Zhang et al., 2026).
--max-context-tokens N	Cap token budget for context packing.
--no-history	Disable local history storage.

---

Not Just Code: Domain-Agnostic Verification

RLM isn't locked to pytest. The Verifier interface makes rollback + memory work for any domain:

from RLM.engine.verifiers import JsonSchemaVerifier, HttpVerifier, CompositeVerifier

# Verify config files against a schema
verifier = JsonSchemaVerifier("service.json", schema={
    "required": ["port", "replicas"],
    "properties": {
        "port": {"type": "integer", "minimum": 1024},
        "replicas": {"type": "integer", "minimum": 1},
    }
})

# Verify an API endpoint returns 200
verifier = HttpVerifier("http://localhost:8080/health", expected_status=200)

# Chain multiple verifiers
verifier = CompositeVerifier([pytest_verifier, schema_verifier, http_verifier])

Try it: rlm demo --domain config shows JSON schema verification with the same rollback + memory system.

---

MCP Tools (10 tools for agent integration)

RLM ships a stdio MCP server exposing memory, search, and analysis to any connected agent:

rlm serve   # or: rlm setup cursor

Tool	What it does
get_current_context	Full context: file, trace, blast radius, memories
get_relevant_memories	Query episodic memory for past failures on this path
get_blast_radius	Dependency graph: what breaks if this file changes
get_file_risk_scores	Caution score (0-1) based on past rollbacks + complexity
eval_diff	Analyze current diff: changed symbols, blast radius, past failures, suggested tests
codebase_search	Hybrid BM25 + semantic search over local codebase
write_agent_memory	Agent writes verified outcomes to memory
reindex_codebase	Trigger incremental codebase indexing
get_active_file	Current file, cursor, selection from IDE
get_terminal_trace	Latest command, exit code, trace

---

The Learning Loop

RLM isn't just a rollback tool. Every rollback provides a verified failure-to-recovery trajectory. RLM accumulates these and trains a Context Selector -- a per-repo model that learns which context chunks actually predict success.

Rollback events → SQLiteHistory → RL Selector training
                                       ↓
                              P(success | query, context)
                                       ↓
                         Smart context selection for next run

The selector uses bilinear query-by-chunk features. After 30+ trajectories, it replaces cosine similarity with learned rankings. It knows "what went wrong before" is more predictive than "what looks similar."

---

Constraint-Aware Planning

RLM includes a ConstraintSpec system inspired by multi-objective RL:

from RLM.engine.constraints import ConstraintSpec

# Define constraints explicitly
spec = ConstraintSpec(
    forbidden_files={"production.env", "deploy.yaml"},
    resource_ceilings={"cost_usd": 1.0, "api_calls": 50},
)

# Or learn constraints from past failures
spec = ConstraintSpec.from_history(history, repo_path=".")
# Automatically marks files with 3+ failures as high-risk

Forbidden actions are structurally masked out before scoring -- an illegal path has probability zero, not a low score.

---

Cross-Repo Memory

Failure patterns that appear across multiple repos are automatically promoted to global scope:

rlm sync                 # auto-promote cross-repo failures
rlm sync --list-global   # see all global memories

A failure pattern learned in repo A surfaces as a warning in repo B. One team member's mistake teaches every agent on the team.

---

Architecture

┌─────────────────────────────────────────────┐
│  CLI (rlm watch / run / demo / report)      │
├─────────────────────────────────────────────┤
│  Engine                                     │
│  ├── WatchLoop (filesystem guardian)        │
│  ├── RollbackLoop (agentic coding loop)     │
│  ├── Verifiers (pytest, schema, http, ...)  │
│  └── ConstraintSpec (Phi — hard masking)    │
├─────────────────────────────────────────────┤
│  Memory                                     │
│  ├── SQLiteHistory (episodic store)         │
│  ├── CodebaseIndexer (BM25 + semantic)      │
│  ├── BudgetSolver (token-aware packing)     │
│  ├── SemanticContextGraph (blast radius)    │
│  └── RL Selector (learned P(success))       │
├─────────────────────────────────────────────┤
│  API                                        │
│  ├── MCP Server (10 tools, stdio)           │
│  ├── ContextOS (unified context layer)      │
│  └── Dashboard (local web console)          │
└─────────────────────────────────────────────┘

---

Privacy

All data stays local. Memory is stored in repo-local .rlm_history.db. Nothing leaves your machine.

rlm contribute --enable   # opt-in to anonymized trajectory sharing
rlm contribute --disable  # opt-out (default)

---

Comparison

	RLM	Perseus	Claude Code
Episodic failure memory	Yes	No	No
Auto-rollback on test failure	Yes	No	No
Learned context selection	Yes (RL selector)	No	No
Codebase search	Yes (local, hybrid)	Yes (cloud)	Yes (built-in)
Blast radius analysis	Yes (file + symbol)	Yes (symbol)	No
Cross-repo memory	Yes	No	No
Domain-agnostic verifiers	Yes (4 types)	No	No
Constraint masking	Yes	Yes (unshipped)	No
Local-first / offline	Yes	No (cloud)	Yes
Open source	Yes	No	Partial
Gets smarter over time	Yes (RL selector)	No	No

---

Development

git clone https://github.com/arushsinghal/RLM.git
cd RLM
pip install -e ".[dev]"
pytest RLM/tests/ -q    # 201 tests

---

Roadmap

• Now: CLI rollback tool + context selector + MCP server + cross-repo memory
• Next: SWE-bench benchmarks, Zhang RLM recursive integration, PyPI v0.1.0
• Later: RLM-0 foundation model trained on verified failure/recovery trajectories

---

Built by Recursive Labs