Wissenschaftlicher Intelligence Layer

lean-ctx geht über einfaches Pattern Matching hinaus. Sechs Algorithmen aus der Informationstheorie, Graphentheorie und statistischen Mechanik arbeiten zusammen, um zu entscheiden, was behalten, was entfernt und wo platziert wird - alles automatisch, alles lokal, keine Konfiguration.

Diese Algorithmen treiben den autonomen Intelligence Layer an. Sie werden bei jedem ctx_read-, ctx_preload- und ctx_overview-Aufruf aktiviert - du rufst sie nie direkt auf.

Wie die Ebenen zusammenwirken

Predictive Surprise Scoring

Traditionelle Kompressionsfilter nutzen Shannon-Entropie auf Rohzeichen, was aaaa und import als gleich vorhersagbar behandelt. Predictive Surprise misst stattdessen die Kreuzentropie gegen BPE-Token-Häufigkeit - wie überraschend jede Zeile für den Tokenizer des LLM ist.

So funktioniert es

1. Jede Zeile wird mit o200k_base (GPT-4o / Claude Tokenizer) tokenisiert.
2. Für jeden Token schätzt ein Zipf-Prior die erwartete Häufigkeit basierend auf dem Rang.
3. Die Kreuzentropie wird berechnet: Zeilen mit häufigen Tokens (Boilerplate) erhalten niedrige Werte; Zeilen mit seltenen Tokens (komplexe Logik) erhalten hohe Werte.
4. Zeilen unter dem Überraschungsschwellenwert sind Kandidaten für die Entfernung bei aggressiver Kompression.

Beispiel

// Low surprise (boilerplate) - candidate for removal:
return Ok(());                    // surprise: 0.12
use std::collections::HashMap;   // surprise: 0.18

// High surprise (unique logic) - always preserved:
let decay = (-alpha * dist as f64).exp();   // surprise: 0.89
scores[j] += heat[i] * decay / degree;      // surprise: 0.94

Warum es wichtig ist

Predictive Surprise entfernt 15–30% mehr Boilerplate als zeichenbasierte Entropie und bewahrt dabei komplexe Logik.

Spectral Relevance Propagation

Wenn du lean-ctx bittest, Kontext für eine Aufgabe vorzuladen, muss es entscheiden, welche Dateien relevant sind. Spectral Relevance findet Dateien, die strukturell verbunden sind - auch wenn sie keine gemeinsamen Keywords haben.

So funktioniert es

Zwei Graph-Algorithmen laufen auf dem Abhängigkeitsgraphen des Projekts:

1. Heat Diffusion - Seed-Dateien, die zur Aufgabenbeschreibung passen, erhalten initiale "Wärme". Die Wärme breitet sich entlang von Import-Kanten mit exponentiellem Abfall aus.
2. PageRank-Zentralität - Dateien, die von vielen anderen Dateien importiert werden, erhalten höhere Zentralitätswerte.

Der finale Relevanzwert kombiniert beides: 0.7 × Wärme + 0.3 × PageRank.

Beispiel

Task: "fix authentication bug"

Direct matches:       auth.ts, login.ts
Heat diffusion adds:  middleware.ts (imports auth.ts)
                      session.ts (imported by auth.ts)
PageRank promotes:    db.ts (imported by 18 files - structural hub)

Result: 5 files preloaded instead of 2, covering the full blast radius.

Keine Konfiguration

Der Abhängigkeitsgraph wird bei der ersten Verwendung automatisch erstellt.

Boltzmann Context Allocation

Sobald Spectral Relevance die relevanten Dateien auswählt, braucht jede Datei ein Token-Budget. Boltzmann Allocation nutzt statistische Mechanik, um Tokens optimal zu verteilen.

So funktioniert es

1. Jede Datei hat einen Relevanzwert E_i aus Spectral Relevance.
2. Ein Temperaturparameter β wird aus der Aufgabe abgeleitet.
3. Token-Budgets folgen der Boltzmann-Verteilung: budgeti = total × (eβ·Ei / Σ eβ·Ej)
4. Minimum- und Maximum-Budgets werden erzwungen (128–4096 Tokens pro Datei).

Beispiel

Task: "fix the JWT validation in auth middleware"
Task specificity: 0.85 (specific) → β = 4.2

File            | Relevance | Budget | Mode
auth.ts         |      0.92 |  3,200 | full
middleware.ts   |      0.78 |  1,800 | full
session.ts      |      0.45 |    420 | map
db.ts           |      0.31 |    180 | signatures
routes.ts       |      0.22 |    128 | signatures
                                ─────
Total:                         5,728 tokens (within 8,000 budget)

Reciprocal Rank Fusion (RRF) Cache Eviction

lean-ctx uses Reciprocal Rank Fusion for cache eviction decisions, replacing the earlier Boltzmann-inspired weighted scoring. RRF handles incomparable signals (time in seconds, frequency as counts, size in tokens) without arbitrary weight tuning.

Formula: RRF(d) = Σ 1/(K + ranki(d)) - entries with the lowest fused score are evicted first. This produces monotonically correct ordering regardless of signal magnitude differences.

Semantic Chunking mit Attention Bridges

LLMs leiden unter dem "Lost in the Middle"-Problem. Semantic Chunking strukturiert die Ausgabe um, um Informationsverlust zu minimieren.

So funktioniert es

1. Chunk-Erkennung - Quellzeilen werden anhand von AST-Grenz-Heuristiken in semantische Chunks gruppiert.
2. Relevanz-Sortierung - Chunks, die zur aktuellen Aufgabe passen, werden nach oben befördert.
3. Attention Bridges - Zwischen Chunks fügt lean-ctx minimale Brückenmarkierungen (---) ein.
4. Tail Anchors - Die letzten 2–3 Zeilen des höchstpriorisierten Chunks werden am Ende wiederholt.

Beispiel

// Without chunking (flat output):
import { db } from '../pages/docs/db';
import { hash } from '../pages/docs/crypto';
const MAX_RETRIES = 3;
export function createUser(...) { ... }
export function validateToken(...) { ... }    ← lost in the middle
export function deleteUser(...) { ... }

// With semantic chunking (task: "fix token validation"):
export function validateToken(...) { ... }    ← promoted to top
---
export function createUser(...) { ... }
export function deleteUser(...) { ... }
---
import { db } from '../pages/docs/db';
const MAX_RETRIES = 3;
---
// anchor: validateToken signature                ← tail anchor

MMR Deduplication

Maximum Marginal Relevance (MMR) entfernt Redundanz und bewahrt einzigartige Informationen.

So funktioniert es

1. Für jede Zeile wird die Bigramm-Jaccard-Ähnlichkeit berechnet.
2. Der MMR-Score balanciert Relevanz gegen Redundanz: MMR(l) = λ × relevance(l) - (1 - λ) × max_similarity(l, selected)
3. Zeilen mit MMR < 0 werden unterdrückt.

Auswirkung

MMR entfernt 10–25% redundanten Inhalt.

BPE-optimierte Token-Kompression

Ein letzter Durchlauf optimiert den Rohtext für den BPE-Tokenizer des LLM.

Optimierungsregeln

So funktioniert es

Jede Regel ist eine einfache Zeichenkettenersetzung nach allen anderen Kompressionsstufen.

Auswirkung

BPE-Optimierung spart typischerweise 3–8% zusätzliche Tokens.

Auswirkung überprüfen

Führe lean-ctx benchmark run in deinem Projekt aus, um den kombinierten Effekt aller sechs Algorithmen zu messen.

$ lean-ctx benchmark run
──────────────────────────────────────────
BENCHMARK - /Users/you/project
──────────────────────────────────────────
Files:       143
Total:       285,401 → 42,810 tokens (85% reduction)
Avg/file:    1,997 → 300 tokens

Preservation:
  AST:         98.2%
  Identifiers: 97.4%
  Lines:       96.1%

Mode breakdown:
  full:        68% of files
  map:         22% of files
  signatures:   8% of files
  aggressive:   2% of files

Strukturierte Intent-Erkennung

lean-ctx klassifiziert jede Interaktion in einen StructuredIntent - eine Slot-basierte Darstellung mit Aufgabentyp, Konfidenz, Zieldateien, Scope, Sprachhinweis, Dringlichkeit und Aktionsverb. Dies steuert alle nachgelagerten Entscheidungen: welcher Kompressionsmodus verwendet wird, wie Kontext geroutet wird und was priorisiert wird.

9 Aufgabentypen werden erkannt: Explore, Generate, FixBug, Refactor, Test, Review, Config, Deploy und Document. Jeder Typ löst unterschiedliche Kompressionsstrategien und Kontext-Routing aus.

IntentScope reicht von SingleFile über MultiFile und CrossModule bis ProjectWide - und bestimmt, wie breit Kontext gesammelt wird.

So funktioniert es

Kompression passt sich pro Intent an: FixBug-Aufgaben priorisieren Fehlerzeilen und Testdateien über den Information-Bottleneck-Filter, Explore-Aufgaben nutzen leichte Bereinigung zur Strukturerhaltung, und Generate-Aufgaben fokussieren auf Signaturen und Typen.

Der Auto-Modus-Selektor von ctx_read nutzt den aktiven Aufgabentyp zur Verfeinerung - wählt task-Modus für Bug-Fixes in großen Dateien, map-Modus für Exploration und signatures-Modus für Dokumentationsaufgaben.

Beispiel

Query: "fix the NaN bug in entropy.rs"

StructuredIntent:
  task_type:    FixBug (confidence: 0.95)
  targets:      ["entropy.rs"]
  scope:        SingleFile
  language:     Rust
  urgency:      0.8
  action_verb:  "fix"

→ Compression: Information Bottleneck filter (error lines boosted)
→ Mode:        task (error-focused extraction)
→ Suggestions: tests/entropy_test.rs (deficit detection)

Context-Pipeline-Architektur

Die Context-Pipeline verarbeitet Informationen durch sechs Schichten: Input → Intent → Relevance → Compression → Translation → Delivery. Jede Schicht hat definierte Verträge (Input/Output-Typen) und emittiert Metriken.

So funktioniert es

Input → Intent → Relevance → Compression → Terse Engine → Delivery
  │        │          │            │              │              │
  │        │          │            │              │              └─ Final output to LLM
  │        │          │            │              └─ 4-layer terse pipeline (see below)
  │        │          │            └─ AST-aware compression per intent
  │        │          └─ Graph heat + relevance scoring
  │        └─ StructuredIntent classification
  └─ Raw file content / shell output

Pro-Schicht-Metriken erfassen Input-Tokens, Output-Tokens, Kompressionsrate und Verarbeitungszeit. Aggregiert über eine Session zeigen sie, wo die meisten Einsparungen entstehen und welche Schichten Engpässe sind.

4-Layer Terse Engine

The terse engine applies four composable compression layers, controlled by compression_level (Off / Lite / Standard / Max). Each layer is independently verified by Lean4 proofs (TerseQuality, TerseEngine — part of 82 total theorems).

Context-Ledger & Druck-Management

Der ContextLedger trackt jede Datei, die an die AI gesendet wird: Pfad, Kompressionsmodus, Original-Tokens, gesendete Tokens und Zeitstempel. Er berechnet die Context-Window-Auslastung und den Druck in Echtzeit.

So funktioniert es

Drei Druckstufen: None (unter 70% Auslastung), Compress (70–90%) und Evict (über 95%). Auf jeder Stufe ergreift das System unterschiedliche Maßnahmen - Downgrade von Kompressionsmodi für weniger relevante Dateien oder Vorschlag von Evictions.

Beispiel

Context Window: 128,000 tokens
Loaded: 89,600 tokens (70% utilization)
Pressure: None → safe

After loading 3 more files:
Loaded: 115,200 tokens (90% utilization)
Pressure: Compress → downgrade non-target files

Re-Injection Plan:
  utils.rs:    full → signatures  (save 2,400 tokens)
  helpers.rs:  full → map         (save 1,800 tokens)
  config.rs:   full → signatures  (save 1,200 tokens)
  Protected:   auth.rs, login.ts  (target files)

Context-Deficit-Erkennung identifiziert fehlende Informationen: Wenn ein Bug-Fix auth.rs betrifft, aber keine Testdatei geladen ist, schlägt das System tests/auth_test.rs vor. Für Config-Aufgaben empfiehlt es Cargo.toml, .env oder Dockerfile.

Smart Re-Injection generiert einen Plan zur Freigabe von Context-Budget durch Downgrade von Nicht-Ziel-Dateien (z.B. Wechsel von full zu signatures-Modus) bei gleichzeitigem Schutz der für den aktuellen Intent kritischen Dateien.

Multi-Agent-Intelligenz

Wenn mehrere AI-Agenten zusammenarbeiten (z.B. ein Coder und ein Reviewer), bietet lean-ctx strukturierte Handoffs, rollenbasierte Kontexttiefe und agentübergreifenden Wissensaustausch.

So funktioniert es

HandoffPackage bündelt den aktuellen Session-Ledger, den strukturierten Intent und den Context-Snapshot in einer übertragbaren Einheit - so dass der empfangende Agent mit vollständigem Situationsbewusstsein startet statt mit einem leeren Blatt.

Sieben Agentenrollen werden erkannt: Coder, Reviewer, Planner, Explorer, Debugger, Tester und Orchestrator. Jede erhält eine maßgeschneiderte ContextDepthConfig - ein Coder bekommt mehr Voll-Datei-Reads, ein Reviewer mehr Signaturen, ein Explorer breiteren Graph-Kontext.

Beispiel

Agent "coder-1" (role: Coder):
  max_files_full: 8
  preferred_mode: full
  context_budget: 80%

Agent "reviewer-1" (role: Reviewer):
  max_files_full: 3
  preferred_mode: signatures
  context_budget: 60%

Shared Knowledge:
  K:discovery:auth_bug = "null check missing in line 42"
  K:decision:fix_approach = "add Option<T> wrapper"
  → reviewer-1 inherits these facts without re-reading files

Agentübergreifender Wissensaustausch ermöglicht Agenten den Austausch strukturierter Fakten (z.B. "discovery:auth_bug=null check fehlt in Zeile 42") über ein gemeinsames Scratchpad. Neue Agenten erben relevantes Wissen, ohne es neu entdecken zu müssen.

Community Detection (Louvain)

The core::community module clusters files by their dependency graph using the Louvain algorithm. This groups tightly-coupled files into communities, enabling more intelligent context selection — files in the same community as your target are prioritized for preloading and receive higher relevance scores during task-driven reads.

Code Smell Detection

The ctx_smells tool detects long functions, deep nesting, and high cyclomatic complexity using the core::smells module. Detected smells are scored with graph-enriched weighting — files with high PageRank or many dependents receive amplified smell scores, surfacing maintenance hotspots that have the widest blast radius across the codebase.

Siehe auch

• Autonome Intelligence Tools - die Tools, die diese Algorithmen nutzen
• Tree-sitter Engine - AST-Parsing für 18 Sprachen
• Konfiguration - Schwellenwerte und Autonomie-Einstellungen anpassen
• Benchmark - deine Einsparungen messen