O sistema que decide
o que sua IA vê.
A camada de context engineering para agentes de IAUm binário local em ambos os lados do modelo. LeanCTX percebe, comprime, lembra, roteia e governa o ciclo de vida completo do contexto de IA, desde leituras de arquivos até saídas verificadas.
O que é uma Camada de Contexto Cognitivo?
Uma Camada de Contexto Cognitivo é a infraestrutura entre suas ferramentas de IA e sua base de código. Ela controla quais arquivos são lidos, como a saída é comprimida, qual conhecimento persiste em sessões e se os resultados atendem aos padrões de qualidade antes da entrega.
O desenho de construção
A topologia do processo do binário enviado: sete pontos de entrada, um tempo de execução, um conjunto de lojas locais. Cada caixa abaixo mapeia para um módulo, porta ou arquivo real no disco.
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 O que acontece com uma leitura única
A Sheet 2 rastreia um pedido através do tempo de execução, estágio por estágio, incluindo o curto-circuito de cache que torna as leituras repetidas quase gratuitas. O caminho do shell é executado em paralelo com a mesma contabilidade.
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 Ambos os caminhos terminam no mesmo ledger: cada evento de compressão é contado com matemática exata do tokenizador e alimenta gain, o dashboard e o ledger de economias assinadas.
Planilha de dados de engenharia
As tabelas de referência por trás dos desenhos: cada superfície com seu transporte e ciclo de vida, o layout no disco, as camadas de aprendizado adaptativo e os limites de segurança que o tempo de execução impõe.
AModelo de processo
Todas as superfícies são o mesmo binário em papéis diferentes. Nada requer conexão em nuvem; tudo é local-first.
| REF | SURFACE | TRANSPORT | ENDPOINT | LIFECYCLE | COMANDO |
|---|---|---|---|---|---|
| 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 |
BLayout de armazenamento — diretórios XDG locais
O estado persistente são arquivos simples sob os diretórios base XDG: inspecionáveis, exportáveis, deletáveis. Nenhum banco de dados oculto além dessas pastas locais.
| ARTIFACTO | FORM | PROPÓSITO |
|---|---|---|
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) |
CCamadas de aprendizado adaptativo
Sete mecanismos de aprendizado online ajustam a compressão ao seu uso real, localmente, a partir sinais de qualidade como bounces e falhas de edição. Aprofundamento: Aprendizado Adaptativo →
- 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
DLimites de segurança
Garantias rígidas aplicadas no tempo de execução. Modelo de segurança →
- 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
Um binário. Três formas de entrada.
LeanCTX seleciona automaticamente o modo de integração ideal para cada agente: CLI-Redirect direciona a CLI do LeanCTX através de regras de editor com zero overhead MCP, Hybrid combina leituras em cache MCP com hooks de compressão shell e Full MCP fornece acesso máximo às ferramentas para editores apenas de protocolo.
lean-ctx -c / read / grep MCP cache + CLI shell/search 81 tools via MCP + lazy tool set De qualquer maneira, LeanCTX escolhe o modo certo para seu editor, automaticamente. Veja todas as mais de 30 ferramentas suportadas
Sempre ativo. Sempre seu.
Um pequeno serviço em segundo plano mantém sua sessão ativa, para que os acertos de cache sejam instantâneos e a memória esteja sempre disponível. Ele inicia automaticamente durante a configuração, reinicia quando você atualiza e se limpa sozinho, nada para gerenciar.
Cada Capacidade, Um Binário.
Tudo entre o seu código e a IA, gerenciado.
Smart I/O
Leituras determinísticas, compressão de shell, busca, visibilidade total do contexto + 99% menos tokens
Compressão de Requisição
Um proxy local opcional comprime cada requisição ao modelo — prompt do sistema, histórico e resultados das ferramentas — seguro contra cache de prompts.
Intelligence
Roteamento de intenção, seleção de modo, pipeline adaptativo
Memory
Sessões, conhecimento do projeto, grafos, passagens
Governance
Funções, orçamentos, SLOs, portões de fluxo de trabalho, políticas
Verification
Provas formais Lean4, verificação baseada em afirmações, Níveis de Qualidade 0-4
Integrations
MCP, HTTP, SDK, 29+ IDEs, Cloud, Team Server
Shared Sessions
Compartilhamento de sessão baseado em workspace e canal entre agentes
Context Bus
Fluxo de eventos em tempo real para mudanças de contexto via SSE
SDK & API
SDK TypeScript e API REST para integrações externas
Todo output carrega prova
LeanCTX gera artefatos de prova para cada sessão: quais arquivos foram lidos, o que foi comprimido, quais verificações passaram e como os tokens foram gastos. Isso torna o trabalho da IA auditável, reproduzível e confiável.
LeanCTX (abreviação de Lean Context) é a camada open-source de context engineering para agentes de IA. Um binário local Rust decide o que os agentes leem (10 modos de leitura, 60–90% menos tokens, re-leituras em cache de ~13 tokens), lembra o que eles aprendem (sessões persistentes, grafo de conhecimento), protege o que eles tocam (PathJail, redação de segredos, orçamentos, detecção de injeção), prova o que eles salvam (ledger assinado Ed25519, benchmark reprodutível) e reproduz o que viram (snapshots de contexto assinados e ancorados em git que você pode restaurar ou compartilhar); um proxy local opcional comprime o que eles enviam — prompt do sistema, histórico e saída da ferramenta de cada requisição, seguro para cache de prompts na linha. A compressão — no lado da leitura e na linha — é um dos cinco subsistemas, e todo original permanece recuperável localmente. Funciona com mais de 30 ferramentas de codificação de IA via MCP e hooks de shell; incorpora em qualquer agente via API versionada /v1 com SDKs Python, TypeScript e Rust. O uso local é grátis para sempre, garantido por CI.
Leia a história completa