आर्किटेक्चर
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.
शिप किए गए बाइनरी की प्रक्रिया टोपोलॉजी: सात एंट्री पॉइंट, एक रनटाइम, स्थानीय स्टोरों का एक सेट। नीचे हर बॉक्स एक वास्तविक मॉड्यूल, पोर्ट या डिस्क पर फ़ाइल से मैप होता है।
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.
डेटा प्रवाह Stage by stage.
शीट 2 रनटाइम के माध्यम से एक अनुरोध को चरण दर चरण ट्रैक करती है, जिसमें कैश शॉर्ट-सर्किट शामिल है जो बार-बार रीड्स को लगभग मुफ्त बना देता है। शेल पाथ उसी अकाउंटिंग के साथ समानांतर में चलता है।
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 दोनों पथ एक ही लेजर पर समाप्त होते हैं: हर संपीड़न घटना की गिनती सटीक टोकनाइज़र गणित के साथ होती है और gain, डैशबोर्ड और हस्ताक्षरित बचत लेजर को फीड करती है।
संपीड़न 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.
ड्रॉइंग के पीछे संदर्भ तालिकाएँ: हर सतह अपने परिवहन और जीवनचक्र के साथ, ऑन-डिस्क लेआउट, अनुकूली-सीखने वाली परतें, और सुरक्षा सीमाएँ जो रनटाइम लागू करता है।
Aप्रोसेस मॉडल
सभी सतहें विभिन्न भूमिकाओं में एक ही बाइनरी हैं। किसी को क्लाउड कनेक्शन की आवश्यकता नहीं है; सब कुछ स्थानीय-प्रथम (local-first) से बंधा हुआ है।
| REF | SURFACE | TRANSPORT | ENDPOINT | LIFECYCLE | कमांड |
|---|---|---|---|---|---|
| 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 |
Bस्टोरेज लेआउट — लोकल XDG डायरेक्टरीज़
स्थायी स्थिति (persistent state) XDG बेस डायरेक्टरीज़ के तहत सादे फ़ाइलें हैं: निरीक्षण योग्य, निर्यात करने योग्य, हटाने योग्य। इन स्थानीय फ़ोल्डरों से परे कोई छिपे हुए डेटाबेस नहीं।
| आर्टिफैक्ट | FORM | उद्देश्य |
|---|---|---|
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) |
Cएडैप्टिव-लर्निंग लेयर्स
सात ऑनलाइन-लर्निंग मैकेनिज्म बౌन्सेस और एडिट फेलियर्स जैसे गुणवत्ता संकेतों के आधार पर आपके वास्तविक उपयोग के लिए संपीड़न (compression) को स्थानीय रूप से ट्यून करते हैं। गहन अध्ययन: एडैप्टिव लर्निंग →
- 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
Dसुरक्षा सीमाएँ
रनटाइम में लागू कठोर गारंटी। सिक्योरिटी मॉडल →
- 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
Explore thesource.
LeanCTX is open source. Read the code, understand the design, contribute.