什么是认知上下文层？
认知上下文层是您的 AI 工具和代码库之间的基础设施。它控制哪些文件被读取、如何压缩输出、哪些知识跨会话持久化，以及交付结果是否达到质量标准。
构建图纸
已发布二进制文件的流程拓扑：七个入口点、一个运行时、一套本地存储。下面每个方框都对应于磁盘上的真实模块、端口或文件。
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 单次读取的流程
Sheet 2 跟踪了一个请求在运行时中的各个阶段，包括使重复读取几乎免费的缓存短路机制。shell 路径以相同的计费方式并行运行。
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 两个路径都指向同一个账本：每次压缩事件都会用精确的 tokenizer 数学进行计数，并记录在 gain、仪表板和签名的节约账本中。
工程数据表
图纸背后的参考表格：每个表面及其传输和生命周期、磁盘布局、自适应学习层以及运行时强制执行的安全边界。
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
一个二进制文件。三种接入方式。
LeanCTX 为每个代理自动选择最佳的集成模式：CLI-Redirect 通过编辑器规则驱动 LeanCTX CLI，零 MCP 开销；Hybrid 结合了 MCP 缓存读取和 shell 压缩钩；Full MCP 为仅支持协议的编辑器提供最大的工具访问权限。
lean-ctx -c / read / grep MCP cache + CLI shell/search 81 tools via MCP + lazy tool set 无论哪种方式，LeanCTX都会为您的编辑器自动选择合适的模式。 查看所有 30+ 支持的工具
始终在线。永远属于您。
一个小型后台服务保持您的会话活跃，从而使缓存命中瞬间完成，内存始终可用。它在设置期间自动启动，在您更新时自我重启，并在完成后自行清理，无需管理。
每项能力，一个二进制文件。
处理您代码和 AI 之间的所有内容。
Smart I/O
确定性读取、Shell 压缩、搜索、完整的上下文可见性 + 减少 99% 的 tokens
请求压缩
一个可选的本地代理会压缩发送给模型的每个请求——系统提示、历史记录和工具结果——防范提示缓存污染。
Intelligence
意图路由、模式选择、自适应管道
Memory
会话、项目知识、图谱、交接
Governance
角色、预算、SLO、工作流门禁、策略
Verification
Lean4形式证明、基于声明的验证、质量等级 0-4
Integrations
MCP、HTTP、SDK、29+ IDEs、云端、团队服务器
Shared Sessions
跨代理的工作区和频道会话共享
Context Bus
通过 SSE 的实时上下文变更事件流
SDK & API
用于外部集成的 TypeScript SDK 和 REST API
每个输出都带有证明
LeanCTX 为每次会话生成证明工件：读取了哪些文件，压缩了什么内容，通过了哪些检查，以及消耗了多少 token。这使得 AI 工作可审计、可重放和值得信赖。
LeanCTX（“Lean Context”的缩写）是用于 AI agents 的开源 context engineering layer。一个本地 Rust 二进制文件决定了 agents 读取什么（10 种读取模式，减少 60–90% 的 tokens，~13 个 token 的缓存重读），记住它们学到什么（持久会话、知识图谱），保护它们触及什么（PathJail、秘密脱敏、预算、注入检测），证明它们保存了什么（Ed25519 签名账本、可复现基准），并重放它们看到什么（git-anchored、可恢复或分享的签名 context 快照）；一个可选的本地代理压缩它们发送的内容——每个请求的系统提示、历史记录和工具输出，在网络传输中保证 prompt-cache 安全。压缩——无论是读取侧还是网络侧——是五个子系统之一，并且所有原始数据都可以在本地检索到。通过 MCP 和 shell hooks 支持 30+ AI coding tools；可通过 Python、TypeScript 和 Rust SDKs 的版本化 /v1 API 嵌入任何 agent。本地使用永久免费，由 CI 强制执行。
阅读完整故事