# 04 — lean-ctx v3.9.18: current design (https://jackin.tailrocks.com/research/context/tools/04-leanctx-design/) ## Summary [#summary] lean-ctx is an integrated context runtime rather than a single compressor, giving it broad reach but also the largest behavioral and ownership surface. Cutoff: **2026-08-12**. Current stable: [v3.9.18](https://github.com/yvgude/lean-ctx/releases/tag/v3.9.18), released 2026-08-08. lean-ctx—branded LeanCTX upstream—is an integrated **context runtime**, not one compressor. It controls file views, shell observations, search, code structure, memory, retrieval, policy, recovery, and measurement through one local system. Current v3.9.18 enables a broader cognitive orchestration layer by default. ## Question and scope [#question-and-scope] How does lean-ctx v3.9.18 coordinate retrieval, compression, memory, and policy, and what ownership risks follow? ## Method [#method] The review fixes lean-ctx to v3.9.18, maps its retrieval, compression, memory, policy, and recovery surfaces from upstream evidence, and records where outcome attribution remains weak. ## Findings [#findings] ### Current facts [#current-facts] | Field | Current value | | ----------------- | -------------------------------------------------------------------------------------------------------------- | | Repository | [yvgude/lean-ctx](https://github.com/yvgude/lean-ctx) | | Stable release | [v3.9.18](https://github.com/yvgude/lean-ctx/releases/tag/v3.9.18) | | Adoption snapshot | 3,568 stars / 22 subscribers / 323 forks / 8 open issues and PRs | | Current scope | 83 MCP tools, 30+ agent integrations, 95+ shell patterns, 10 read modes | | Core mechanisms | Tree-sitter views, BM25/property graph, cached handles, archive/recovery, memory, proxy, policy, signed ledger | | Form factor | Rust release artifacts, daemon, SQLite state, MCP/hook/proxy/dashboard surfaces | | License | Apache-2.0 | Metadata source: [GitHub API](https://api.github.com/repos/yvgude/lean-ctx). Current capability counts: [README](https://github.com/yvgude/lean-ctx). ### Current architecture [#current-architecture] ```text repository reads ── map/signatures/lines/full/cache handles ─┐ shell commands ─── deterministic output patterns ───────────┤ search/code ────── BM25 + graph + symbols/LSP ──────────────┤ history ────────── optional proxy + memory ─────────────────┤→ agent context recovery ───────── archive + ctx_expand/raw reads ──────────┤ policy/ledger ─── permissions, budgets, signed events ──────┘ ``` The key benefit is read prevention. A map, signature view, graph query, or cached stub can avoid sending an entire source file. That is architecturally different from compressing bytes after a broad read. Full and bounded modes remain necessary before exact edits. ### What v3.9.18 currently adds [#what-v3918-currently-adds] * Full cognitive mode enabled by default. * `ctx_cognitive`, bringing the current MCP count to 83. * FSRS-style spaced repetition, graph expansion, token allocation, learned verbosity, prefetch, anti-interrupt behavior, and stigmergy features. * Enterprise initialization, policy/sidecar gates, protocol work, and architecture decision records. * Fixes for zsh `nomatch`, rerooting, atomic patch batches, unknown MCP methods, file URIs, PowerShell injection, and a shadow-mode permission bypass. Release source: [v3.9.18 notes](https://github.com/yvgude/lean-ctx/releases/tag/v3.9.18). ### Current evidence [#current-evidence] The latest independent field report found is [Wavect's 2026-07-27 report](https://wavect.io/blog/lean-ctx-agency-experience/): 64.1% less tracked context, 92.7% MCP compression, and most savings attributed to MCP file-read traffic. The report explicitly labels itself observational, not a controlled productivity study, and does not identify an exact lean-ctx version. It therefore supports the current workflow pattern—compressed discovery, raw verification—but does **not** prove v3.9.18's task-level effect. No controlled independent accepted-task benchmark explicitly testing **v3.9.18** was found at the cutoff. Current vendor percentages remain first-party. ## Implications for jackin❯ [#implications-for-jackin] ### Benefits [#benefits] * Broadest integrated reach of the named set. * Selective structural reads can prevent large observations instead of summarizing them. * Deterministic core; optional embeddings/proxy surfaces can remain disabled. * Exact recovery through archive expansion and raw/bounded reads. * Persistent graph and memory support long or multi-agent sessions. * Explicit policy, savings, and verification machinery. * Current release closes several correctness and security defects. ### Best fit [#best-fit] Test lean-ctx on large repositories and long sessions with repeated navigation, source rereads, graph questions, handoffs, or persistent context. Use maps/signatures/search for discovery, then require full or bounded reads, real diffs, tests, and review before exact or high-risk changes. Avoid it when the task is small, operational minimalism matters, or policy cannot accept broad user-scope integration and persistent local state. ### Current verdict [#current-verdict] lean-ctx v3.9.18 is the most capable context-management system here and the least comparable to a small filter. It may provide the largest benefit when repeated repository reads are the bottleneck, but that claim needs a current controlled A/B. Status: **best broad runtime for measured repository-context problems; excessive for narrow token waste**. Next: [05 — Current objective comparison](/research/context/tools/05-head-to-head/). ## Limitations and unknowns [#limitations-and-unknowns] ### Costs and risks [#costs-and-risks] * Widest trusted and operational surface: daemon, databases, dashboard, MCP schema, hooks, proxy, agent integrations, and policies. * Current release archives are roughly 22–24 MB compressed; installed/runtime state is larger and persistent. * The README states a fixed session overhead around 2.1k tokens; savings must exceed it. * Compressed maps/signatures are discovery views, not authoritative source for exact edits. * Full cognitive mode adds adaptive behavior by default, increasing causal complexity and making A/B attribution harder. * Setup touches many agent configurations; inspect dry-run/current installer behavior before user-scope writes. * Proxy mode expands the integrity and cache-risk boundary. * Current release notes contain a self-comparison “Full Changelog” link, a documentation-quality defect. ## Sources [#sources] Evidence and repository references are cited inline beside the claims they support. ## Related work [#related-work] * [Token-optimization tools dossier](/research/context/tools/) * [Token-optimization techniques](/research/context/techniques/) * [Context engine](/research/context/engine/)