Aleph

What is Aleph about?

Aleph implements the Recursive Language Model (RLM) paradigm, allowing large‑scale textual or JSON data to be kept outside the model's prompt context. The server supplies tools for searching, peeking, running Python code, chunking, and spawning sub‑agents, while automatically recording citations that link answers back to source fragments.

How to use Aleph?

1. Install the package:

   pip install aleph-rlm[mcp]
   aleph-rlm install   # auto‑configure popular MCP clients
   aleph-rlm doctor    # verify installation
   

2. Configure your MCP client (Claude Desktop, Cursor, Codex CLI, etc.) by adding the server entry shown in the README or using the provided aleph-rlm install <client> helper.
3. Load content from your environment:

   load_context(context="<large document>", context_id="doc")
   

4. Explore with tools such as search_context, peek_context, or exec_python to retrieve relevant slices or compute statistics.
5. Generate answers – the assistant will cite evidence automatically. For very large inputs, use chunk_context and sub_query to spawn recursive agents that process chunks in parallel before synthesising a final response.

Key features of Aleph

• External memory: Store unlimited text/JSON outside the LLM context.
• Navigation tools: Regex search, line/character peeking, chunking.
• Compute sandbox: Safe execution of Python code on the loaded data.
• Evidence tracking: Automatic citations linking outputs to source locations.
• Recursive agents: Automatic chunk‑based decomposition and sub‑agent orchestration.
• Optional actions: File I/O, shell commands, and test execution (off by default).
• Multi‑client support: Works with Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, Codex CLI, and any MCP‑compatible client.

Use cases of Aleph

• Debugging large logs – search for error patterns, compute statistics, and produce root‑cause reports.
• Legal or research document analysis – cite specific paragraphs while summarising contracts or papers.
• Codebase exploration – load repository files, run analysis scripts, and synthesize design overviews.
• Incident post‑mortems – navigate massive incident reports, extract timelines, and generate actionable recommendations.
• Data extraction from huge CSV/JSON dumps – chunk, query, and transform without hitting token limits.

FAQ from Aleph

Q: Do I need an OpenAI API key? A: Only if you use the api backend for sub_query. Set OPENAI_API_KEY (and optionally OPENAI_BASE_URL) in your environment.

Q: Is the Python sandbox secure? A: It is a best‑effort sandbox and not hardened. Do not run untrusted code; run Aleph inside a container for extra safety.

Q: Why are action tools disabled by default? A: To avoid accidental file system or command execution. Enable them with the --enable-actions flag when you trust the environment.

Q: How does recursion work? A: Use chunk_context to split a large document, then call sub_query on each chunk. Aleph coordinates parallel sub‑agents and aggregates their results.

Q: Which MCP clients are supported? A: Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, Codex CLI, and any client adhering to the Model Context Protocol.

Aleph

"What my eyes beheld was simultaneous, but what I shall now write down will be successive, because language is successive." — Jorge Luis Borges, "The Aleph" (1945)

Aleph is an MCP server that lets AI assistants work with documents too large to fit in their context window.

It implements the Recursive Language Model (RLM) paradigm from arXiv:2512.24601.

---

The problem

LLMs have a fundamental limitation: they can only "see" what fits in their context window. When you paste a large document into a prompt, models often miss important details buried in the middle—a phenomenon called "lost in the middle."

The usual approach:

1. Collect all relevant content
2. Paste it into the prompt
3. Hope the model attends to the right parts

The RLM approach (what Aleph enables):

1. Store content outside the model's context
2. Let the model explore it with tools (search, peek, compute)
3. Keep a trail of evidence linking outputs to source text
4. When needed, recurse: spawn sub-agents for chunks, then synthesize

Think of Borges' Aleph: a point containing all points. You don't hold it all in attention at once—you move through it, zooming and searching, returning with what matters.

---

What Aleph provides

Aleph is an MCP server—a standardized way for AI assistants to use external tools. It works with Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, Codex CLI, and other MCP-compatible clients.

When you install Aleph, your AI assistant gains:

Capability	What it means
External memory	Store documents outside the context window as searchable state
Navigation tools	Search by regex, view specific line ranges, jump to matches
Compute sandbox	Run Python code over the loaded content (parsing, stats, transforms)
Evidence tracking	Automatically cite which parts of the source informed each answer
Recursive agents	Spawn sub-agents to process chunks in parallel, then aggregate

The content you load can be anything representable as text or JSON: code repositories, build logs, incident reports, database exports, API responses, research papers, legal documents, etc.

---

Quick start

pip install aleph-rlm[mcp]

# Auto-configure popular MCP clients
aleph-rlm install

# Verify installation
aleph-rlm doctor

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "aleph": {
      "command": "aleph-mcp-local",
      "args": ["--enable-actions"]
    }
  }
}

Claude Code auto-discovers MCP servers. Run aleph-rlm install claude-code or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "aleph": {
      "command": "aleph-mcp-local",
      "args": ["--enable-actions"]
    }
  }
}

Install the /aleph skill for the RLM workflow prompt:

mkdir -p ~/.claude/commands
cp /path/to/aleph/docs/prompts/aleph.md ~/.claude/commands/aleph.md

Add to ~/.codex/config.toml:

[mcp_servers.aleph]
command = "aleph-mcp-local"
args = ["--enable-actions"]

Or run: aleph-rlm install codex

Install the /aleph skill for Codex:

mkdir -p ~/.codex/skills/aleph
cp /path/to/aleph/ALEPH.md ~/.codex/skills/aleph/SKILL.md

---

How it works in practice

Once installed, you interact with Aleph through your AI assistant. Here's the typical flow:

1. Load your content

load_context(context="<your large document>", context_id="doc")

The assistant stores this externally—it doesn't consume context window tokens.

2. Explore with tools

search_context(pattern="error|exception|fail", context_id="doc")
peek_context(start=120, end=150, unit="lines", context_id="doc")

The assistant searches and views only the relevant slices.

3. Compute when needed

# exec_python — runs in the sandbox with your content as `ctx`
matches = search(r"timeout.*\d+ seconds")
stats = {"total_matches": len(matches), "lines": [m["line_no"] for m in matches]}

4. Get cited answers

The assistant's final answer includes evidence trails back to specific source locations.

Using the /aleph command

If you've installed the skill, just use:

/aleph: Find the root cause of this test failure and propose a fix.

For AI assistants using Aleph, see ALEPH.md for the detailed workflow.

---

Recursion: handling very large inputs

When content is too large even for slice-based exploration, Aleph supports recursive decomposition:

1. Chunk the content into manageable pieces
2. Spawn sub-agents to analyze each chunk
3. Synthesize findings into a final answer

# exec_python
chunks = chunk(100_000)  # split into ~100K char pieces
results = [sub_query("Extract key findings.", context_slice=c) for c in chunks]
final = sub_query("Synthesize into a summary:", context_slice="\n\n".join(results))

sub_query can use an API backend (OpenAI-compatible) or spawn a local CLI (Claude, Codex, Aider)—whichever is available.

---

Available tools

Core exploration:

Tool	Purpose
load_context	Store text/JSON in external memory
search_context	Regex search with surrounding context
peek_context	View specific line or character ranges
exec_python	Run Python code over the content
chunk_context	Split content into navigable chunks

Workflow management:

Tool	Purpose
think	Structure reasoning for complex problems
get_evidence	Retrieve collected citations
summarize_so_far	Summarize progress on long tasks
finalize	Complete with answer and evidence

Recursion:

Tool	Purpose
sub_query	Spawn a sub-agent on a content slice

Optional actions (disabled by default, enable with --enable-actions):

Tool	Purpose
load_file	Load a workspace file into a context
read_file, write_file	File system access
run_command, run_tests	Shell execution
save_session, load_session	Persist/restore state

Action tools that return JSON support output="object" for structured responses without double-encoding.

---

Configuration

Environment variables for sub_query:

# Backend selection (auto-detects by default)
export ALEPH_SUB_QUERY_BACKEND=auto   # or: api | claude | codex | aider

# API credentials (for API backend)
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1
export ALEPH_SUB_QUERY_MODEL=gpt-4o-mini

Note: Some MCP clients don't reliably pass env vars from their config to the server process. If sub_query reports "API key not found" despite your client's MCP settings, add the exports to your shell profile (~/.zshrc or ~/.bashrc) and restart your terminal/client.

See docs/CONFIGURATION.md for all options.

---

Changelog

Unreleased

• Added load_file and auto-created contexts for action tools when a context_id is provided
• Standardized line numbering to 1-based by default (configurable), clarified peek/search line ranges, and added include_raw for read_file
• Added output="object" for structured responses and consistent JSON error payloads
• Reduced evidence noise with search summary mode and record_evidence flags; cite now validates line ranges
• Hardened run_tests reporting (exit codes/errors) and sub_query backend validation; added sandbox import introspection helpers

---

Security

• The Python sandbox is best-effort, not hardened—don't run untrusted code
• Action tools (file/command access) are off by default and workspace-scoped when enabled
• For untrusted inputs, run Aleph in a container with resource limits

---

Development

git clone https://github.com/Hmbown/aleph.git
cd aleph
pip install -e '.[dev,mcp]'
pytest

See DEVELOPMENT.md for architecture details.

---

License

MIT