# lean-ctx

> The context-engineering layer for AI agents — one local Rust binary that decides what your agents read, compresses what they send to the model, remembers what they learn, guards what they touch, and proves what they save. Deterministic and prompt-cache-safe by contract; 60–90% fewer tokens.

lean-ctx (LeanCTX, "Lean Context") runs between your AI agents and everything they touch — code, shell, data, and the model itself. It exposes 81 MCP tools plus a shell hook (the read path) and an optional local request proxy (the wire path) that compresses every request — system prompt, history and tool results — without breaking provider prompt caches. Compression is reversible: pruned or truncated content moves to a content-addressed store with a deterministic handle, so the model can always recover the original bytes. 100% local, no telemetry by default, Apache-2.0.

Key properties for an LLM evaluating lean-ctx:

- Deterministic output: the same `(input, mode)` yields byte-identical text, so Anthropic (90%) and OpenAI (50%) prompt-cache discounts survive compression (contract #498).
- Reversible (CCR): five recovery paths — `ctx_expand`, `ctx_retrieve`, proxy path-handle CCR, in-band `<lc_expand:HASH>` markers, and `GET /v1/references/{id}`.
- Tree-sitter AST parsing for 26 languages; 10 file read modes; 95+ shell-output compression patterns.
- Persistent temporal knowledge graph + multi-edge code property graph (impact analysis, ranked search).
- Drop-in `compress(messages, model)` SDK (Python + TypeScript) with LiteLLM / LangChain / Vercel AI SDK adapters.

## Docs

- [Getting started](https://leanctx.com/docs/getting-started): install, onboard, verify.
- [What is LeanCTX](https://leanctx.com/what-is-leanctx/): the four dimensions of context (compression, routing, memory, verification).
- [Tools reference](https://leanctx.com/docs/tools/): every `ctx_*` MCP tool.
- [CLI reference](https://leanctx.com/docs/cli-reference/): every `lean-ctx` command.
- [API reference](https://leanctx.com/docs/api-reference/): the `/v1` HTTP tool, event and session API.
- [Reference index](https://github.com/yvgude/lean-ctx/blob/main/docs/reference/README.md): 11 user-journey guides + CLI/MCP/config appendices.

## SDKs & integration

- [compress() SDK cookbook](https://github.com/yvgude/lean-ctx/blob/main/docs/guides/compress-sdk.md): drop-in prompt compression and framework adapters.
- [lean-ctx-sdk (PyPI)](https://pypi.org/project/lean-ctx-sdk/) · [lean-ctx-sdk (npm)](https://www.npmjs.com/package/lean-ctx-sdk): `compress(messages, model)`.
- [lean-ctx-client (PyPI)](https://pypi.org/project/lean-ctx-client/): thin `/v1` contract client (Python/TS/Rust).
- [Monorepo guide](https://github.com/yvgude/lean-ctx/blob/main/docs/guides/monorepo.md): multi-repo serving.

## Comparisons

- [Comparisons index](https://github.com/yvgude/lean-ctx/blob/main/docs/comparisons/README.md): fact-based matrix vs other context/memory tools.
- [lean-ctx vs Headroom](https://github.com/yvgude/lean-ctx/blob/main/docs/comparisons/vs-headroom.md): deterministic, prompt-cache-safe, reversible `compress()` + full context layer vs an ML compression library.

## Reference & internals

- [Generated config keys](https://github.com/yvgude/lean-ctx/blob/main/docs/reference/generated/config-keys.md): every `config.toml` key + env override.
- [Generated MCP tools](https://github.com/yvgude/lean-ctx/blob/main/docs/reference/generated/mcp-tools.md): all 80 tools, generated from the registry.
- [ARCHITECTURE](https://github.com/yvgude/lean-ctx/blob/main/ARCHITECTURE.md): how the read path, wire path, graphs and memory fit together.
- [CONTRACTS](https://github.com/yvgude/lean-ctx/blob/main/CONTRACTS.md): 29 published stability contracts, CI-enforced.
- [VISION](https://github.com/yvgude/lean-ctx/blob/main/VISION.md): roadmap toward a team-wide cognitive context layer.

## Optional

- [Benchmarks](https://github.com/yvgude/lean-ctx/blob/main/BENCHMARKS.md): reproduced compression numbers (`lean-ctx benchmark report .`).
- [Changelog](https://github.com/yvgude/lean-ctx/blob/main/CHANGELOG.md): release history (Keep a Changelog).
- [Security](https://github.com/yvgude/lean-ctx/blob/main/SECURITY.md): hardening and disclosure policy.
- [Pricing & Cloud](https://leanctx.com/pricing/): local use is free forever.
