The system that decides
what your AI sees.
The cognitive context layer between your AI and your codeOne local binary between your AI and your code. LeanCTX perceives, compresses, remembers, routes, and governs the complete lifecycle of AI context, from file reads to verified outputs.
What is a Cognitive Context Layer?
A Cognitive Context Layer is the infrastructure between your AI tools and your codebase. It controls what files are read, how output is compressed, what knowledge persists across sessions, and whether results meet quality standards before delivery.
The construction drawing
The process topology of the shipped binary: seven entry points, one runtime, one set of local stores. Every box below maps to a real module, port or file on disk.
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 What happens to a single read
Sheet 2 traces one request through the runtime, stage by stage, including the cache short-circuit that makes repeated reads nearly free. The shell path runs in parallel with the same accounting.
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
18 languagestree-sitter parses the file into a syntax tree: signatures, imports, call edges. 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.
- Compression
adaptive thresholdsShannon-entropy line filtering, U-curve attention placement (LITM), TF-IDF codebook and query-conditioned Information-Bottleneck fusion.
- 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
Both paths end in the same ledger: every compression event is counted with exact
tokenizer math and feeds gain, the dashboard and the signed savings ledger.
Engineering data sheet
The reference tables behind the drawings: every surface with its transport and lifecycle, the on-disk layout, the adaptive-learning layers, and the security boundaries the runtime enforces.
AProcess model
All surfaces are the same binary in different roles. Nothing requires a cloud connection; everything binds local-first.
| REF | SURFACE | TRANSPORT | ENDPOINT | LIFECYCLE | COMMAND |
|---|---|---|---|---|---|
| 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 |
BStorage layout — ~/.lean-ctx
Persistent state is plain files in your home directory: inspectable, exportable, deletable. No hidden databases outside this folder.
| ARTIFACT | FORM | PURPOSE |
|---|---|---|
config.toml | TOML | Single config file — integration mode, compression, providers, opt-outs |
cache/ | content-addressed | Session file cache; unchanged re-reads collapse to ~13-token stubs |
bm25 index | inverted index | Lexical search over code chunks + provider documents |
context_graph/ | property graph | Imports, calls, types across files and repos — powers map mode + deep queries |
knowledge | SQLite | Persistent facts, decisions, rooms — recalled across sessions (CCP) |
savings ledger | append-only JSONL | Every compression event; Ed25519-signable for audit |
litm_calibration.json | JSON | Learned context-position hit rates (lost-in-the-middle calibration) |
events.jsonl | event stream | Live feed consumed by watch, dashboard and efficacy reports |
CAdaptive-learning layers
Seven online-learning mechanisms tune compression to your real usage, locally, from quality signals like bounces and edit failures. Deep dive: Adaptive Learning →
- 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
DSecurity boundaries
Hard guarantees enforced in the runtime. Security model →
- PathJail Every file access is canonicalised and confined to the workspace root
- 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
One binary. Three ways in.
LeanCTX automatically selects the optimal integration mode for each agent: CLI-Redirect drives the LeanCTX CLI through editor rules with zero MCP overhead, Hybrid combines MCP cached reads with shell compression hooks, and Full MCP provides maximum tool access for protocol-only editors.
lean-ctx -c / read / grep MCP cache + CLI shell/search 76 tools via MCP + lazy tool set Either way, LeanCTX picks the right mode for your editor, automatically. See all 30+ supported tools
Always on. Always yours.
A small background service keeps your session warm, so cache hits are instant and memory is always there. It starts automatically during setup, restarts itself when you update, and cleans up after itself, nothing to manage.
Every Capability, One Binary.
Everything between your code and the AI, handled.
Smart I/O
Deterministic reads, shell compression, search, full context visibility + 99% fewer tokens
Intelligence
Intent routing, mode selection, adaptive pipeline
Memory
Sessions, project knowledge, graphs, handoffs
Governance
Roles, budgets, SLOs, workflow gates, policies
Verification
Lean4 formal proofs, claim-based verification, Quality Levels 0-4
Integrations
MCP, HTTP, SDK, 29+ IDEs, Cloud, Team Server
Shared Sessions
Workspace & channel-based session sharing across agents
Context Bus
Real-time event stream for context changes via SSE
SDK & API
TypeScript SDK and REST API for external integrations
Every output carries proof
LeanCTX generates proof artifacts for every session: which files were read, what was compressed, which checks passed, and how tokens were spent. This makes AI work auditable, replayable, and trustworthy.
LeanCTX (short for Lean Context) is the open-source context intelligence layer for AI agents. One local Rust binary decides what agents read (10 read modes, 60–90% fewer tokens, ~13-token cached re-reads), remembers what they learn (persistent sessions, knowledge graph), guards what they touch (PathJail, secret redaction, budgets, injection detection) and proves what they save (Ed25519-signed ledger, reproducible benchmark). Compression is one of five subsystems, and every original stays locally retrievable. Works with 30+ AI coding tools via MCP and shell hooks; embeds in any agent via a versioned /v1 API with Python, TypeScript and Rust SDKs. Local use is free forever, enforced by CI.
Read the full storyTake back control of your context.
One local binary between your AI and your code. LeanCTX perceives, compresses, remembers, routes, and governs the complete lifecycle of AI context, from file reads to verified outputs.