# [ARCHIVED] Aleph RLM Enhancement Plan

> Enable Recursive Language Model (RLM) patterns in Aleph - allowing the host AI to spawn sub-agents that can reason over context slices, without requiring external API keys.

- Skill: `tools-only/archived-aleph-rlm-enhancement-plan` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/archived-aleph-rlm-enhancement-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/archived-aleph-rlm-enhancement-plan/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/archived-aleph-rlm-enhancement-plan

---

# [ARCHIVED] Aleph RLM Enhancement Plan

> **Note:** This document is historical. The features described here have been implemented in v0.5.0. See the main [README.md](../../README.md) for current documentation.

> January 4, 2026

## Goal

Enable **Recursive Language Model (RLM)** patterns in Aleph - allowing the host AI to spawn sub-agents that can reason over context slices, without requiring external API keys.

Based on: [Recursive Language Models (arXiv:2512.24601)](https://arxiv.org/abs/2512.24601)

---

## Core Insight

The RLM paper's key breakthrough: **treat context as an external environment variable**, then let the LLM programmatically decompose and recursively query itself over chunks.

Aleph already has:
- ✅ Context as `ctx` variable
- ✅ REPL with 80+ helpers (`peek`, `search`, `chunk`, etc.)
- ✅ Evidence/citation tracking
- ✅ Variable persistence

**What's missing**: True recursive sub-LLM calls where the sub-agent can also use tools.

---

## Architecture: CLI-Based Sub-Agent Spawning

### The Problem
MCP servers can't call themselves - tools are invoked BY the host AI, not by Aleph.

### The Solution
Spawn sub-agents via CLI tools that the user is already authenticated with:

```
┌─────────────────────────────────────────────────────────┐
│ Host AI (Claude Desktop / Cursor / Codex)               │
│   └─ calls Aleph MCP tools                              │
│       └─ sub_query(prompt, context_slice)               │
│           └─ spawns: claude -p "prompt" --no-input      │
│               └─ returns result to Aleph                │
│                   └─ Aleph returns to Host AI           │
└─────────────────────────────────────────────────────────┘
```

### Supported CLI Backends

| Backend | Command | Notes |
|---------|---------|-------|
| `claude` | `claude --dangerously-skip-permissions -p "prompt"` | Claude Code CLI |
| `codex` | `codex -q "prompt"` | OpenAI Codex CLI |
| `aider` | `aider --message "prompt" --yes` | Aider CLI |
| `api` | Direct API call | Requires API key (fallback) |

---

## Implementation Steps

### Step 1: Add SubQueryBackend Configuration

Create `aleph/sub_query/__init__.py`:

```python
from dataclasses import dataclass
from typing import Literal

@dataclass
class SubQueryConfig:
    """Configuration for sub-query backend."""
    backend: Literal["claude", "codex", "aider", "api", "auto"] = "auto"
    
    # CLI options
    cli_timeout_seconds: float = 120.0
    cli_max_output_chars: int = 50_000
    
    # API fallback options (if backend="api")
    # Default: Mimo Flash V2 (free public beta until Jan 20, 2026)
    # Uses OpenAI-compatible API format
    api_base_url_env: str = "OPENAI_BASE_URL"
    api_key_env: str = "OPENAI_API_KEY"
    api_model: str = "mimo-v2-flash"
    
    # Behavior
    max_context_chars: int = 100_000  # truncate context slice if too long
    include_system_prompt: bool = True
```

### Step 2: Implement CLI Backend Runner

Create `aleph/sub_query/cli_backend.py`:

```python
import asyncio
import shlex
from pathlib import Path

async def run_cli_sub_query(
    prompt: str,
    context_slice: str | None,
    backend: str,
    timeout: float = 120.0,
    cwd: Path | None = None,
) -> tuple[bool, str]:
    """
    Spawn a CLI sub-agent and return its response.
    
    Returns (success, output)
    """
    
    # Build the full prompt
    full_prompt = prompt
    if context_slice:
        full_prompt = f"{prompt}\n\n---\nContext:\n{context_slice}"
    
    # Escape for shell
    escaped_prompt = shlex.quote(full_prompt)
    
    # Build command based on backend
    if backend == "claude":
        cmd = f'claude --dangerously-skip-permissions -p {escaped_prompt} --no-input'
    elif backend == "codex":
        cmd = f'codex -q {escaped_prompt}'
    elif backend == "aider":
        cmd = f'aider --message {escaped_prompt} --yes --no-git'
    else:
        return False, f"Unknown CLI backend: {backend}"
    
    # Run the command
    proc = await asyncio.create_subprocess_shell(
        cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
        cwd=str(cwd) if cwd else None,
    )
    
    try:
        stdout, stderr = await asyncio.wait_for(
            proc.communicate(),
            timeout=timeout
        )
        output = stdout.decode("utf-8", errors="replace")
        if proc.returncode != 0:
            err = stderr.decode("utf-8", errors="replace")
            return False, f"CLI error (exit {proc.returncode}): {err}"
        return True, output
    except asyncio.TimeoutError:
        proc.kill()
        return False, f"CLI timeout after {timeout}s"
```

### Step 3: Implement API Fallback Backend

Create `aleph/sub_query/api_backend.py`:

```python
import os
import httpx

async def run_api_sub_query(
    prompt: str,
    context_slice: str | None,
    model: str = "mimo-v2-flash",
    api_key_env: str = "OPENAI_API_KEY",
    api_base_url_env: str = "OPENAI_BASE_URL",
    timeout: float = 60.0,
) -> tuple[bool, str]:
    """
    Run sub-query via OpenAI-compatible API.
    
    Default: Mimo Flash V2 (free public beta until Jan 20, 2026)
    
    Returns (success, output)
    """
    api_key = os.environ.get(api_key_env)
    base_url = os.environ.get(api_base_url_env, "https://api.openai.com/v1")
    
    if not api_key:
        return False, f"API key not found in ${api_key_env}. Set OPENAI_API_KEY for Mimo Flash V2."
    
    full_prompt = prompt
    if context_slice:
        full_prompt = f"{prompt}\n\n---\nContext:\n{context_slice}"
    
    url = f"{base_url.rstrip('/')}/chat/completions"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    }
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": full_prompt}],
        "max_tokens": 8192,
    }
    
    async with httpx.AsyncClient() as client:
        try:
            resp = await client.post(
                url,
                json=payload,
                headers=headers,
                timeout=timeout,
            )
            
            if resp.status_code != 200:
                return False, f"API error {resp.status_code}: {resp.text}"
            
            data = resp.json()
            text = data["choices"][0]["message"]["content"]
            return True, text
        except httpx.TimeoutException:
            return False, f"API timeout after {timeout}s"
        except (KeyError, IndexError) as e:
            return False, f"Failed to parse API response: {e}"
        except Exception as e:
            return False, f"API request failed: {e}"
```

### Step 4: Add `sub_query` MCP Tool

Update `aleph/mcp/local_server.py` - add this tool registration:

```python
@self.server.tool()
async def sub_query(
    prompt: str,
    context_slice: str | None = None,
    context_id: str = "default",
    backend: str = "auto",
) -> str:
    """
    Run a sub-query using a spawned sub-agent.
    
    This enables RLM-style recursive reasoning: break your problem
    into chunks, query a sub-agent for each chunk, aggregate results.
    
    Args:
        prompt: The question/task for the sub-agent
        context_slice: Optional context to include (from ctx variable)
        context_id: Session to record evidence in
        backend: "auto", "claude", "codex", "aider", or "api"
    
    Returns:
        The sub-agent's response
    
    Example usage in exec_python:
        chunks = chunk(100000)
        results = []
        for i, c in enumerate(chunks):
            answer = sub_query(f"Summarize chunk {i}", context_slice=c)
            results.append(answer)
        final = sub_query("Combine these summaries: " + str(results))
    """
    session = self._sessions.get(context_id)
    if session:
        session.iterations += 1
    
    # Auto-detect backend
    resolved_backend = backend
    if backend == "auto":
        resolved_backend = _detect_cli_backend()
    
    # Truncate context if needed
    if context_slice and len(context_slice) > self.sub_query_config.max_context_chars:
        context_slice = context_slice[:self.sub_query_config.max_context_chars] + "\n...[truncated]"
    
    # Try CLI first, fall back to API
    if resolved_backend in ("claude", "codex", "aider"):
        success, output = await run_cli_sub_query(
            prompt=prompt,
            context_slice=context_slice,
            backend=resolved_backend,
            timeout=self.sub_query_config.cli_timeout_seconds,
            cwd=self.action_config.workspace_root if self.action_config else None,
        )
    else:
        success, output = await run_api_sub_query(
            prompt=prompt,
            context_slice=context_slice,
            model=self.sub_query_config.api_model,
            api_key_env=self.sub_query_config.api_key_env,
            api_base_url_env=self.sub_query_config.api_base_url_env,
        )
    
    # Record evidence
    if session and success:
        session.evidence.append(_Evidence(
            source="sub_query",
            line_range=None,
            pattern=None,
            snippet=output[:200],
            note=f"backend={resolved_backend}",
        ))
    
    if not success:
        return f"## Sub-Query Error\n\n{output}"
    
    return f"## Sub-Query Result\n\n{output}"


def _detect_cli_backend() -> str:
    """Auto-detect available CLI backend."""
    import shutil
    
    if shutil.which("claude"):
        return "claude"
    if shutil.which("codex"):
        return "codex"
    if shutil.which("aider"):
        return "aider"
    return "api"  # fallback
```

### Step 5: Inject `sub_query` into REPL Namespace

Update `REPLEnvironment` to expose `sub_query` as a callable inside `exec_python`:

```python
# In sandbox.py, after inject_sub_query:

def inject_sub_query(self, fn: SubQueryFn) -> None:
    """Inject sub_query(prompt, context_slice=None) into the REPL namespace."""
    self._sub_query_fn = fn
    self._namespace["sub_query"] = self._sync_bridge(fn)
```

This already exists! We just need to wire it up in local_server.py.

### Step 6: Update Configuration & Environment

Add to `.env.example`:
```bash
# =============================================================================
# Sub-Query API Configuration (for RLM-style recursive reasoning)
# =============================================================================
# Required if no CLI backend (claude/codex/aider) is available.
#
# Default: Mimo Flash V2 - FREE public beta until Jan 20, 2026
# A strong reasoning model, perfect for sub-agent tasks.
#
# Get your free API key at: https://mimo.ai
# Then set these environment variables:

OPENAI_API_KEY=your_mimo_api_key_here
OPENAI_BASE_URL=https://api.mimo.ai/v1

# Model to use for sub-queries (default: mimo-v2-flash)
# ALEPH_SUB_QUERY_MODEL=mimo-v2-flash

# =============================================================================
# Alternative: Use any OpenAI-compatible API
# =============================================================================
# Examples:
#   OpenAI:     OPENAI_BASE_URL=https://api.openai.com/v1
#   Groq:       OPENAI_BASE_URL=https://api.groq.com/openai/v1
#   Together:   OPENAI_BASE_URL=https://api.together.xyz/v1
#   Local:      OPENAI_BASE_URL=http://localhost:11434/v1 (Ollama)
```

### Step 7: Add Documentation

Update README.md with:
```markdown
## Recursive Sub-Queries (RLM Mode)

Aleph supports RLM-style recursive reasoning. Inside `exec_python`, you can call:

```python
# Break context into chunks and process each
chunks = chunk(100000)  # 100k char chunks
summaries = []
for c in chunks:
    summary = sub_query("Summarize this section:", context_slice=c)
    summaries.append(summary)

# Aggregate
final = sub_query(f"Combine these {len(summaries)} summaries into a final answer")
print(final)
```

**Backend Priority:**
1. `claude` CLI (if installed) - uses your existing Claude subscription
2. `codex` CLI (if installed) - uses your existing OpenAI subscription
3. `aider` CLI (if installed)
4. **Mimo Flash V2 API** (FREE until Jan 20, 2026) - strong reasoning model

To use the API fallback, set in your environment:
```bash
export OPENAI_API_KEY=your_mimo_key
export OPENAI_BASE_URL=https://api.mimo.ai/v1
```

Set `ALEPH_SUB_QUERY_BACKEND=api` to force API mode.
```

---

## File Changes Summary

| File | Action | Description |
|------|--------|-------------|
| `aleph/sub_query/__init__.py` | Create | SubQueryConfig dataclass |
| `aleph/sub_query/cli_backend.py` | Create | CLI spawning logic |
| `aleph/sub_query/api_backend.py` | Create | API fallback (Gemini) |
| `aleph/mcp/local_server.py` | Modify | Add `sub_query` tool, wire up config |
| `aleph/repl/sandbox.py` | Verify | Already has `inject_sub_query` |
| `.env.example` | Create/Update | Document env vars |
| `README.md` | Update | Document RLM mode |
| `tests/test_sub_query.py` | Create | Unit tests |

---

## Testing Plan

1. **CLI backend test**: Mock subprocess, verify command construction
2. **API backend test**: Mock httpx, verify Gemini request format
3. **Integration test**: Load context, run `exec_python` with `sub_query` calls
4. **E2E test**: Actually spawn Claude CLI (manual, requires Claude Code installed)

---

## Rollout

1. **Phase 1** (this PR): CLI backends + Gemini API fallback
2. **Phase 2**: Parallel batch sub-queries (`batch_sub_query`)
3. **Phase 3**: Sub-agent can use Aleph tools (true recursion via MCP-over-stdio)

---

## Open Questions

- [ ] Should sub_query results auto-cite into evidence?
- [ ] Rate limiting for API fallback?
- [ ] Should we support streaming responses?
- [ ] Token counting for sub-queries?