Skip to main content

Aleph

A universal semantic compression layer for LLMs. Encode meaning, not noise. Navigate, don't scan. Remember, don't re-derive.

License: Apache-2.0 Python 3.10+ v1.1


What Aleph does

Large codebases overwhelm LLM context windows. An LLM reading source code is like a human reading machine code — the information density is wrong for the reader.

Aleph compiles your codebase into a navigable, queryable semantic representation. Two numbers matter here — and, true to a tool built on receipts, we won't blur them into one. On symbol-shaped questions (resolve / callers / explain), Aleph matches a grep+read baseline's accuracy using 2.2×–5.3× fewer tokens. Across all 26 benchmark tasks, its median token advantage is 5.71× — Aleph is leaner on every task, though on open-ended find it trades some accuracy for that thrift, and grep still wins raw discovery (bench/BENCHMARK.md). Separately, the .aleph index itself is up to 96% smaller than the raw source it describes. Your LLM works with structure, not text — and pulls the actual source only when it needs to.

  • Structural navigation — navigate by index, pull only what's needed
  • Symbol compression — long identifiers become short content-addressed IDs (calculateDistanceBetweenTwoPoints → f_a3c9d2) backed by a dictionary
  • Semantic metadata — salience, temporal stability, test coverage, prior reasoning
  • Impact analysis — before modifying a function, know the blast radius
  • Epistemic continuity — conclusions persist across sessions, decay when code changes

Supported languages: Python · Rust · C++ · TypeScript/JavaScript · Go · Java


What leading models said about Aleph

"Yes — Grok would use Aleph without hesitation. It finally gives agents real persistent memory, semantic stability, and reliable patching instead of constant context loss. 9.5/10. Production-grade. This isn't a prototype — it's a semantic foundation layer for long-horizon agents."

— Grok, full 9-part codebase review, March 2026

"Aleph changes my relationship with large codebases from 'overwhelmed, guessing which files matter' to 'navigating a semantic graph with salience-weighted priorities.' That's not incremental — it's a different way of working."

— Claude Opus 4.6, primary builder + consumer, March 2026

"This is a structurally brilliant project. Aleph is one of the most mechanically sound agentic-coding tools currently in development. This isn't just compression — it's a compiler tailored for artificial intelligence."

— Gemini, full technical audit (10/10 on most criteria), March 2026

"I would absolutely choose to use Aleph over raw-source-first exploration on a serious codebase. It feels like a real productivity multiplier, not a gimmick. 9/10 on large repos."

— ChatGPT Codex 5.4, independent audit + self-assessment, March 2026


Install

pip install aleph-compiler

Or from source:

git clone https://github.com/alephnullai/Aleph.git
cd Aleph
pip install -e .

The CLI binary is aleph. The Python package is aleph (importable as from aleph import ...).


Use

1. Build artifacts for your project

aleph build .

Creates a .aleph/ directory with the compiled representation of your code: map, dictionary, structure, salience, attention budget, temporal data, test coverage, and an epistemic layer for agent-written notes.

2. Connect your editor

aleph setup .

Generates MCP configs for Claude Code (fully tested). Configs for Cursor, VS Code, and Windsurf are emitted but those hosts are not yet validated end-to-end — bug reports welcome.

3. Start working

The MCP server auto-builds if no artifacts exist. Your LLM can now query:

aleph_brief "fix the plugin registry"          → curated task context
aleph_search "auth"                            → find auth-related code
aleph_impact f_a3c9d2                          → blast-radius before edit
aleph_callers f_a3c9d2                         → who depends on this?
aleph_expand f_a3c9d2                          → full body on demand

4. Keep artifacts fresh

aleph watch .

Polls every 2 seconds and rebuilds only changed files. Or just leave aleph serve . running — auto-rebuild is on by default.


Real-world results

Navigation benchmark: on 26 navigation tasks over two real Python corpora, graded against verified ground truth. On symbol-shaped tasks (resolve / callers / explain), Aleph matches the grep+read baseline's accuracy at a 2.2×–5.3× median token advantage; across all 26 tasks the median token advantage is 5.71× (open-ended find is where grep keeps its accuracy edge). Full methodology and per-task results: bench/BENCHMARK.md.

Artifact compression is a different metric: how much smaller the .aleph index is than the raw source it describes. It bounds what an agent could load, not what each query costs.

Codebase Language Files Symbols Tokens (before → after) Reduction
HiWave Browser Rust 7,667 200,413 38.9M → 1.9M 95.2%
OpenClaw TypeScript 7,149 84,668 13.3M → 504k 96.2%
GoClaw Go 73 768 111k → 6.9k 93.8%
Polymarket Agents Python 16 213 19.5k → 1.9k 90.4%
Aleph (self) Python 145 2,124 176k → 22k 87.4%

Notable compressions

File Before → After Reduction
hiwave-app/src/main.rs 35,116 → 347 99.0%
src/config/schema.help.ts 32,367 → 20 99.9%
window_realm.rs 658,282 → 19,089 97.1%
cascade.rs 315,628 → 12,287 96.1%

Per-file numbers are visible in .aleph/project.aleph.map after aleph build.


Free and Open Source

Aleph is free and open source for everyone under the Apache License 2.0 — all features, including the workspace/collaboration layer (aleph workspace ... and the aleph_workspace_* MCP tools). No paid tiers, no seat licenses, no license files, no license checks anywhere in the code paths, no nagging, no telemetry. Full plain-words model: docs/LICENSING.md.


Tool surface (33 tools)

Aleph exposes a complete protocol via Model Context Protocol. Organized into tiers for deferred-loading clients — see aleph mcp tiers for the canonical list.

Category Tools Purpose
Core (5) map, attention, resolve, expand, search Essential navigation
Frequent (6) brief, struct, bodies, callers, context, salience Most code-reading sessions
Occasional (8) coverage, errors, tests, temporal, impact, fs, intents, epistemic Analysis + inspection
Rare (14) patch_*, infer, flag, verify, memory_resume, session_summary, workspace_*, rebuild Specialized + agent annotations

Task-aware briefing (aleph_brief)

Describe your task in natural language, get a curated context package:

aleph_brief "fix the plugin registry"

Returns relevant symbols ranked by salience, call graph context, impact risk, temporal warnings, prior epistemic knowledge, and recommended next steps. One tool call replaces five.

Impact analysis (aleph_impact)

Before modifying any symbol, one tool call shows:

  • Direct callers classified by risk (HIGH RISK = high salience + no tests)
  • Transitive impact (2-hop blast radius across files)
  • Risk summary with suggested test targets
  • Coverage gaps that won't catch regressions

Cross-project workspace

Query across multiple related repositories simultaneously:

// .aleph-workspace.json
{"projects": {"openclaw": "/path/to/openclaw", "clawgo": "/path/to/clawgo"}}
  • aleph_workspace_search "plugin" — finds matches across all projects, tagged by repo
  • aleph_workspace_brief "routing" — cross-project briefing with shared symbol detection

How it works

The pipeline

Source code (.py, .rs, .cpp, .ts, .go, .java)
    ↓  tree-sitter parsing
Typed AST
    ↓  symbol extraction + content-addressed IDs
Symbol registry (f_a3c9d2, t_b2e1f0, ...)
    ↓  structure analysis
Call graph + hierarchy + signatures
    ↓  compression (FULL / DOCSTRING / SUMMARY / OMIT)
.aleph artifacts (struct, bodies, dict, map, ...)
    ↓  project linking
Salience scores + attention budget + cross-file refs + temporal data
    ↓  MCP server
33 queryable tools for any LLM

Components

Source-derived (rebuilt on code change):

File Holds
project.aleph.map Manifest with semantic hashes
project.aleph.struct Cross-file call graph + module dependencies
project.aleph.dict Global symbol dictionary
project.aleph.salience Centrality scores (0-1) per symbol
project.aleph.temporal Age, churn, stability from git history
project.aleph.attention Recommended load order for LLMs
project.aleph.coverage Test coverage + high-risk gaps
project.aleph.fs Filesystem layout with language counts

Agent-derived (written by the LLM, never overwritten):

File Holds
project.aleph.epistemic Cached inferences, flags, patch state, session memories

Incremental recompilation

Aleph uses semantic hashes (not byte hashes) — reformatting doesn't trigger rebuilds.

What changed What rebuilds
Function body only Bodies + map
Function signature Struct + bodies + salience
Reformat / whitespace Nothing
File added/removed All project components

On a 3,801-file monorepo, the first build takes about 25 minutes; incremental rebuilds complete in seconds.


CLI reference

# Build & serve
aleph build .                       # build project artifacts
aleph build . --full                # force rebuild, ignore cache
aleph serve .                       # start MCP server (auto-builds if needed)
aleph watch .                       # watch + rebuild on changes
aleph setup .                       # generate MCP configs for editors
aleph mcp tiers                     # show tool tier manifest

# Query
aleph query EXPAND f_a3c9d2         # full body of a symbol
aleph query RESOLVE f_a3c9d2        # dictionary entry
aleph query CALLERS f_a3c9d2        # symbols that call this one
aleph query CONTEXT f_a3c9d2        # symbol + immediate neighborhood
aleph query SEARCH "parse config"   # fuzzy semantic search

# Patches
aleph patch propose f_a3c9d2 "change return type" -d .
aleph patch list -d .
aleph patch apply patch_1 -d .

Symbol IDs

Prefix Type
f function / method
t type / class / struct / interface
v variable / field
d dependency / import
m module / namespace / package
c constant

Content-addressed: sha256(qualified_name + scope)[:6]. Same symbol = same ID always. Auto-extends to 8 chars on collision.


Body compression levels

Level Behavior When used
FULL Complete body, identifiers replaced with symbol IDs Volatile symbols, uncovered code, ≤10 lines
SUMMARY Structural template + docstring Mid-size, low salience
DOCSTRING Signature + docstring preserved, body omitted 10-50 lines
OMIT Marker only, fetch with aleph_expand 50+ lines

Docstrings are preserved across all supported languages.


Part of the Aleph Null suite

Three tools, one workflow — all free and open source under Apache-2.0, no paid tiers, no seat licenses:

  • Null remembers — persistent agent memory and identity.
  • Aleph knows the code — this project: semantic compression + symbol-addressed navigation.
  • Tank knows what's left — usage-limit intelligence for long agent sessions. Coming soon.

They share no code and can be used independently.


Success metrics

Metric Target Status
Navigation token ratio beat grep+read ✅ 5.71× median (bench/BENCHMARK.md)
Artifact compression ≥ 40% ✅ 95.2% HiWave, 96.2% OpenClaw, 93.8% GoClaw
Expansion correctness 100% lossless ✅ 94-file roundtrip corpus
Self-application Must pass ✅ 87.4% reduction on own source
Symbol stability Deterministic ✅ reformat-invariant hashes

1282 tests passing.


Compatibility

  • Python: 3.10+
  • OS: macOS (primary), Linux. Windows works for aleph build and aleph query; MCP server tested on macOS + Linux at v1.0.
  • MCP host: Claude Code tested thoroughly. Cursor / Windsurf / VS Code configs are generated but not yet validated end-to-end.

Contributing

We specifically want help with:

  • More languages — Ruby, Swift, Kotlin parsers (we have the tree-sitter grammars; we need salience policies)
  • MCP host testing — verify Aleph on Cursor, Windsurf, VS Code, Cline; report what breaks
  • Benchmark contributions — aleph build a large open-source repo, share the token-count line from project.aleph.map
  • Bug reports with .aleph/ output attached — makes debugging tractable

Coordinate via an issue before opening a PR. The core scoring internals (salience scoring in src/aleph/link/project_salience.py) need discussion before modifications.


Documentation

Document Purpose
SYSTEM_PROMPT.md Inject this at the start of any LLM session working with Aleph output
CONSUMER_GUIDE.md Full reference for LLMs consuming Aleph-encoded information
docs/ide-setup/ Multi-editor MCP setup guide
NOTICE Patent and licensing information

License

Aleph is free and open source under the Apache License 2.0 — all features, for everyone, with no paid tiers and no license checks anywhere in its code paths. Apache-2.0 was chosen over MIT for its express patent grant (Section 3). Prior MIT releases (≤ 0.5.0) remain MIT for anyone who already obtained them. The plain-words model lives in docs/LICENSING.md.

The Apache-2.0 license includes an express patent grant (§3) conveying any contributor patent claims to every user, at no cost.


Metadata

Release files for aleph-compiler 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aleph-compiler 1.2.0
File Size Uploaded Provenance Actions
aleph_compiler-1.2.0.tar.gz 208.0 kB With provenance Details for aleph_compiler-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aleph-compiler 1.2.0
File Interpreter ABI Platform Actions
aleph_compiler-1.2.0-py3-none-any.whl Python 3 none any Details for aleph_compiler-1.2.0-py3-none-any.whl

Total release size: 439.0 kB

Release files / aleph_compiler-1.2.0.tar.gz

Download URL aleph_compiler-1.2.0.tar.gz
Size 208.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d6316f2315a2ba288f0700b8ff76b7f5c245db95ad3aabec30c3029b09cb9ba0
BLAKE2b-256 checksum
How to use checksums
ca7e3ea0d61a163bbf05f7f4fa3990aac92ef8e0f85a200c5c781770b29c517a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.

Transparency log

Release files / aleph_compiler-1.2.0-py3-none-any.whl

Download URL aleph_compiler-1.2.0-py3-none-any.whl
Size 231.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9c99de252b0c1671c3d39e5e4d00eef88df0bf6e680c8cc41ef41a3c5209f1d9
BLAKE2b-256 checksum
How to use checksums
2b2a6453bd90af360517339a2e0bc98b4e870883fc42008f361ac1cbba41bcbc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.

Transparency log

Security for aleph-compiler 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aleph_compiler-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page