{"id":39200598,"url":"https://github.com/hmbown/aleph","last_synced_at":"2026-04-12T01:16:54.262Z","repository":{"id":328857321,"uuid":"1117061614","full_name":"Hmbown/aleph","owner":"Hmbown","description":"MCP server for recursive LLM reasoning. Load context, iterate with search/code/think tools, converge on answers.","archived":false,"fork":false,"pushed_at":"2026-01-17T02:06:34.000Z","size":7125,"stargazers_count":63,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-18T07:37:52.391Z","etag":null,"topics":["llm","mcp","recursive","repl","rlm"],"latest_commit_sha":null,"homepage":"https://aleph-web.pages.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hmbown.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T19:20:02.000Z","updated_at":"2026-01-18T05:14:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Hmbown/aleph","commit_stats":null,"previous_names":["hmbown/aleph"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Hmbown/aleph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2Faleph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2Faleph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2Faleph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2Faleph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hmbown","download_url":"https://codeload.github.com/Hmbown/aleph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2Faleph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28597985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T02:08:49.799Z","status":"ssl_error","status_checked_at":"2026-01-20T02:08:44.148Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["llm","mcp","recursive","repl","rlm"],"created_at":"2026-01-17T22:54:33.175Z","updated_at":"2026-04-12T01:16:54.234Z","avatar_url":"https://github.com/Hmbown.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aleph\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI version](https://img.shields.io/pypi/v/aleph-rlm.svg)](https://pypi.org/project/aleph-rlm/)\n\nAleph is an [MCP server](https://modelcontextprotocol.io/) and skill for\n**Recursive Language Models** (RLMs). It keeps working state — search indexes,\ncode execution, evidence, recursion — in a Python process outside the prompt\nwindow, so the LLM reasons iteratively over large codebases, long-lived\nprojects, logs, documents, and data without burning context on raw content.\n\n```text\n+-----------------+    tool calls     +-----------------------------+\n|   LLM client    | ---------------\u003e |  Aleph (Python process)     |\n| (context budget)| \u003c--------------- |  search / peek / exec / sub |\n+-----------------+   small results  +-----------------------------+\n```\n\nWhy Aleph:\n\n- **Load once, reason many times.** Data lives in Aleph memory, not the prompt.\n- **Compute server-side.** `exec_python` runs code over the full context and\n  returns only derived results. For JS/TS repos, `exec_javascript` and\n  `exec_typescript` provide a persistent Node.js runtime over the same `ctx`.\n- **Recurse.** Sub-queries and recipes split complex work across multiple\n  reasoning passes.\n- **Keep workspaces warm.** Bind contexts back to files or generated workspace\n  manifests, refresh them, and resume long investigations later.\n\n## Quick Start\n\n```bash\npip install \"aleph-rlm[mcp]\"\naleph-rlm install --profile claude   # or: codex, portable, api\naleph-rlm doctor                     # verify everything is wired up\n```\n\nThen restart your MCP client and confirm Aleph is available:\n\n```text\nget_status()\nlist_contexts()\n```\n\nThe optional `/aleph` (Claude Code) or `$aleph` (Codex) skill shortcut starts\na structured RLM workflow. Install\n[`docs/prompts/aleph.md`](docs/prompts/aleph.md) into your client's\ncommand/skill folder — see [MCP_SETUP.md](MCP_SETUP.md) for exact paths.\n\nIf you are using action tools on a real repo, the safest default is:\n\n```bash\naleph --enable-actions --action-policy read-only\n```\n\n### Cursor\n\nUse **global** MCP (`aleph-rlm install cursor`) for `--workspace-mode any`, or\n**project** MCP (`aleph-rlm install cursor-project` from the repo) for\n`${workspaceFolder}` + `--workspace-mode fixed`. Chat, Composer, and the Cursor\nCLI share that MCP config; a Cursor extension is optional and not required for\nAleph — see [MCP_SETUP.md](MCP_SETUP.md#cursor).\n\n## Entry Points\n\n| Command | Module | What it does |\n|---------|--------|--------------|\n| `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. |\n| `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). |\n\n## Install Profiles\n\n`aleph-rlm install` asks which sub-query profile to use. Profiles configure\nthe nested backend that `sub_query` and `sub_query_batch` spawn for recursive\nreasoning.\n\n| Profile | What it pins |\n|---------|-------------|\n| `portable` | No nested backend — you choose later or rely on auto-detection |\n| `claude` | Claude CLI: `--model opus`, `--effort low`, shared session enabled |\n| `codex` | Codex MCP: `gpt-5.4`, low reasoning effort, shared session enabled |\n| `api` | OpenAI-compatible API — set `ALEPH_SUB_QUERY_API_KEY` and `ALEPH_SUB_QUERY_MODEL` |\n\n```bash\naleph-rlm install claude-code --profile claude\naleph-rlm configure --profile codex   # overwrite existing config\n```\n\nSee [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all env vars, CLI\nflags, and runtime `configure(...)` options.\n\n## Large Codebase Workflow\n\nIf your main use case is a repo or multi-folder project, start by loading a\ncompact workspace manifest instead of throwing raw source files into the model\nwindow. That gives the model a map of the project, lets it search aggressively,\nand keeps the session refreshable as the repo changes.\n\n```python\nload_workspace_manifest(paths=[\"src\", \"tests\"], context_id=\"repo\")\nrg_search(pattern=\"FastAPI|APIRouter|router\\\\.\", paths=[\"src\", \"tests\"], load_context_id=\"routes\")\nload_file(path=\"pyproject.toml\", context_id=\"pyproject\")\nexec_python(code=\"\"\"\nfiles = [line for line in ctx.splitlines() if line.startswith(\"- \")]\nsummary = {\n    \"indexed_entries\": len(files),\n    \"top_python_files\": [line for line in files if \"| python |\" in line][:10],\n}\n\"\"\", context_id=\"repo\")\nget_variable(name=\"summary\", context_id=\"repo\")\nrefresh_context(context_id=\"repo\")\n```\n\nUse `load_workspace_manifest` as the default front door for large codebases and\nprojects. Then pull in specific files with `load_file`, search the repo with\n`rg_search`, and refresh the bound context when the workspace changes. Refreshes\npreserve the session's reasoning state, evidence log, and tracked tasks.\n\n### Single File Workflow\n\nAleph is also strong when you load one large file once, do the heavy work\ninside Aleph, and only pull back compact answers.\n\n```python\nload_file(path=\"/absolute/path/to/large_file.log\", context_id=\"doc\")\nsearch_context(pattern=\"ERROR|WARN\", context_id=\"doc\")\npeek_context(start=1, end=60, unit=\"lines\", context_id=\"doc\")\nexec_python(code=\"\"\"\nerrors = [line for line in ctx.splitlines() if \"error\" in line.lower()]\nresult = {\n    \"error_count\": len(errors),\n    \"first_error\": errors[0] if errors else None,\n}\n\"\"\", context_id=\"doc\")\nget_variable(name=\"result\", context_id=\"doc\")\nsave_session(context_id=\"doc\", path=\".aleph/doc.json\")\n```\n\nThe important habit is to compute server-side. Do not treat `get_variable(\"ctx\")`\nas the default path. Search, filter, chunk, or summarize first, then retrieve a\nsmall result.\n\nIf you want terminal-only mode instead of MCP, use:\n\n```bash\naleph run \"Summarize this log\" --provider cli --model codex --context-file app.log\n```\n\n## Local Models (llama.cpp)\n\nAleph can use a local model instead of a cloud API. This runs the full RLM\nloop — search, code execution, convergence — entirely on your machine with\nzero API cost.\n\n**Prerequisites:** [llama.cpp](https://github.com/ggml-org/llama.cpp) and a\nGGUF model file.\n\n```bash\n# Install llama.cpp\nbrew install llama.cpp          # Mac\nwinget install ggml.LlamaCpp    # Windows\n\n# Start the server with your model\nllama-server -m /path/to/model.gguf -c 16384 -ngl 99 --port 8080\n```\n\nPoint Aleph at the running server:\n\n```bash\nexport ALEPH_PROVIDER=llamacpp\nexport ALEPH_LLAMACPP_URL=http://127.0.0.1:8080\nexport ALEPH_MODEL=local\naleph\n```\n\nOr let Aleph start the server automatically:\n\n```bash\nexport ALEPH_PROVIDER=llamacpp\nexport ALEPH_LLAMACPP_MODEL=/path/to/model.gguf\nexport ALEPH_LLAMACPP_CTX=16384\nexport ALEPH_MODEL=local\naleph\n```\n\nTested with Qwen 3.5 9B (Q8_0, ~9 GB). Any GGUF model works — larger models\ngive better results in the RLM loop. Models with reasoning/thinking support\n(Qwen 3.5, QwQ, etc.) are handled automatically. See\n[CONFIGURATION.md](docs/CONFIGURATION.md) for all `ALEPH_LLAMACPP_*`\nvariables.\n\n## Common Workloads\n\n| Scenario | What Aleph Is Good At |\n|---|---|\n| Large codebase / project analysis | Build a workspace map, search quickly, load only the files that matter, and keep the session refreshable |\n| Large log analysis | Load big files, trace patterns, correlate events |\n| Codebase navigation | Search symbols, inspect routes, trace behavior |\n| Data exploration | Analyze JSON, CSV, and mixed text with Python helpers |\n| Long document review | Load PDFs, Word docs, HTML, and compressed logs |\n| Recursive investigations | Split work into sub-queries instead of one giant prompt |\n| Long-running sessions | Save and resume memory packs across sessions |\n\n## Core Tools\n\n| Category | Primary tools | What they do |\n|---|---|---|\n| 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 |\n| Navigate | `search_context`, `semantic_search`, `peek_context`, `chunk_context`, `rg_search` | Find the relevant slice before asking for an answer |\n| Compute | `exec_python`, `exec_javascript`, `exec_typescript`, `get_variable` | Run Python or JS/TS over the full context and retrieve only the derived result |\n| Reason | `think`, `evaluate_progress`, `get_evidence`, `finalize` | Structure progress and close out with evidence |\n| Orchestrate | `configure`, `validate_recipe`, `estimate_recipe`, `run_recipe`, `run_recipe_code` | Switch backends and automate repeated reasoning patterns |\n| Persist | `save_session`, `load_session` | Keep long investigations outside the prompt window |\n\n## Python vs JS/TS REPL\n\nAleph's **primary control layer is still Python**. `exec_python` remains the\ndefault REPL for general-purpose analysis, recipes, and orchestration.\n\n- Use `exec_python` when you need the full Aleph surface area: Python-first\n  prompts, Python's numeric / symbolic stack (`cmath`, `mpmath`, `decimal`,\n  `fractions`, `statistics`, `numpy`, `scipy`, `sympy`, `networkx`), or\n  recipe execution via `run_recipe_code`.\n- Use `exec_javascript` / `exec_typescript` when the target repo or analysis is\n  naturally JS/TS-shaped and you want persistent Node state, JS-native array /\n  object manipulation, or async recursion with `await`.\n\n- `exec_python`\n  Full Aleph helper surface, including recipe DSL helpers, synchronous\n  `sub_query(...)` / `sub_aleph(...)`, and the widest compatibility with\n  existing prompts and workflows.\n- `exec_javascript` / `exec_typescript`\n  Persistent Node.js runtime per context for JS/TS-heavy repos. Shares the same\n  `ctx`, supports top-level `await`, and can recurse with async\n  `await sub_query(...)`, `await sub_query_batch(...)`,\n  `await sub_query_map(...)`, `await sub_query_strict(...)`, and\n  `await sub_aleph(...)`. Also includes the recipe DSL (`Recipe`, `Search`,\n  `Take`, etc.) for building recipe payloads in JS/TS.\n\nThe JS/TS runtime also ships with a broader local helper set than the first\nhandoff slice: search/peek/lines/chunk, extraction helpers (`extract_emails`,\n`extract_todos`, `extract_routes`, etc.), text utilities (`number_lines`,\n`grep_v`, `sort_lines`, `normalize_whitespace`, etc.), text comparison helpers\n(`diff`, `similarity`, `common_lines`, `diff_lines`), collection helpers\n(`flatten`, `group_by`, `frequency`, `sample_items`, `shuffle_items`, etc.),\nvalidation helpers (`is_json`, `is_email`, `is_uuid`, etc.), CSV / JSON\nconverters, and `semantic_search`.\n\nThe JS/TS runtime now also includes the Recipe DSL: `RecipeStep`,\n`RecipeBuilder`, and all step constructors (`Recipe`, `Search`, `Peek`,\n`Lines`, `Take`, `Chunk`, `Filter`, `MapSubQuery`, `SubQuery`, `Aggregate`,\n`Assign`, `Load`, `Finalize`, `as_recipe`). You can build recipes with\nfluent chaining or pipe-style:\n\n```javascript\n// Fluent style\nRecipe(\"doc\").search(\"ERROR\").take(5).finalize().compile()\n\n// Pipe style\nRecipe(\"doc\").pipe(Search(\"ERROR\")).pipe(Take(5)).pipe(Finalize()).compile()\n```\n\nThe `compile_recipe` and `run_recipe_code` MCP tools accept a `language`\nparameter (`\"python\"`, `\"javascript\"`, `\"typescript\"`) to compile recipe DSL\ncode in the corresponding runtime.\n\nWhat still differs from Python:\n\n- Python is still the default and best-supported Aleph REPL.\n- JS/TS recursion helpers are async and require `await`.\n- Recipe *execution* (`run_recipe`) always uses the Python runtime. The JS/TS\n  path covers recipe *building and compilation* only.\n- JS uses `RecipeBuilder.pipe()` / fluent methods instead of Python's `|`\n  operator (JS `|` is bitwise OR, not overloadable for this purpose).\n- Python's import ecosystem remains Python-only. The Node runtime is helper-led:\n  no `require`, no `process`, no `module`, and no npm package loading inside\n  the sandbox.\n- `exec_typescript` strips type syntax for execution; it is not a full TS\n  compiler, typechecker, or `ts-node` environment.\n- Regex flag behavior follows each runtime: Python helpers use Python `re`\n  flags, while JS/TS helpers use JavaScript regex flag strings.\n\nExample JS/TS workflow:\n\n```python\nexec_typescript(code=`\nconst routes: string[] = extract_routes('javascript').map((item) =\u003e item.value);\nconst routeKinds = frequency(\n  routes.map((route) =\u003e (route.includes('.post(') ? 'write' : 'read')),\n  2,\n);\nconst notes = await sub_query_map(\n  routes.map((route) =\u003e `Explain ${route}`),\n  routes,\n);\n({ routeCount: routes.length, routeKinds, notes })\n`, context_id=\"repo\")\n```\n\n## Safety Model\n\nAleph is built to keep raw context out of the model window unless you\nexplicitly pull it back:\n\n- Tool responses are capped and truncated.\n- `get_variable(\"ctx\")` is policy-aware and should not be your default path.\n- `exec_python` stdout, stderr, and return values are bounded independently.\n- `ALEPH_CONTEXT_POLICY=isolated` adds stricter session export/import rules and\n  more defensive defaults.\n- `ALEPH_ACTION_POLICY=read-only` (or `--action-policy read-only`) keeps action\n  tools in read-only mode: search and file loading still work, but writes and\n  subprocess execution are blocked.\n\nThe safest pattern is always:\n\n1. Load the large context into Aleph memory.\n2. Search or compute inside Aleph.\n3. Retrieve only the small result you need.\n\n## Docs Map\n\n- [MCP_SETUP.md](MCP_SETUP.md): client-by-client MCP and skill installation.\n- [docs/prompts/aleph.md](docs/prompts/aleph.md): the `/aleph` and `$aleph`\n  workflow plus tool patterns.\n- [docs/CONFIGURATION.md](docs/CONFIGURATION.md): flags, env vars, limits, and\n  safety settings.\n- [docs/langgraph-rlm-default.md](docs/langgraph-rlm-default.md): LangGraph\n  integration with Aleph-style tool usage.\n- [examples/langgraph_rlm_repo_improver.py](examples/langgraph_rlm_repo_improver.py):\n  repo improvement example with optional LangSmith tracing.\n- [CHANGELOG.md](CHANGELOG.md): release history.\n- [DEVELOPMENT.md](DEVELOPMENT.md): contributor guide.\n\n## Development\n\n```bash\ngit clone https://github.com/Hmbown/aleph.git\ncd aleph\npip install -e \".[dev,mcp]\"\n# Optional extras:\n#   .[docs]           -\u003e MarkItDown-backed document conversion\n#   .[observability]  -\u003e OpenTelemetry spans\npytest tests/ -v\nruff check aleph/ tests/\n```\n\n## References\n\n- Zhang, A. L., Kraska, T., Khattab, O. (2025)\n  [Recursive Language Models (arXiv:2512.24601)](https://arxiv.org/abs/2512.24601)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmbown%2Faleph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmbown%2Faleph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmbown%2Faleph/lists"}