aleph-compiler 1.1.2__tar.gz

aleph_compiler-1.1.2/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aleph_compiler-1.1.2/NOTICE

@@ -0,0 +1,28 @@
+NOTICE — Aleph Semantic Compiler
+
+Copyright 2026 Aleph Null LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+PATENT PENDING
+
+The methods, systems, and processes embodied in this software — including but
+not limited to semantic compression of source code for large language model
+consumption, symbol-addressed navigation protocols, salience-weighted attention
+budgets, epistemic continuity layers, confidence-decay inference systems,
+multi-agent epistemic versioning, and pre-modification impact analysis — are
+the subject of one or more pending patent applications. The Apache License,
+Version 2.0 includes an express grant of patent rights from contributors to
+users (Section 3 of the License).
+
+For inquiries: support@alephnull.ai

aleph_compiler-1.1.2/PKG-INFO

@@ -0,0 +1,399 @@
+Metadata-Version: 2.4
+Name: aleph-compiler
+Version: 1.1.2
+Summary: Universal semantic compression layer for LLMs — compile any codebase into navigable artifacts
+Author: Pete Copeland
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://alephnull.ai
+Project-URL: Repository, https://github.com/alephnullai/aleph
+Project-URL: Issues, https://github.com/alephnullai/aleph/issues
+Keywords: llm,semantic,compression,mcp,code-analysis,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: tree-sitter<0.24,>=0.23.0
+Requires-Dist: tree-sitter-cpp<0.24,>=0.23.0
+Requires-Dist: tree-sitter-rust<0.23.3,>=0.23.0
+Requires-Dist: tree-sitter-python<0.24,>=0.23.0
+Requires-Dist: tree-sitter-typescript<0.24,>=0.23.0
+Requires-Dist: tree-sitter-go<0.24,>=0.23.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: cryptography>=42.0
+Provides-Extra: semantic
+Requires-Dist: fastembed>=0.4; extra == "semantic"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Dynamic: license-file
+
+# 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](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![v1.1](https://img.shields.io/badge/release-v1.1-blueviolet)](https://github.com/alephnullai/Aleph/releases)
+
+**Patent Pending** — See [NOTICE](NOTICE)
+
+---
+
+## 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](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
+
+---
+
+## 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
+
+```bash
+pip install aleph-compiler
+```
+
+Or from source:
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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](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**](https://www.hiwavebrowser.com) | 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](LICENSE) — 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](docs/LICENSING.md).
+
+---
+
+## Tool surface (33 tools)
+
+Aleph exposes a complete protocol via [Model Context Protocol](https://modelcontextprotocol.io). 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:
+```json
+// .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)
+    ↓  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
+
+```bash
+# 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](https://github.com/alephnullai/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](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 |
+
+**1088+ 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** — Java, 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 patent-pending parts (salience scoring in `src/aleph/link/project_salience.py`, body-pruning policy in `src/aleph/compress/policies.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](LICENSE) — 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, which composes with the pending patent applications described in [NOTICE](NOTICE). Prior MIT releases (≤ 0.5.0) remain MIT for anyone who already obtained them. The plain-words model lives in [docs/LICENSING.md](docs/LICENSING.md).
+
+**Patent Pending.** See [NOTICE](NOTICE) for patent details — the Apache-2.0 grant conveys the pending methods to every user, at no cost.
+
+---
+
+## Links
+
+- Website: [alephnull.ai](https://alephnull.ai)
+- Companion: [Null](https://github.com/alephnullai/null) · Tank (coming soon)
+- Issues: [github.com/alephnullai/Aleph/issues](https://github.com/alephnullai/Aleph/issues)
+- Support: `support@alephnull.ai`