Il sistema che decide
cosa vede la tua AI.
Lo strato di context engineering per gli agenti AIUn singolo binario locale su entrambi i lati del modello. LeanCTX percepisce, comprime, ricorda, instrada e governa l'intero ciclo di vita del contesto AI, dalla lettura dei file agli output verificati.
Cos'è uno Strato di Contesto Cognitivo?
Uno Strato di Contesto Cognitivo è l'infrastruttura tra i tuoi strumenti AI e la tua codebase. Controlla quali file vengono letti, come viene compresso l'output, quale conoscenza persiste attraverso le sessioni e se i risultati soddisfano gli standard di qualità prima della consegna.
Il disegno costruttivo
La topologia del processo del binario distribuito: sette punti di ingresso, un runtime, un set di store locali. Ogni riquadro qui sotto corrisponde a un modulo, una porta o un file reale su disco.
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 Cosa succede a una singola lettura
La Scheda 2 traccia una richiesta attraverso il runtime, stadio per stadio, incluso lo short-circuit del cache che rende le letture ripetute quasi gratuite. Il percorso shell viene eseguito in parallelo con la stessa contabilità.
ctx_read(path, mode) · lean-ctx read - PathJail
core/pathjail.rsCanonicalises the path and rejects escapes outside the workspace root before any I/O happens.
- Session cache
hit → ~13 tokensContent-addressed lookup keyed by path + mtime/hash. Unchanged files collapse to a stub instead of re-sending content.
- AST extraction
26 languagestree-sitter parses the file into a syntax tree: signatures, imports, call edges — Lua, Luau, Kotlin and GDScript are graph-indexed too. Regex fallback for unsupported languages.
- Mode selection
10 modesauto picks the optimal of 10 read modes (full, map, signatures, diff, task, reference, aggressive, entropy, lines:N-M) from task intent and file size; structure_first biases cold medium-file code reads toward map, and a file flagged suspect on a fix task is forced to full.
- Compression
adaptive thresholdsShannon-entropy line filtering, U-curve attention placement (LITM), TF-IDF codebook and query-conditioned Information-Bottleneck fusion — an anti-inflation guard ships the file verbatim whenever framing would cost more tokens than the raw bytes.
- Token accounting
core/tokens.rsExact tiktoken counts (o200k_base; cl100k_base approximation for Claude-family models) on input and output.
- Ledger + stats
savings sign / verify-batchSavings are appended to the local ledger (Ed25519-signable), stats and the gain score update, the result streams back.
lean-ctx -c "cargo test" · IDE bash hook Entrambi i percorsi terminano nello stesso registro: ogni evento di compressione viene contato con matematica esatta del tokenizer e alimenta gain, il dashboard e il registro dei risparmi firmati.
Scheda dati di ingegneria
Le tabelle di riferimento dietro i disegni: ogni superficie con il suo trasporto e ciclo di vita, l'layout su disco, gli strati di apprendimento adattivo e i confini di sicurezza che il runtime applica.
AModello di processo
Tutte le superfici sono lo stesso binario in ruoli diversi. Nulla richiede una connessione cloud; tutto è vincolato local-first.
| REF | SURFACE | TRANSPORT | ENDPOINT | LIFECYCLE | COMANDO |
|---|---|---|---|---|---|
| 01 | MCP server (stdio) | JSON-RPC over stdin/stdout | spawned per editor session | child process of the editor | lean-ctx |
| 02 | MCP server (HTTP) | MCP Streamable HTTP | localhost, configurable --host/--port | foreground or service | lean-ctx serve |
| 03 | IPC daemon | Unix Domain Socket | OS data dir, e.g. ~/Library/Application Support/lean-ctx/daemon.sock | launchd / systemd autostart | lean-ctx serve --daemon |
| 04 | Shell hook | process exec, compressed stdout | wraps IDE bash calls + interactive shells | per command | lean-ctx -c "<cmd>" |
| 05 | API proxy | HTTP (LLM API pass-through) | localhost:4444 (default) | on demand | lean-ctx proxy start |
| 06 | Web dashboard | HTTP + bearer token | localhost:3333 (default, --port) | on demand | lean-ctx dashboard |
| 07 | Terminal UI | TTY (in-place redraw) | live event stream / 1 s refresh | interactive | lean-ctx watch · gain --live |
BLayout dello storage — directory XDG locali
Lo stato persistente consiste in file semplici nelle directory base XDG: ispezionabili, esportabili, eliminabili. Nessun database nascosto oltre queste cartelle locali.
| ARTIFACTO | FORM | SCOPO |
|---|---|---|
config.toml | TOML | Single config file — integration mode, compression, providers, opt-outs (config dir) |
cache/ | content-addressed | Session file cache; unchanged re-reads collapse to ~13-token stubs (cache dir) |
bm25 index | inverted index | Lexical search over code chunks + provider documents (data dir) |
context_graph/ | property graph | Imports, calls, types across files and repos — powers map mode + deep queries (data dir) |
knowledge | SQLite | Persistent facts, decisions, rooms — recalled across sessions, CCP (data dir) |
savings ledger | append-only JSONL | Every compression event; Ed25519-signable for audit (data dir) |
litm_calibration.json | JSON | Learned context-position hit rates (lost-in-the-middle calibration) (cache dir) |
events.jsonl | event stream | Live feed consumed by watch, dashboard and efficacy reports (state dir) |
CLivelli di apprendimento adattivo
Sette meccanismi di apprendimento online regolano la compressione in base al tuo utilizzo reale, localmente, da segnali di qualità come rimbalzi e fallimenti di modifica. Approfondimento: Apprendimento Adattivo →
- L1 Adaptive thresholds Online-learned compression aggressiveness from quality signals (bounces, edit failures, clean runs)
- L2 LITM calibration Empirical placement of critical context at positions the model actually attends to
- L3 Stigmergic scent field Multi-agent coordination via decaying markers: claimed, done, stuck, hot, avoid
- L4 Delta playbook Incremental checkpoint snapshots that survive context compaction
- L5 Query-conditioned IB Information-Bottleneck compression fused with query relevance
- L6 Theta-gamma chunking Wakeup facts grouped in attention-friendly bursts
- L7 Semantic dedup Likelihood-scored redundancy filtering across the session
DConfini di sicurezza
Garanzie rigide applicate nel runtime. Modello di sicurezza →
- PathJail Every file access is canonicalised and confined to the workspace root
- IDE config-dir jail Home-level IDE/agent config dirs (~/.claude, ~/.codex, ~/.codebuddy, …) are writable only when allow_ide_config_dirs is opted in; otherwise PathJail blocks them
- Shell allowlist Deny-by-default command policy for agent-issued shell executions
- Local-first All processing on-device; dashboard binds to localhost and requires a bearer token
- Signed evidence Savings ledger entries are Ed25519-signable and batch-verifiable
Un binario. Tre modi per entrare.
LeanCTX seleziona automaticamente la modalità di integrazione ottimale per ogni agente: CLI-Redirect guida il CLI di LeanCTX attraverso le regole dell'editor con zero overhead MCP, Hybrid combina letture memorizzate MCP con hook di compressione shell e Full MCP fornisce l'accesso massimo agli strumenti per gli editor basati su protocollo.
lean-ctx -c / read / grep MCP cache + CLI shell/search 81 tools via MCP + lazy tool set In ogni caso, LeanCTX seleziona automaticamente la modalità giusta per il tuo editor. Vedi tutti i {count}+ strumenti supportati
Sempre attivo. Sempre tuo.
Un piccolo servizio in background mantiene la tua sessione calda, in modo che i cache hit siano istantanei e la memoria sia sempre disponibile. Si avvia automaticamente durante l'installazione, si riavvia quando aggiorni e si pulisce da solo, nulla da gestire.
Ogni capacità, un singolo binario.
Tutto ciò che c'è tra il tuo codice e l'AI, gestito.
Smart I/O
Letture deterministiche, compressione shell, ricerca, visibilità contesto completa + 99% meno token
Compressione delle richieste
Un proxy locale opzionale comprime ogni richiesta al modello — prompt di sistema, cronologia e risultati degli strumenti — sicuro per il prompt-cache.
Intelligence
Instradamento delle intenzioni, selezione della modalità, pipeline adattiva
Memory
Sessioni, conoscenza del progetto, grafici, passaggi di consegne
Governance
Ruoli, budget, SLO, porte di flusso di lavoro, politiche
Verification
Prove formali Lean4, verifica basata su claim, Livelli di Qualità 0-4
Integrations
MCP, HTTP, SDK, 29+ IDE, Cloud, Team Server
Shared Sessions
Condivisione sessioni basata su workspace e canali tra agent
Context Bus
Stream di eventi in tempo reale per i cambiamenti di contesto tramite SSE
SDK & API
TypeScript SDK e REST API per integrazioni esterne
Ogni output è accompagnato da prove
LeanCTX genera artefatti di prova per ogni sessione: quali file sono stati letti, cosa è stato compresso, quali controlli sono passati e come sono stati spesi i token. Ciò rende il lavoro AI verificabile, riproducibile e affidabile.
LeanCTX (acronimo di Lean Context) è lo strato open-source di context engineering per gli agenti AI. Un singolo binario Rust locale decide cosa leggono gli agenti (10 modalità di lettura, 60–90% meno token, riletture in cache di ~13 token), ricorda ciò che apprendono (sessioni persistenti, grafo della conoscenza), protegge ciò che toccano (PathJail, cancellazione di segreti, budget, rilevamento di injection), dimostra ciò che salvano (registro firmato Ed25519, benchmark riproducibile) e riproduce ciò che hanno visto (snapshot contestuali firmati e ancorati a git che puoi ripristinare o condividere); un proxy locale opzionale comprime ciò che inviano — il prompt di sistema, la cronologia e l'output degli strumenti di ogni richiesta, sicuro per il cache del prompt sulla rete. La compressione — lato lettura e lato trasmissione — è uno dei cinque sottosistemi, e ogni originale rimane localmente recuperabile. Funziona con oltre 30 strumenti AI per coding tramite MCP e hook shell; si integra in qualsiasi agente tramite un'API versionata /v1 con SDK Python, TypeScript e Rust. L'uso locale è gratuito per sempre, garantito da CI.
Leggi la storia completa