aleph: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is Aleph

Aleph is an MCP server implementing Recursive Language Models (RLMs). It loads large data (up to ~1GB) into RAM as in-memory contexts, letting LLMs explore data via search/peek/code execution without consuming the context window. Only results enter the LLM prompt, never raw content. Published on PyPI as aleph-rlm.

Build & Development Commands

# Install for development (Python 3.10+ required)
pip install -e ".[dev,mcp]"

# Run all tests
pytest tests/ -v

# Run a single test file
pytest tests/test_helpers.py -v

# Run a specific test class or method
pytest tests/test_helpers.py::TestPeek::test_peek_full -v

# Type checking
mypy aleph/

# Version is in two places — sync with:
python scripts/sync_versions.py

Tests use pytest-asyncio with asyncio_mode = "auto" (no need for @pytest.mark.asyncio). CI runs on Python 3.10, 3.11, 3.12.

Architecture

Core RLM Loop (aleph/core.py)

The Aleph class implements the RLM pattern: load context into a sandboxed REPL variable (ctx), send query+metadata to an LLM, then loop — parsing the LLM response for code blocks or FINAL(...) answers, executing code in the sandbox, feeding results back — until the answer converges or the budget is exhausted.

MCP Server (aleph/mcp/local_server.py)

AlephMCPServerLocal is the primary interface. It exposes 30+ tools to MCP clients (Claude Desktop, Cursor, VSCode, Claude Code). Entry point: aleph command. Key flags: --enable-actions (filesystem/shell tools), --workspace-mode any, --tool-docs concise.

Tool categories: context management (load/list/diff/peek/search), computation (exec_python, get_variable), reasoning (think, evaluate_progress, summarize_so_far, finalize), recursion (sub_query, sub_aleph), action tools (read_file, write_file, run_command, rg_search, run_tests), recipes (run_recipe, compile_recipe), and remote MCP orchestration.