Aleph

Aleph 是一个用于递归语言模型 (RLMs) 的 MCP 服务器 和技能。它将工作状态（搜索索引、代码执行、证据、递归）保存在提示词窗口之外的 Python 进程中，因此 LLM 可以在大型代码库、长期项目、日志、文档和数据上进行迭代推理，而不会因原始内容而耗尽上下文。

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

为什么选择 Aleph：

• 加载一次，多次推理。 数据存在 Aleph 内存中，而不是提示词中。

• 服务器端计算。 exec_python 在完整上下文上运行代码，并仅返回派生结果。对于 JS/TS 仓库，exec_javascript 和 exec_typescript 在相同的 ctx 上提供持久的 Node.js 运行时。

• 递归。 子查询和配方（recipes）将复杂工作拆分到多个推理步骤中。

• 保持工作区活跃。 将上下文绑定回文件或生成的工作区清单，刷新它们，并在稍后恢复长时间的调查。

快速开始

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

然后重启你的 MCP 客户端并确认 Aleph 可用：

get_status()
list_contexts()

可选的 /aleph (Claude Code) 或 $aleph (Codex) 技能快捷方式会启动一个结构化的 RLM 工作流。将 docs/prompts/aleph.md 安装到你客户端的命令/技能文件夹中 — 确切路径请参阅 MCP_SETUP.md。

如果你正在真实仓库上使用操作工具，最安全的默认设置是：

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

Cursor

使用 全局 MCP (aleph-rlm install cursor) 以实现 --workspace-mode any，或者使用 项目 MCP（从仓库运行 aleph-rlm install cursor-project）以实现 ${workspaceFolder} + --workspace-mode fixed。Chat、Composer 和 Cursor CLI 共享该 MCP 配置；Cursor 扩展是可选的，Aleph 不需要它 — 详见 MCP_SETUP.md。

入口点

安装配置文件

aleph-rlm install 会询问使用哪个子查询配置文件。配置文件配置了 sub_query 和 sub_query_batch 为递归推理所生成的嵌套后端。

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

有关所有环境变量、CLI 标志和运行时 configure(...) 选项，请参阅 docs/CONFIGURATION.md。

大型代码库工作流

如果你的主要用例是仓库或多文件夹项目，请从加载紧凑的工作区清单开始，而不是将原始源文件扔进模型窗口。这为模型提供了项目地图，使其能够积极搜索，并在仓库更改时保持会话可刷新。

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")

将 load_workspace_manifest 作为大型代码库和项目的默认入口。然后使用 load_file 拉取特定文件，使用 rg_search 搜索仓库，并在工作区更改时刷新绑定的上下文。刷新会保留会话的推理状态、证据日志和跟踪任务。

单文件工作流

当一次加载一个大文件，在 Aleph 内部完成繁重工作，并仅拉回紧凑答案时，Aleph 也非常强大。

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")

重要的习惯是在服务器端进行计算。不要将 get_variable("ctx") 视为默认路径。先搜索、过滤、分块或总结，然后检索一个小结果。

如果你想要终端模式而不是 MCP，请使用：

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

本地模型 (llama.cpp)

Aleph 可以使用本地模型代替云 API。这会在你的机器上完全运行 RLM 循环（搜索、代码执行、收敛），且零 API 成本。

先决条件： llama.cpp 和一个 GGUF 模型文件。

# 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

将 Aleph 指向正在运行的服务器：

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

或者让 Aleph 自动启动服务器：

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

已使用 Qwen 3.5 9B (Q8_0, ~9 GB) 进行测试。任何 GGUF 模型均可工作 — 更大的模型在 RLM 循环中效果更好。支持推理/思考的模型（Qwen 3.5, QwQ 等）会自动处理。有关所有 ALEPH_LLAMACPP_* 变量，请参阅 CONFIGURATION.md。

常见工作负载

核心工具

Python 与 JS/TS REPL

Aleph 的 主要控制层仍然是 Python。exec_python 仍然是通用分析、配方和编排的默认 REPL。

• 当你需要完整的 Aleph 表面积时，请使用 exec_python：Python 优先的提示词、Python 的数值/符号栈 (cmath, mpmath, decimal, fractions, statistics, numpy, scipy, sympy, networkx)，或通过 run_recipe_code 执行配方。

• 当目标仓库或分析本质上是 JS/TS 风格，且你想要持久的 Node 状态、JS 原生数组/对象操作或带有 await 的异步递归时，请使用 exec_javascript / exec_typescript。

• exec_python 完整的 Aleph 辅助表面，包括配方 DSL 辅助工具、同步 sub_query(...) / sub_aleph(...)，以及与现有提示词和工作流的最广泛兼容性。

• exec_javascript / exec_typescript 每个上下文的持久 Node.js 运行时，适用于 JS/TS 重型仓库。共享相同的 ctx，支持顶层 await，并可以使用异步 await sub_query(...), await sub_query_batch(...), await sub_query_map(...), await sub_query_strict(...) 和 await sub_aleph(...) 进行递归。还包括用于在 JS/TS 中构建配方负载的配方 DSL (Recipe, Search, Take 等)。

JS/TS 运行时还附带了比初始移交片段更广泛的本地辅助工具集：搜索/查看/行/分块、提取辅助工具 (extract_emails, extract_todos, extract_routes 等)、文本工具 (number_lines, grep_v, sort_lines, normalize_whitespace 等)、文本比较辅助工具 (diff, similarity, common_lines, diff_lines)、集合辅助工具 (flatten, group_by, frequency, sample_items, shuffle_items 等)、验证辅助工具 (is_json, is_email, is_uuid 等)、CSV/JSON 转换器和 semantic_search。

JS/TS 运行时现在还包括配方 DSL：RecipeStep, RecipeBuilder 以及所有步骤构造函数 (Recipe, Search, Peek, Lines, Take, Chunk, Filter, MapSubQuery, SubQuery, Aggregate, Assign, Load, Finalize, as_recipe)。你可以使用流式链式调用或管道风格构建配方：

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

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

compile_recipe 和 run_recipe_code MCP 工具接受一个 language 参数 ("python", "javascript", "typescript") 以在相应的运行时中编译配方 DSL 代码。

与 Python 的区别：

• Python 仍然是默认且支持最好的 Aleph REPL。

• JS/TS 递归辅助工具是异步的，需要 await。

• 配方 执行 (run_recipe) 始终使用 Python 运行时。JS/TS 路径仅涵盖配方 构建和编译。

• JS 使用 RecipeBuilder.pipe() / 流式方法，而不是 Python 的 | 运算符（JS 中的 | 是按位或，不能为此目的重载）。

• Python 的导入生态系统仍然仅限 Python。Node 运行时是辅助工具驱动的：沙箱内没有 require，没有 process，没有 module，也没有 npm 包加载。

• exec_typescript 会剥离类型语法以进行执行；它不是一个完整的 TS 编译器、类型检查器或 ts-node 环境。

• 正则表达式标志行为遵循每个运行时：Python 辅助工具使用 Python re 标志，而 JS/TS 辅助工具使用 JavaScript 正则表达式标志字符串。

JS/TS 工作流示例：

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")

安全模型

Aleph 的构建旨在将原始上下文排除在模型窗口之外，除非你明确将其拉回：

• 工具响应被限制和截断。

• get_variable("ctx") 是策略感知的，不应作为你的默认路径。

• exec_python 的 stdout、stderr 和返回值是独立限制的。

• ALEPH_CONTEXT_POLICY=isolated 增加了更严格的会话导出/导入规则和更防御性的默认设置。

• ALEPH_ACTION_POLICY=read-only (或 --action-policy read-only) 将操作工具保持在只读模式：搜索和文件加载仍然有效，但写入和子进程执行被阻止。

最安全的模式始终是：

1. 将大型上下文加载到 Aleph 内存中。

2. 在 Aleph 内部搜索或计算。

3. 仅检索你需要的那个小结果。

文档地图

• MCP_SETUP.md: 各客户端的 MCP 和技能安装。

• docs/prompts/aleph.md: /aleph 和 $aleph 工作流以及工具模式。

• docs/CONFIGURATION.md: 标志、环境变量、限制和安全设置。

• docs/langgraph-rlm-default.md: LangGraph 与 Aleph 风格工具使用的集成。

• examples/langgraph_rlm_repo_improver.py: 带有可选 LangSmith 追踪的仓库改进示例。

• CHANGELOG.md: 发布历史。

• DEVELOPMENT.md: 贡献者指南。

开发

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/

参考

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

许可证

MIT