Architektur
The architecture.
One Rust binary. Five subsystems. Zero cloud dependencies. Every box below maps to a real module, port, or file on disk.
System topology.
Die Prozess-Topologie der ausgelieferten Binary: sieben Einstiegspunkte, eine Laufzeit, ein Satz lokaler Stores. Jede Box unten entspricht einem echten Modul, Port oder einer Datei auf der Platte.
lean-ctx lean-ctx serve lean-ctx serve --daemon lean-ctx -c "<cmd>" lean-ctx proxy start lean-ctx dashboard lean-ctx watch · gain --live One binary. Five subsystems. No cloud required.
Datenfluss Stage by stage.
Blatt 2 verfolgt eine Anfrage Stufe für Stufe durch die Laufzeit, inklusive des Cache-Kurzschlusses, der wiederholte Reads nahezu kostenlos macht. Der Shell-Pfad läuft parallel mit derselben Abrechnung.
ctx_read(path, mode) · lean-ctx read - PathJail
core/pathjail.rsKanonisiert den Pfad und weist Escapes außerhalb des Workspace-Roots ab, bevor irgendein I/O passiert.
- Session-Cache
hit → ~13 tokensContent-adressiertes Lookup mit Schlüssel aus Pfad + mtime/Hash. Unveränderte Dateien kollabieren zu einem Stub, statt Inhalt erneut zu senden.
- AST-Extraktion
26 languagestree-sitter parst die Datei in einen Syntaxbaum: Signaturen, Imports, Call-Edges — auch Lua, Luau, Kotlin und GDScript werden graph-indiziert. Regex-Fallback für nicht unterstützte Sprachen.
- Modus-Auswahl
10 modesauto wählt den optimalen von 10 Read-Modi (full, map, signatures, diff, task, reference, aggressive, entropy, lines:N-M) aus Task-Intent und Dateigröße; structure_first lenkt kalte Code-Reads mittlerer Größe Richtung map, und eine bei einem Fix-Task als verdächtig markierte Datei wird auf full gezwungen.
- Kompression
adaptive thresholdsShannon-Entropie-Zeilenfilterung, U-Kurven-Attention-Platzierung (LITM), TF-IDF-Codebook und query-konditionierte Information-Bottleneck-Fusion — ein Anti-Inflation-Guard liefert die Datei wortgetreu, wann immer das Framing mehr Tokens kosten würde als die rohen Bytes.
- Token-Abrechnung
core/tokens.rsExakte tiktoken-Zählung (o200k_base; cl100k_base-Näherung für Modelle der Claude-Familie) auf Input und Output.
- Ledger + Stats
savings sign / verify-batchEinsparungen werden an das lokale Ledger angehängt (Ed25519-signierbar), Stats und der gain-Score aktualisieren sich, das Ergebnis streamt zurück.
lean-ctx -c "cargo test" · IDE bash hook Beide Pfade enden im selben Ledger: jedes Kompressions-Event wird mit exakter Tokenizer-Mathematik gezählt und speist gain, das Dashboard und das signierte Savings-Ledger.
Kompression engine.
Tree-sitter parses 27 languages into ASTs. 10 read modes select the right abstraction level — from full source to aggressive entropy filtering. 95+ shell patterns compress git, cargo, npm, docker, and kubectl output into compact evidence.
Explore read modesAvailable modes full → entire file, no compression signatures → fn signatures + type defs map → structural overview diff → uncommitted changes only task → query-conditioned extract aggressive → maximum compression entropy → information-dense lines reference → symbols + doc comments lines:N-M → specific line rangeSelected: signatures (420 lines → 18 lines)Memory, agents, security.
Content-addressed caching collapses re-reads to ~13 tokens. A knowledge graph persists decisions across sessions. The agent bus coordinates multiple agents without duplicating context. PathJail, shell allowlists, and TOCTOU checks enforce deny-by-default boundaries on every call.
Security modelCache 47 entries · 73% hit rateKnowledge 342 nodes · 1,205 edgesAgent bus 3 agents registeredPathJail root: /Users/dev/projectAllowlist 14 allow, 6 denyRedaction .env, credentials.*TOCTOU open-handle verify activeLedger Ed25519-signed · 0 violationsEngineering data sheet.
Die Referenztabellen hinter den Zeichnungen: jede Oberfläche mit Transport und Lebenszyklus, das On-Disk-Layout, die adaptiven Lernschichten und die Sicherheitsgrenzen, die die Laufzeit durchsetzt.
AProzessmodell
Alle Oberflächen sind dieselbe Binary in verschiedenen Rollen. Nichts braucht eine Cloud-Verbindung; alles bindet local-first.
| REF | SURFACE | TRANSPORT | ENDPOINT | LIFECYCLE | BEFEHL |
|---|---|---|---|---|---|
| 01 | MCP-Server (stdio) | JSON-RPC über stdin/stdout | pro Editor-Session gestartet | Kindprozess des Editors | lean-ctx |
| 02 | MCP-Server (HTTP) | MCP Streamable HTTP | localhost, konfigurierbar via --host/--port | Vordergrund oder Service | lean-ctx serve |
| 03 | IPC-Daemon | Unix Domain Socket | OS-Data-Dir, z. B. ~/Library/Application Support/lean-ctx/daemon.sock | launchd / systemd Autostart | lean-ctx serve --daemon |
| 04 | Shell-Hook | Prozess-Exec, komprimierter stdout | umschließt IDE-Bash-Aufrufe + interaktive Shells | pro Befehl | lean-ctx -c "<cmd>" |
| 05 | API-Proxy | HTTP (LLM-API-Pass-through) | localhost:4444 (Standard) | bei Bedarf | lean-ctx proxy start |
| 06 | Web-Dashboard | HTTP + Bearer-Token | localhost:3333 (Standard, --port) | bei Bedarf | lean-ctx dashboard |
| 07 | Terminal-UI | TTY (In-place-Redraw) | Live-Event-Stream / 1 s Refresh | interaktiv | lean-ctx watch · gain --live |
BStorage-Layout — lokale XDG-Verzeichnisse
Persistenter Zustand sind einfache Dateien unter den XDG-Basisverzeichnissen: inspizierbar, exportierbar, löschbar. Keine versteckten Datenbanken außerhalb dieser lokalen Ordner.
| ARTEFAKT | FORM | ZWECK |
|---|---|---|
config.toml | TOML | Einzelne Config-Datei — Integrationsmodus, Kompression, Provider, Opt-outs (Config-Dir) |
cache/ | content-adressiert | Session-Datei-Cache; unveränderte Re-Reads kollabieren zu ~13-Token-Stubs (Cache-Dir) |
bm25 index | invertierter Index | Lexikalische Suche über Code-Chunks + Provider-Dokumente (Data-Dir) |
context_graph/ | Property-Graph | Imports, Calls, Typen über Dateien und Repos — treibt map-Modus + Deep-Queries (Data-Dir) |
knowledge | SQLite | Persistente Fakten, Entscheidungen, Rooms — über Sessions hinweg abrufbar, CCP (Data-Dir) |
savings ledger | append-only JSONL | Jedes Kompressions-Event; Ed25519-signierbar für Audits (Data-Dir) |
litm_calibration.json | JSON | Gelernte Kontext-Positions-Trefferraten (Lost-in-the-Middle-Kalibrierung) (Cache-Dir) |
events.jsonl | Event-Stream | Live-Feed, konsumiert von watch, Dashboard und Efficacy-Reports (State-Dir) |
CAdaptive Lernschichten
Sieben Online-Learning-Mechanismen stimmen die Kompression auf deine reale Nutzung ab — lokal, aus Qualitätssignalen wie Bounces und Edit-Fehlern. Tiefer eintauchen: Adaptive Learning →
- L1 Adaptive Schwellenwerte Online-gelernte Kompressions-Aggressivität aus Qualitätssignalen (Bounces, fehlgeschlagene Edits, saubere Runs)
- L2 LITM-Kalibrierung Empirische Platzierung kritischen Kontexts an Positionen, die das Modell tatsächlich beachtet
- L3 Stigmergisches Scent-Field Multi-Agent-Koordination über zerfallende Marker: claimed, done, stuck, hot, avoid
- L4 Delta-Playbook Inkrementelle Checkpoint-Snapshots, die Kontext-Kompaktierung überleben
- L5 Query-konditioniertes IB Information-Bottleneck-Kompression, fusioniert mit Query-Relevanz
- L6 Theta-Gamma-Chunking Wakeup-Fakten gruppiert in attention-freundlichen Bursts
- L7 Semantisches Dedup Likelihood-bewertete Redundanzfilterung über die Session
DSicherheitsgrenzen
Harte Garantien, in der Laufzeit durchgesetzt. Sicherheitsmodell →
- PathJail Jeder Dateizugriff wird kanonisiert und auf den Workspace-Root beschränkt
- IDE-Config-Dir-Jail Home-Level-IDE-/Agent-Config-Dirs (~/.claude, ~/.codex, ~/.codebuddy, …) sind nur schreibbar, wenn allow_ide_config_dirs aktiviert ist; sonst blockiert PathJail sie
- Shell-Allowlist Deny-by-default-Befehls-Policy für agent-initiierte Shell-Ausführungen
- Local-first Gesamte Verarbeitung on-device; das Dashboard bindet an localhost und erfordert ein Bearer-Token
- Signierte Evidenz Savings-Ledger-Einträge sind Ed25519-signierbar und batch-verifizierbar
Explore thesource.
LeanCTX is open source. Read the code, understand the design, contribute.