repository·main·Indexed 42 days ago
https://github.com/hmbown/alephAn MCP server and skill for Recursive Language Models (RLMs) that enables LLMs to reason over large codebases, logs, and data. It maintains state—including search indexes, code execution, and evidence—in a persistent Python process outside the prompt window to prevent context exhaustion. Aleph provides tools for context loading, navigation, computation via Python/JS/TS REPLs, and recursive reasoning, with support for Claude Code, Cursor, and local models via llama.cpp.
If --workspace-root is not explicitly provided, Aleph follows this priority order to determine the workspace:
ALEPH_WORKSPACE_ROOT environment variable.PWD), falling back to INIT_CWD.os.getcwd() to the nearest .git root.Aleph operates in three distinct modes based on how it interacts with Recursive Language Model (RLM) principles. Understanding these helps you choose the right tool for your workflow:
aleph run, alef, or calling Aleph.complete(...) via the API.The integration supports stateful conversations and resumability:
build_rlm_default_graph compiles with checkpointing if a checkpointer is provided in AlephRLMConfig or if enable_checkpointing=True (which defaults to LangGraph MemorySaver).thread_id to invoke_rlm(...) to resume the same thread state across multiple calls, which is essential for debugging and multi-turn interactions.Aleph uses two distinct modes to provide context to sub-agents during sub-queries. Choosing the right mode depends on your context size and the complexity of the query.
Shared-session MCP (share_session=true):
http://127.0.0.1:8765/mcp) that exposes MCP tools like search_context, peek_context, and exec_python. The sub-query backend is configured to connect to this server.Prompt-embedded (share_session=false):
max_context_chars is 20,000).The sub_aleph tool runs a full Aleph loop inside another Aleph run. You can control the maximum allowed recursion depth using the ALEPH_MAX_DEPTH environment variable.
2 levels.ALEPH_MAX_DEPTH=3 allows one additional nested layer.export ALEPH_MAX_DEPTH=3To allow CLI sub-agents spawned via sub_query to access the same live Aleph session (including tools, contexts, and sandbox state), enable streamable HTTP sharing. This spins up a local HTTP endpoint that the nested CLI points to automatically.
Key configuration options for shared sessions:
--sub-query-backend: Set to codex for shared sessions.--sub-query-share-session: Set to true.--sub-query-codex-mode: Set to mcp to allow Aleph to talk to codex mcp-server instead of codex exec.--sub-query-codex-model: Specify the model (e.g., gpt-5.4).--sub-query-codex-reasoning-effort: Specify effort (e.g., low).Note: Tools are exposed under the server name aleph_shared to avoid conflicts with existing aleph entries.
{
"mcpServers": {
"aleph": {
"command": "aleph",
"args": [
"--enable-actions",
"--workspace-mode", "any",
"--tool-docs", "concise",
"--sub-query-backend", "codex",
"--sub-query-share-session", "true",
"--sub-query-timeout", "300",
"--sub-query-codex-mode", "mcp",
"--sub-query-codex-model", "gpt-5.4",
"--sub-query-codex-reasoning-effort", "low"
]
}
}
}The /aleph skill is an external memory workflow designed for handling large local data (codebases, large logs, etc.) without overwhelming the LLM prompt. The core principle is to keep whole contexts out of the prompt, returning only focused slices or compact derived results.
The workflow follows a 5-Phase Loop:
load_workspace_manifest for repos, load_file for single files, or load_context for inline content).search_context, peek_context, semantic_search, chunk_context, or rg_search.exec_python or built-in helpers (search, peek, lines, etc.). Store results in variables and retrieve them via get_variable.sub_query, sub_query_batch, sub_query_map, sub_aleph) to handle complex, multi-step reasoning.evaluate_progress, summarize_so_far, or finalize.The sub_query tool enables recursive reasoning by spawning independent sub-agents. You can configure which backend these agents use via the ALEPH_SUB_QUERY_BACKEND environment variable or CLI flags.
Available Backends:
codex: The recommended first-class backend for nested MCP sub-queries and shared-session recursion.api: A fallback for OpenAI-compatible endpoints.claude: A stable fallback for general sub-queries.gemini: An experimental override with live Aleph MCP access.kimi: An experimental override.auto: The default mode. It attempts to use codex if installed, otherwise falls back to api.Selection Precedence:
SubQueryConfig or configure).ALEPH_SUB_QUERY_BACKEND environment variable.codex -> api).export ALEPH_SUB_QUERY_BACKEND=api # Force API backend
export ALEPH_SUB_QUERY_BACKEND=claude # Force Claude CLI
export ALEPH_SUB_QUERY_BACKEND=codex # Force Codex CLI
export ALEPH_SUB_QUERY_BACKEND=gemini # Force Gemini CLI
export ALEPH_SUB_QUERY_BACKEND=kimi # Force Kimi CLI
export ALEPH_SUB_QUERY_BACKEND=auto # Return to auto selectionTo maintain effective RLM performance and avoid prompt bloating, avoid these common mistakes:
read_file for large files or repos; use load_workspace_manifest instead.search or compute instead.get_variable("ctx") as it is explicitly blocked.exec_python only returns print() output; it returns a full feedback object (stdout, stderr, etc.).Aleph uses a depth-based strategy to handle different data sizes and complexities. You can request a specific depth using the syntax /aleph N file where N is the depth.
| Depth | Strategy | Description |
|---|---|---|
| 1 | Direct Analysis | No sub-agents. Uses search, peek, or exec_python directly. Best for < 200K chars. |
| 2 | Parallel Fan-out | Uses sub_query_batch or sub_query_map over chunks. Best for 200K-2M chars. |
| 3 | Recursive (RLM^2) | Sub-agents use exec_python and sub_query internally. Best for 2M+ chars. |
| 4 | Deep Recursion (RLM^3) | Sub-agents spawn their own sub-agents. Best for massive datasets. |
Important: For depth 3 or higher, you must increase timeouts using configure(sub_query_timeout=300, sandbox_timeout=300) to prevent execution failures.
# Example of configuring timeouts for deep recursion
configure(sub_query_timeout=300, sandbox_timeout=300)Aleph implements context isolation to prevent large in-memory sessions from overwhelming the model's context window via Model Context Protocol (MCP) tool responses.
Key Constraints:
ctx) is kept server-side. Accessing it via get_variable("ctx") is explicitly blocked.10_000 characters (max_tool_response_chars). If a response exceeds this, it is appended with the truncation marker ... [TRUNCATED].peek_context, search_context, semantic_search, and diff_contexts—are bounded at the MCP boundary to ensure they do not return massive payloads.max_context_chars (defaulting to 20_000).Aleph provides different execution environments (REPLs) depending on your analysis needs:
exec_python for:numpy, scipy, sympy, networkx, etc.run_recipe_code.sub_query(...) or sub_aleph(...) synchronously.exec_javascript or exec_typescript for:await for recursion with await sub_query(...), await sub_query_batch(...), await sub_query_map(...), await sub_query_strict(...), or await sub_aleph(...).extract_emails, extract_routes), text utilities (grep_v, diff), collection helpers (group_by, frequency), and semantic_search.