架构

The architecture.

One Rust binary. Five subsystems. Zero cloud dependencies. Every box below maps to a real module, port, or file on disk.

开始使用 View Benchmarks

System topology.

已发布二进制文件的流程拓扑：七个入口点、一个运行时、一套本地存储。下面每个方框都对应于磁盘上的真实模块、端口或文件。

代理客户端

CursorClaude CodeCopilotWindsurfCodexGemini CLI30+ 代理程序

表面 — 入口点

01 MCP server (stdio) lean-ctx

02 MCP server (HTTP) lean-ctx serve

03 IPC daemon lean-ctx serve --daemon

04 Shell hook lean-ctx -c "<cmd>"

05 API proxy lean-ctx proxy start

06 Web dashboard lean-ctx dashboard

07 Terminal UI lean-ctx watch · gain --live

核心运行时 — 单个 Rust 二进制文件

工具分派 81 MCP 工具 · 惰性工具集 (5 个统一)

模式引擎 95+ shell 模式 · git, cargo, npm, docker, kubectl, …

读取管道 10 读取模式 · 每请求自动选择

AST 层 tree-sitter · 26 种语言 · regex 回退

压缩熵 · 注意力 U 曲线 · TF-IDF · query-IB

自适应学习 7 个在线学习层 · 功效报告

本地存储 — XDG 目录

会话缓存BM25 索引属性图知识库 (SQLite)节省账本 (Ed25519)config.toml

外部提供者

GitHubGitLabJira (+ OAuth)PostgresMCP bridgeConfig REST (Linear, …)

BM25 chunksgraph edgesknowledge factscache entries

一个二进制文件，七个入口点。表面共享相同的运行时和本地存储——提供商数据被整合到文件读取使用的相同索引中。

One binary. Five subsystems. No cloud required.

数据流 Stage by stage.

Sheet 2 跟踪了一个请求在运行时中的各个阶段，包括使重复读取几乎免费的缓存短路机制。shell 路径以相同的计费方式并行运行。

读取路径 ctx_read(path, mode) · lean-ctx read

PathJail core/pathjail.rs

Canonicalises the path and rejects escapes outside the workspace root before any I/O happens.
Session cache hit → ~13 tokens

Content-addressed lookup keyed by path + mtime/hash. Unchanged files collapse to a stub instead of re-sending content.
AST extraction 26 languages

tree-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 modes

auto 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 thresholds

Shannon-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.rs

Exact tiktoken counts (o200k_base; cl100k_base approximation for Claude-family models) on input and output.
Ledger + stats savings sign / verify-batch

Savings are appended to the local ledger (Ed25519-signable), stats and the gain score update, the result streams back.

shell 路径 lean-ctx -c "cargo test" · IDE bash hook

H1 Allowlist 默认拒绝策略

H2 执行真实命令，真实退出代码

H3 模式引擎 95+ 手工设计的模式

H4 压缩后的 stdout 错误总是保留下来

两个路径都指向同一个账本：每次压缩事件都会用精确的 tokenizer 数学进行计数，并记录在 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 modes

ctx_read — mode selection auto

Available 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 range

Selected: 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 model

lean-ctx doctor all passed

✓Cache 47 entries · 73% hit rate

✓Knowledge 342 nodes · 1,205 edges

✓Agent bus 3 agents registered

✓PathJail root: /Users/dev/project

✓Allowlist 14 allow, 6 deny

✓Redaction .env, credentials.*

✓TOCTOU open-handle verify active

✓Ledger Ed25519-signed · 0 violations

Engineering data sheet.

图纸背后的参考表格：每个表面及其传输和生命周期、磁盘布局、自适应学习层以及运行时强制执行的安全边界。

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自适应学习层

七种在线学习机制根据跳出率和编辑失败等质量信号，在本地对压缩进行调整，以匹配您的实际使用情况。深入了解：自适应学习 →

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.

View on GitHub Read the docs →