# lean-ctx

> The local context-engineering layer for AI agents — select, shape, reuse, recover, and inspect context before inference. Deterministic, prompt-cache-aware representations with local, auditable measurements.

lean-ctx (LeanCTX, "Lean Context") exposes a broad MCP tool set plus a shell hook for local context operations. An optional local request proxy can shape supported request fields while preserving stable prefixes for provider prompt caches. Pruned or truncated content can be recovered from content-addressed references. Processing is local by default; explicitly submitted feedback and enabled integrations are the exceptions. Apache-2.0.

Key properties for an LLM evaluating lean-ctx:

- Deterministic output: the same `(input, mode)` yields byte-identical text so stable prefixes remain eligible for provider prompt caching (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).
- Supported custom-agent SDK: `thinkery-leanctx-sdk` for Python. It uses the local LeanCTX Engine; model calls and agent orchestration remain application-owned.

## 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

- [Supported Agent SDK](https://github.com/Thinkery-AG/leanctx-sdk) · [PyPI](https://pypi.org/project/thinkery-leanctx-sdk/): Python context lifecycle today; the `AgentContext` tool API follows Engine 3.10.1.
- [SDK surface and boundaries](https://github.com/yvgude/lean-ctx/blob/main/docs/reference/sdk-surface.md): supported SDK, Engine requirement, and retired package names.
- [Low-level HTTP examples](https://github.com/yvgude/lean-ctx/blob/main/docs/guides/compress-sdk.md): direct Engine integration and framework adapters.
- [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): complete inventory 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.