aleph

Aleph

Aleph is an MCP server and skill for Recursive Language Models (RLMs). It keeps working state — search indexes, code execution, evidence, recursion — in a Python process outside the prompt window, so the LLM reasons iteratively over large codebases, long-lived projects, logs, documents, and data without burning context on raw content.

+-----------------+    tool calls     +-----------------------------+
|   LLM client    | ---------------> |  Aleph (Python process)     |
| (context budget)| <--------------- |  search / peek / exec / sub |
+-----------------+   small results  +-----------------------------+

Why Aleph:

• Load once, reason many times. Data lives in Aleph memory, not the prompt.
• Compute server-side. exec_python runs code over the full context and returns only derived results. For JS/TS repos, exec_javascript and exec_typescript provide a persistent Node.js runtime over the same ctx.
• Recurse. Sub-queries and recipes split complex work across multiple reasoning passes.
• Keep workspaces warm. Bind contexts back to files or generated workspace manifests, refresh them, and resume long investigations later.

Quick Start

pip install "aleph-rlm[mcp]"
aleph-rlm install --profile claude   # or: codex, portable, api
aleph-rlm doctor                     # verify everything is wired up

Then restart your MCP client and confirm Aleph is available:

get_status()
list_contexts()

The optional /aleph (Claude Code) or $aleph (Codex) skill shortcut starts a structured RLM workflow. Install docs/prompts/aleph.md into your client's command/skill folder — see MCP_SETUP.md for exact paths.

If you are using action tools on a real repo, the safest default is:

aleph --enable-actions --action-policy read-only

Cursor

Use global MCP (aleph-rlm install cursor) for --workspace-mode any, or project MCP (aleph-rlm install cursor-project from the repo) for ${workspaceFolder} + --workspace-mode fixed. Chat, Composer, and the Cursor CLI share that MCP config; a Cursor extension is optional and not required for Aleph — see MCP_SETUP.md.

Entry Points

Command	Module	What it does
aleph	aleph.mcp.local_server:main	MCP server. This is what MCP clients launch. Exposes 30+ tools for context management, search, code execution, reasoning, recursion, and action tools.
aleph-rlm	aleph.cli:main	Installer and CLI. install, configure, doctor, uninstall for setting up MCP clients. Also: run (single query), shell (interactive REPL), serve (start MCP server manually).

Install Profiles

aleph-rlm install asks which sub-query profile to use. Profiles configure the nested backend that sub_query and sub_query_batch spawn for recursive reasoning.

Profile	What it pins
portable	No nested backend — you choose later or rely on auto-detection
claude	Claude CLI: --model opus, --effort low, shared session enabled
codex	Codex MCP: gpt-5.4, low reasoning effort, shared session enabled
api	OpenAI-compatible API — set ALEPH_SUB_QUERY_API_KEY and ALEPH_SUB_QUERY_MODEL

aleph-rlm install claude-code --profile claude
aleph-rlm configure --profile codex   # overwrite existing config

See docs/CONFIGURATION.md for all env vars, CLI flags, and runtime configure(...) options.

Large Codebase Workflow

If your main use case is a repo or multi-folder project, start by loading a compact workspace manifest instead of throwing raw source files into the model window. That gives the model a map of the project, lets it search aggressively, and keeps the session refreshable as the repo changes.

load_workspace_manifest(paths=["src", "tests"], context_id="repo")
rg_search(pattern="FastAPI|APIRouter|router\\.", paths=["src", "tests"], load_context_id="routes")
load_file(path="pyproject.toml", context_id="pyproject")
exec_python(code="""
files = [line for line in ctx.splitlines() if line.startswith("- ")]
summary = {
    "indexed_entries": len(files),
    "top_python_files": [line for line in files if "| python |" in line][:10],
}
""", context_id="repo")
get_variable(name="summary", context_id="repo")
refresh_context(context_id="repo")