Aleph

Aleph

Aleph is an MCP server and skill forRecursive Language Models (RLMs). It keeps working state — search indexes,code execution, evidence, recursion — in a Python process outside the promptwindow, so the LLM reasons iteratively over large codebases, long-livedprojects, 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 andreturns only derived results. For JS/TS repos, exec_javascript andexec_typescript provide a persistent Node.js runtime over the same ctx.
• Recurse. Sub-queries and recipes split complex work across multiplereasoning passes.
• Keep workspaces warm. Bind contexts back to files or generated workspacemanifests, 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 startsa structured RLM workflow. Installdocs/prompts/aleph.md into your client'scommand/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, orproject MCP (aleph-rlm install cursor-project from the repo) for${workspaceFolder} + --workspace-mode fixed. Chat, Composer, and the CursorCLI share that MCP config; a Cursor extension is optional and not required forAleph — see MCP_SETUP.md.

Entry Points

Install Profiles

aleph-rlm install asks which sub-query profile to use. Profiles configurethe nested backend that sub_query and sub_query_batch spawn for recursivereasoning.

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

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

Large Codebase Workflow

If your main use case is a repo or multi-folder project, start by loading acompact workspace manifest instead of throwing raw source files into the modelwindow. 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")

Use load_workspace_manifest as the default front door for large codebases andprojects. Then pull in specific files with load_file, search the repo withrg_search, and refresh the bound context when the workspace changes. Refreshespreserve the session's reasoning state, evidence log, and tracked tasks.

Single File Workflow

Aleph is also strong when you load one large file once, do the heavy workinside Aleph, and only pull back compact answers.

load_file(path="/absolute/path/to/large_file.log", context_id="doc")
search_context(pattern="ERROR|WARN", context_id="doc")
peek_context(start=1, end=60, unit="lines", context_id="doc")
exec_python(code="""
errors = [line for line in ctx.splitlines() if "error" in line.lower()]
result = {
    "error_count": len(errors),
    "first_error": errors[0] if errors else None,
}
""", context_id="doc")
get_variable(name="result", context_id="doc")
save_session(context_id="doc", path=".aleph/doc.json")

The important habit is to compute server-side. Do not treat get_variable("ctx")as the default path. Search, filter, chunk, or summarize first, then retrieve asmall result.

If you want terminal-only mode instead of MCP, use:

aleph run "Summarize this log" --provider cli --model codex --context-file app.log

Local Models (llama.cpp)

Aleph can use a local model instead of a cloud API. This runs the full RLMloop — search, code execution, convergence — entirely on your machine withzero API cost.

Prerequisites: llama.cpp and aGGUF model file.

# Install llama.cpp
brew install llama.cpp          # Mac
winget install ggml.LlamaCpp    # Windows

# Start the server with your model
llama-server -m /path/to/model.gguf -c 16384 -ngl 99 --port 8080

Point Aleph at the running server:

export ALEPH_PROVIDER=llamacpp
export ALEPH_LLAMACPP_URL=http://127.0.0.1:8080
export ALEPH_MODEL=local
aleph

Or let Aleph start the server automatically:

export ALEPH_PROVIDER=llamacpp
export ALEPH_LLAMACPP_MODEL=/path/to/model.gguf
export ALEPH_LLAMACPP_CTX=16384
export ALEPH_MODEL=local
aleph

Tested with Qwen 3.5 9B (Q8_0, ~9 GB). Any GGUF model works — larger modelsgive better results in the RLM loop. Models with reasoning/thinking support(Qwen 3.5, QwQ, etc.) are handled automatically. SeeCONFIGURATION.md for all ALEPH_LLAMACPP_*variables.

Common Workloads

Core Tools

Python vs JS/TS REPL

Aleph's primary control layer is still Python. exec_python remains thedefault REPL for general-purpose analysis, recipes, and orchestration.

• Use exec_python when you need the full Aleph surface area: Python-firstprompts, Python's numeric / symbolic stack (cmath, mpmath, decimal,fractions, statistics, numpy, scipy, sympy, networkx), orrecipe execution via run_recipe_code.

• Use exec_javascript / exec_typescript when the target repo or analysis isnaturally JS/TS-shaped and you want persistent Node state, JS-native array /object manipulation, or async recursion with await.

• exec_pythonFull Aleph helper surface, including recipe DSL helpers, synchronoussub_query(...) / sub_aleph(...), and the widest compatibility withexisting prompts and workflows.

• exec_javascript / exec_typescriptPersistent Node.js runtime per context for JS/TS-heavy repos. Shares the samectx, supports top-level await, and can recurse with asyncawait sub_query(...), await sub_query_batch(...),await sub_query_map(...), await sub_query_strict(...), andawait sub_aleph(...). Also includes the recipe DSL (Recipe, Search,Take, etc.) for building recipe payloads in JS/TS.

The JS/TS runtime also ships with a broader local helper set than the firsthandoff slice: search/peek/lines/chunk, extraction helpers (extract_emails,extract_todos, extract_routes, etc.), text utilities (number_lines,grep_v, sort_lines, normalize_whitespace, etc.), text comparison helpers(diff, similarity, common_lines, diff_lines), collection helpers(flatten, group_by, frequency, sample_items, shuffle_items, etc.),validation helpers (is_json, is_email, is_uuid, etc.), CSV / JSONconverters, and semantic_search.

The JS/TS runtime now also includes the Recipe DSL: RecipeStep,RecipeBuilder, and all step constructors (Recipe, Search, Peek,Lines, Take, Chunk, Filter, MapSubQuery, SubQuery, Aggregate,Assign, Load, Finalize, as_recipe). You can build recipes withfluent chaining or pipe-style:

// Fluent style
Recipe("doc").search("ERROR").take(5).finalize().compile()

// Pipe style
Recipe("doc").pipe(Search("ERROR")).pipe(Take(5)).pipe(Finalize()).compile()

The compile_recipe and run_recipe_code MCP tools accept a languageparameter ("python", "javascript", "typescript") to compile recipe DSLcode in the corresponding runtime.

What still differs from Python:

• Python is still the default and best-supported Aleph REPL.
• JS/TS recursion helpers are async and require await.
• Recipe execution (run_recipe) always uses the Python runtime. The JS/TSpath covers recipe building and compilation only.
• JS uses RecipeBuilder.pipe() / fluent methods instead of Python's |operator (JS | is bitwise OR, not overloadable for this purpose).
• Python's import ecosystem remains Python-only. The Node runtime is helper-led:no require, no process, no module, and no npm package loading insidethe sandbox.
• exec_typescript strips type syntax for execution; it is not a full TScompiler, typechecker, or ts-node environment.
• Regex flag behavior follows each runtime: Python helpers use Python reflags, while JS/TS helpers use JavaScript regex flag strings.

Example JS/TS workflow:

exec_typescript(code=`
const routes: string[] = extract_routes('javascript').map((item) => item.value);
const routeKinds = frequency(
  routes.map((route) => (route.includes('.post(') ? 'write' : 'read')),
  2,
);
const notes = await sub_query_map(
  routes.map((route) => `Explain ${route}`),
  routes,
);
({ routeCount: routes.length, routeKinds, notes })
`, context_id="repo")

Safety Model

Aleph is built to keep raw context out of the model window unless youexplicitly pull it back:

• Tool responses are capped and truncated.
• get_variable("ctx") is policy-aware and should not be your default path.
• exec_python stdout, stderr, and return values are bounded independently.
• ALEPH_CONTEXT_POLICY=isolated adds stricter session export/import rules andmore defensive defaults.
• ALEPH_ACTION_POLICY=read-only (or --action-policy read-only) keeps actiontools in read-only mode: search and file loading still work, but writes andsubprocess execution are blocked.

The safest pattern is always:

1. Load the large context into Aleph memory.
2. Search or compute inside Aleph.
3. Retrieve only the small result you need.

Docs Map

• MCP_SETUP.md: client-by-client MCP and skill installation.
• docs/prompts/aleph.md: the /aleph and $alephworkflow plus tool patterns.
• docs/CONFIGURATION.md: flags, env vars, limits, andsafety settings.
• docs/langgraph-rlm-default.md: LangGraphintegration with Aleph-style tool usage.
• examples/langgraph_rlm_repo_improver.py:repo improvement example with optional LangSmith tracing.
• CHANGELOG.md: release history.
• DEVELOPMENT.md: contributor guide.

Development

git clone https://github.com/Hmbown/aleph.git
cd aleph
pip install -e ".[dev,mcp]"
# Optional extras:
#   .[docs]           -> MarkItDown-backed document conversion
#   .[observability]  -> OpenTelemetry spans
pytest tests/ -v
ruff check aleph/ tests/

References

• Zhang, A. L., Kraska, T., Khattab, O. (2025)Recursive Language Models (arXiv:2512.24601)

License

MIT