Skip to content
Back to search

aleph

Skill + MCP server to turn your agent into an RLM. Load context, iterate with search/code/think tools, converge on answers.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hmbown--aleph/badge.svg)](/listings/hmbown--aleph)

HTML

<a href="/listings/hmbown--aleph"><img src="/api/listings/hmbown--aleph/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`](docs/prompts/aleph.md) into your client's command/skill folder — see [MCP_SETUP.md](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](MCP_SETUP.md#cursor).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "aleph-marketplace",
  4. "description": "Aleph MCP server plugin for recursive LLM reasoning over large local data",
  5. "owner": {
  6. "name": "Hunter Bown",
  7. "url": "https://github.com/Hmbown"
  8. },
  9. "plugins": [
  10. {
  11. "name": "aleph",
  12. "description": "External memory workflow for large local data — load, search, peek, execute, and recurse without consuming the context window.",
  13. "version": "0.8.9",
  14. "author": {
  15. "name": "Hunter Bown",
  16. "url": "https://github.com/Hmbown"
  17. },
  18. "source": "./plugins/aleph",
  19. "category": "productivity",
  20. "homepage": "https://github.com/Hmbown/aleph"
  21. }
  22. ]
  23. }
README.md · README · 355 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Aleph
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  3. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  4. [![PyPI version](https://img.shields.io/pypi/v/aleph-rlm.svg)](https://pypi.org/project/aleph-rlm/)
  5. Aleph is an [MCP server](https://modelcontextprotocol.io/) and skill for
  6. **Recursive Language Models** (RLMs). It keeps working state — search indexes,
  7. code execution, evidence, recursion — in a Python process outside the prompt
  8. window, so the LLM reasons iteratively over large codebases, long-lived
  9. projects, logs, documents, and data without burning context on raw content.
  10. ```text
  11. +-----------------+ tool calls +-----------------------------+
  12. | LLM client | ---------------> | Aleph (Python process) |
  13. | (context budget)| <--------------- | search / peek / exec / sub |
  14. +-----------------+ small results +-----------------------------+
  15. ```
  16. Why Aleph:
  17. - **Load once, reason many times.** Data lives in Aleph memory, not the prompt.
  18. - **Compute server-side.** `exec_python` runs code over the full context and
  19. returns only derived results. For JS/TS repos, `exec_javascript` and
  20. `exec_typescript` provide a persistent Node.js runtime over the same `ctx`.
  21. - **Recurse.** Sub-queries and recipes split complex work across multiple
  22. reasoning passes.
  23. - **Keep workspaces warm.** Bind contexts back to files or generated workspace
  24. manifests, refresh them, and resume long investigations later.
  25. ## Quick Start
  26. ```bash
  27. pip install "aleph-rlm[mcp]"
  28. aleph-rlm install --profile claude # or: codex, portable, api
  29. aleph-rlm doctor # verify everything is wired up
  30. ```
  31. Then restart your MCP client and confirm Aleph is available:
  32. ```text
  33. get_status()
  34. list_contexts()
  35. ```
  36. The optional `/aleph` (Claude Code) or `$aleph` (Codex) skill shortcut starts
  37. a structured RLM workflow. Install
  38. [`docs/prompts/aleph.md`](docs/prompts/aleph.md) into your client's
  39. command/skill folder — see [MCP_SETUP.md](MCP_SETUP.md) for exact paths.
  40. If you are using action tools on a real repo, the safest default is:
  41. ```bash
  42. aleph --enable-actions --action-policy read-only
  43. ```
  44. ### Cursor
  45. Use **global** MCP (`aleph-rlm install cursor`) for `--workspace-mode any`, or
  46. **project** MCP (`aleph-rlm install cursor-project` from the repo) for
  47. `${workspaceFolder}` + `--workspace-mode fixed`. Chat, Composer, and the Cursor
  48. CLI share that MCP config; a Cursor extension is optional and not required for
  49. Aleph — see [MCP_SETUP.md](MCP_SETUP.md#cursor).
  50. ## Entry Points
  51. | Command | Module | What it does |
  52. |---------|--------|--------------|
  53. | `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. |
  54. | `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). |
  55. ## Install Profiles
  56. `aleph-rlm install` asks which sub-query profile to use. Profiles configure
  57. the nested backend that `sub_query` and `sub_query_batch` spawn for recursive
  58. reasoning.
  59. | Profile | What it pins |
  60. |---------|-------------|
  61. | `portable` | No nested backend — you choose later or rely on auto-detection |
  62. | `claude` | Claude CLI: `--model opus`, `--effort low`, shared session enabled |
  63. | `codex` | Codex MCP: `gpt-5.4`, low reasoning effort, shared session enabled |
  64. | `api` | OpenAI-compatible API — set `ALEPH_SUB_QUERY_API_KEY` and `ALEPH_SUB_QUERY_MODEL` |
  65. ```bash
  66. aleph-rlm install claude-code --profile claude
  67. aleph-rlm configure --profile codex # overwrite existing config
  68. ```
  69. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all env vars, CLI
  70. flags, and runtime `configure(...)` options.
  71. ## Large Codebase Workflow
  72. If your main use case is a repo or multi-folder project, start by loading a
  73. compact workspace manifest instead of throwing raw source files into the model
  74. window. That gives the model a map of the project, lets it search aggressively,
  75. and keeps the session refreshable as the repo changes.
  76. ```python
  77. load_workspace_manifest(paths=["src", "tests"], context_id="repo")
  78. rg_search(pattern="FastAPI|APIRouter|router\\.", paths=["src", "tests"], load_context_id="routes")
  79. load_file(path="pyproject.toml", context_id="pyproject")
  80. exec_python(code="""
  81. files = [line for line in ctx.splitlines() if line.startswith("- ")]
  82. summary = {
  83. "indexed_entries": len(files),
  84. "top_python_files": [line for line in files if "| python |" in line][:10],
  85. }
  86. """, context_id="repo")
  87. get_variable(name="summary", context_id="repo")
  88. refresh_context(context_id="repo")
  89. ```
  90. Use `load_workspace_manifest` as the default front door for large codebases and
  91. projects. Then pull in specific files with `load_file`, search the repo with
  92. `rg_search`, and refresh the bound context when the workspace changes. Refreshes
  93. preserve the session's reasoning state, evidence log, and tracked tasks.
  94. ### Single File Workflow
  95. Aleph is also strong when you load one large file once, do the heavy work
  96. inside Aleph, and only pull back compact answers.
  97. ```python
  98. load_file(path="/absolute/path/to/large_file.log", context_id="doc")
  99. search_context(pattern="ERROR|WARN", context_id="doc")
  100. peek_context(start=1, end=60, unit="lines", context_id="doc")
  101. exec_python(code="""
  102. errors = [line for line in ctx.splitlines() if "error" in line.lower()]
  103. result = {
  104. "error_count": len(errors),
  105. "first_error": errors[0] if errors else None,
  106. }
  107. """, context_id="doc")
  108. get_variable(name="result", context_id="doc")
  109. save_session(context_id="doc", path=".aleph/doc.json")
  110. ```
  111. The important habit is to compute server-side. Do not treat `get_variable("ctx")`
  112. as the default path. Search, filter, chunk, or summarize first, then retrieve a
  113. small result.
  114. If you want terminal-only mode instead of MCP, use:
  115. ```bash
  116. aleph run "Summarize this log" --provider cli --model codex --context-file app.log
  117. ```
  118. ## Local Models (llama.cpp)
  119. Aleph can use a local model instead of a cloud API. This runs the full RLM
  120. loop — search, code execution, convergence — entirely on your machine with
  121. zero API cost.
  122. **Prerequisites:** [llama.cpp](https://github.com/ggml-org/llama.cpp) and a
  123. GGUF model file.
  124. ```bash
  125. # Install llama.cpp
  126. brew install llama.cpp # Mac
  127. winget install ggml.LlamaCpp # Windows
  128. # Start the server with your model
  129. llama-server -m /path/to/model.gguf -c 16384 -ngl 99 --port 8080
  130. ```
  131. Point Aleph at the running server:
  132. ```bash
  133. export ALEPH_PROVIDER=llamacpp
  134. export ALEPH_LLAMACPP_URL=http://127.0.0.1:8080
  135. export ALEPH_MODEL=local
  136. aleph
  137. ```
  138. Or let Aleph start the server automatically:
  139. ```bash
  140. export ALEPH_PROVIDER=llamacpp
  141. export ALEPH_LLAMACPP_MODEL=/path/to/model.gguf
  142. export ALEPH_LLAMACPP_CTX=16384
  143. export ALEPH_MODEL=local
  144. aleph
  145. ```
  146. Tested with Qwen 3.5 9B (Q8_0, ~9 GB). Any GGUF model works — larger models
  147. give better results in the RLM loop. Models with reasoning/thinking support
  148. (Qwen 3.5, QwQ, etc.) are handled automatically. See
  149. [CONFIGURATION.md](docs/CONFIGURATION.md) for all `ALEPH_LLAMACPP_*`
  150. variables.
  151. ## Common Workloads
  152. | Scenario | What Aleph Is Good At |
  153. |---|---|
  154. | Large codebase / project analysis | Build a workspace map, search quickly, load only the files that matter, and keep the session refreshable |
  155. | Large log analysis | Load big files, trace patterns, correlate events |
  156. | Codebase navigation | Search symbols, inspect routes, trace behavior |
  157. | Data exploration | Analyze JSON, CSV, and mixed text with Python helpers |
  158. | Long document review | Load PDFs, Word docs, HTML, and compressed logs |
  159. | Recursive investigations | Split work into sub-queries instead of one giant prompt |
  160. | Long-running sessions | Save and resume memory packs across sessions |
  161. ## Core Tools
  162. | Category | Primary tools | What they do |
  163. |---|---|---|
  164. | Load context | `load_context`, `load_file`, `load_workspace_manifest`, `refresh_context`, `list_contexts`, `diff_contexts` | Put data into Aleph memory, bind it back to workspace assets, and inspect what is loaded |
  165. | Navigate | `search_context`, `semantic_search`, `peek_context`, `chunk_context`, `rg_search` | Find the relevant slice before asking for an answer |
  166. | Compute | `exec_python`, `exec_javascript`, `exec_typescript`, `get_variable` | Run Python or JS/TS over the full context and retrieve only the derived result |
  167. | Reason | `think`, `evaluate_progress`, `get_evidence`, `finalize` | Structure progress and close out with evidence |
  168. | Orchestrate | `configure`, `validate_recipe`, `estimate_recipe`, `run_recipe`, `run_recipe_code` | Switch backends and automate repeated reasoning patterns |
  169. | Persist | `save_session`, `load_session` | Keep long investigations outside the prompt window |
  170. ## Python vs JS/TS REPL
  171. Aleph's **primary control layer is still Python**. `exec_python` remains the
  172. default REPL for general-purpose analysis, recipes, and orchestration.
  173. - Use `exec_python` when you need the full Aleph surface area: Python-first
  174. prompts, Python's numeric / symbolic stack (`cmath`, `mpmath`, `decimal`,
  175. `fractions`, `statistics`, `numpy`, `scipy`, `sympy`, `networkx`), or
  176. recipe execution via `run_recipe_code`.
  177. - Use `exec_javascript` / `exec_typescript` when the target repo or analysis is
  178. naturally JS/TS-shaped and you want persistent Node state, JS-native array /
  179. object manipulation, or async recursion with `await`.
  180. - `exec_python`
  181. Full Aleph helper surface, including recipe DSL helpers, synchronous
  182. `sub_query(...)` / `sub_aleph(...)`, and the widest compatibility with
  183. existing prompts and workflows.
  184. - `exec_javascript` / `exec_typescript`
  185. Persistent Node.js runtime per context for JS/TS-heavy repos. Shares the same
  186. `ctx`, supports top-level `await`, and can recurse with async
  187. `await sub_query(...)`, `await sub_query_batch(...)`,
  188. `await sub_query_map(...)`, `await sub_query_strict(...)`, and
  189. `await sub_aleph(...)`. Also includes the recipe DSL (`Recipe`, `Search`,
  190. `Take`, etc.) for building recipe payloads in JS/TS.
  191. The JS/TS runtime also ships with a broader local helper set than the first
  192. handoff slice: search/peek/lines/chunk, extraction helpers (`extract_emails`,
  193. `extract_todos`, `extract_routes`, etc.), text utilities (`number_lines`,
  194. `grep_v`, `sort_lines`, `normalize_whitespace`, etc.), text comparison helpers
  195. (`diff`, `similarity`, `common_lines`, `diff_lines`), collection helpers
  196. (`flatten`, `group_by`, `frequency`, `sample_items`, `shuffle_items`, etc.),
  197. validation helpers (`is_json`, `is_email`, `is_uuid`, etc.), CSV / JSON
  198. converters, and `semantic_search`.
  199. The JS/TS runtime now also includes the Recipe DSL: `RecipeStep`,
  200. `RecipeBuilder`, and all step constructors (`Recipe`, `Search`, `Peek`,
  201. `Lines`, `Take`, `Chunk`, `Filter`, `MapSubQuery`, `SubQuery`, `Aggregate`,
  202. `Assign`, `Load`, `Finalize`, `as_recipe`). You can build recipes with
  203. fluent chaining or pipe-style:
  204. ```javascript
  205. // Fluent style
  206. Recipe("doc").search("ERROR").take(5).finalize().compile()
  207. // Pipe style
  208. Recipe("doc").pipe(Search("ERROR")).pipe(Take(5)).pipe(Finalize()).compile()
  209. ```
  210. The `compile_recipe` and `run_recipe_code` MCP tools accept a `language`
  211. parameter (`"python"`, `"javascript"`, `"typescript"`) to compile recipe DSL
  212. code in the corresponding runtime.
  213. What still differs from Python:
  214. - Python is still the default and best-supported Aleph REPL.
  215. - JS/TS recursion helpers are async and require `await`.
  216. - Recipe *execution* (`run_recipe`) always uses the Python runtime. The JS/TS
  217. path covers recipe *building and compilation* only.
  218. - JS uses `RecipeBuilder.pipe()` / fluent methods instead of Python's `|`
  219. operator (JS `|` is bitwise OR, not overloadable for this purpose).
  220. - Python's import ecosystem remains Python-only. The Node runtime is helper-led:
  221. no `require`, no `process`, no `module`, and no npm package loading inside
  222. the sandbox.
  223. - `exec_typescript` strips type syntax for execution; it is not a full TS
  224. compiler, typechecker, or `ts-node` environment.
  225. - Regex flag behavior follows each runtime: Python helpers use Python `re`
  226. flags, while JS/TS helpers use JavaScript regex flag strings.
  227. Example JS/TS workflow:
  228. ```python
  229. exec_typescript(code=`
  230. const routes: string[] = extract_routes('javascript').map((item) => item.value);
  231. const routeKinds = frequency(
  232. routes.map((route) => (route.includes('.post(') ? 'write' : 'read')),
  233. 2,
  234. );
  235. const notes = await sub_query_map(
  236. routes.map((route) => `Explain ${route}`),
  237. routes,
  238. );
  239. ({ routeCount: routes.length, routeKinds, notes })
  240. `, context_id="repo")
  241. ```
  242. ## Safety Model
  243. Aleph is built to keep raw context out of the model window unless you
  244. explicitly pull it back:
  245. - Tool responses are capped and truncated.
  246. - `get_variable("ctx")` is policy-aware and should not be your default path.
  247. - `exec_python` stdout, stderr, and return values are bounded independently.
  248. - `ALEPH_CONTEXT_POLICY=isolated` adds stricter session export/import rules and
  249. more defensive defaults.
  250. - `ALEPH_ACTION_POLICY=read-only` (or `--action-policy read-only`) keeps action
  251. tools in read-only mode: search and file loading still work, but writes and
  252. subprocess execution are blocked.
  253. The safest pattern is always:
  254. 1. Load the large context into Aleph memory.
  255. 2. Search or compute inside Aleph.
  256. 3. Retrieve only the small result you need.
  257. ## Docs Map
  258. - [MCP_SETUP.md](MCP_SETUP.md): client-by-client MCP and skill installation.
  259. - [docs/prompts/aleph.md](docs/prompts/aleph.md): the `/aleph` and `$aleph`
  260. workflow plus tool patterns.
  261. - [docs/CONFIGURATION.md](docs/CONFIGURATION.md): flags, env vars, limits, and
  262. safety settings.
  263. - [docs/langgraph-rlm-default.md](docs/langgraph-rlm-default.md): LangGraph
  264. integration with Aleph-style tool usage.
  265. - [examples/langgraph_rlm_repo_improver.py](examples/langgraph_rlm_repo_improver.py):
  266. repo improvement example with optional LangSmith tracing.
  267. - [CHANGELOG.md](CHANGELOG.md): release history.
  268. - [DEVELOPMENT.md](DEVELOPMENT.md): contributor guide.
  269. ## Development
  270. ```bash
  271. git clone https://github.com/Hmbown/aleph.git
  272. cd aleph
  273. pip install -e ".[dev,mcp]"
  274. # Optional extras:
  275. # .[docs] -> MarkItDown-backed document conversion
  276. # .[observability] -> OpenTelemetry spans
  277. pytest tests/ -v
  278. ruff check aleph/ tests/
  279. ```
  280. ## References
  281. - Zhang, A. L., Kraska, T., Khattab, O. (2025)
  282. [Recursive Language Models (arXiv:2512.24601)](https://arxiv.org/abs/2512.24601)
  283. ## License
  284. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.