아키텍처
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.
배포된 바이너리의 프로세스 토폴로지: 7개의 진입점, 1개의 런타임, 1세트의 로컬 스토어. 아래의 모든 박스는 실제 모듈, 포트 또는 디스크 파일에 매핑됩니다.
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.
Sheet 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.
도면 뒤의 참조 테이블: 모든 표면과 그 운송 및 수명 주기, 디스크 상 레이아웃, 적응형 학습 계층, 그리고 런타임이 강제하는 보안 경계.<br>
A프로세스 모델
모든 표면은 다른 역할을 하는 동일한 바이너리입니다. 클라우드 연결이 필요하지 않으며, 모든 것이 로컬 우선으로 바인딩됩니다.
| 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 디렉토리
영구 상태는 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적응형 학습 레이어
7가지 온라인 학습 메커니즘이 바운스 및 편집 실패와 같은 품질 신호를 기반으로 사용자의 실제 사용에 맞춰 압축을 조정합니다. 심층 분석: 적응형 학습 →
- 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.