DOCSEARCHbyAlgolia
Submit Docs

LeanCTX Documentation

repository·main·Indexed 25 days ago

https://github.com/yvgude/lean-ctx

A context engineering layer for AI agents designed to optimize token usage, manage persistent memory, and provide a verifiable ledger for context. It includes the lean-ctx-client SDKs for Python, Rust, and TypeScript, enabling service discovery, tool execution, and SSE event subscriptions via a /v1 HTTP contract. The project also provides OCLA v1 verification for token and agent envelopes and a cookbook featuring a Memory Policy Playground and Knowledge Graph Explorer.

Tokens
263.8K
Snippets
629
Records
1.5K
Agent score
85%

What's inside LeanCTX

  1. Overview of LeanCTX

    main

    LeanCTX (Lean Context) is a context engineering layer for AI agents designed to optimize how agents interact with code, shell, and data. It acts as a local Rust binary that sits between your agents and their environment to:

    • Decide what agents read.
    • Compress data sent to models (system prompts, history, and tool results) to be prompt-cache-safe, reducing token usage by 60–90%.
    • Remember learned information via persistent session memory.
    • Guard access to sensitive data.
    • Verify saved information with a signed, verifiable savings ledger.

    It is model-agnostic and works with existing agents like Cursor, Claude Code, Copilot, Windsurf, Codex, and Gemini without requiring configuration changes.

  2. Overview of ctxpkg companion projects

    main

    LeanCTX utilizes the ctxpkg ecosystem for managing context:

    • ctxpkg.org: An open standard for signed, typed context packages using the .ctxpkg format.
    • ctxpkg.com: A registry and marketplace for discovering and using context packages.

  3. Overview of lean-ctx features

    main

    lean-ctx provides a broad suite of context engineering tools including:

    • Structural Intelligence: Knowledge graph (SQLite property graph), call graphs (multi-hop BFS), and architecture overviews (ctx_architecture).
    • Compression: 10 modes for file reads and 95+ patterns for shell output.
    • Memory: Temporal knowledge graph for session findings, decisions, and episodic/procedural memory.
    • Multi-Agent Support: Tools for handoffs (ctx_agent), communication (diary), and synchronization.
    • Governance & Observability: Real-time token tracking, budgets, SLOs, and context verification (ctx_proof, ctx_verify).
    • Repo Management: Repo packing via .ctxpkg bundles and PR packs.

  4. Understand Autonomy Drivers v1 (AutonomyDriversV1)

    main

    Autonomy Drivers v1 are deterministic helper drivers in LeanCTX designed to make workflows faster and more reliable without providing full autonomy. They standardize the use of Triggers, Guards (Budget/SLO/Boundary), and Proof/Reports.

    Key objectives include:

    • Deterministic behavior: Identical inputs and policies result in the same Driver-Plan.
    • Guarded execution: Uses Budget, SLO, and Boundary guards to prevent overfetching or excessive token burn.
    • Auditability: Driver-Reports record which drivers ran and why (bounded and redaction-safe).
    • Compatibility: Defaults remain conservative, with opt-in capabilities via Profiles.

  5. Understand the Quality Loop v1 feedback mechanism

    main

    The Quality Loop v1 is an experimental feedback mechanism that uses edit outcomes to adjust how LeanCTX selects read modes (e.g., compressed vs full). It specifically targets 'compression-correlated failures'—where an edit fails because the file was previously read in a compressed mode that omitted necessary context (like a function body).

    This mechanism uses two primary signals to improve future reads:

    1. Per-path one-shot escalation: If an edit fails due to compression, the next mode=auto resolution for that specific file path will return full mode. This escalation expires after 1 hour.
    2. Per-(extension × mode) risky penalty: If a specific file extension and read mode pair (e.g., .rs files in map mode) reaches a failure threshold, the system marks that pair as 'risky' and forces full mode for that extension until the failure rate drops below a certain threshold.

  6. Understand the Cognition Interface (v1) capabilities

    main

    The Cognition Interface (v1) is a deterministic control surface designed to shape an LLM's effective reasoning by managing its context. Instead of modifying model weights, it controls the following five dimensions:

    1. Context I/O (signal in): Manages deterministic reads, search, and shell output via explicit tool calls. It enforces bounded outputs (size caps, truncation markers) and sandboxed file access using PathJail with allowed roots.
    2. Orchestration (routing + budgets): Uses profile-driven pipelines ("Context as Code") to define read modes, budgets, verification, and autonomy. It includes intent/mode prediction and adaptive thresholds to stabilize cost and quality.
    3. Memory (what persists): Provides session continuity (CCP), structured knowledge, and tracking of contradictions/relations. It supports exportable handoffs and auditability across agents.
    4. Verification (what must hold): Performs deterministic checks on compressed outputs, such as verifying paths, identifiers, structure, and line numbers. It uses proof artifacts and CI gates to prevent drift.
    5. Delivery (everywhere): Supports deployment via MCP, HTTP MCP, and Team Server, allowing primitives to run locally, in CI, or in enterprise environments.

  7. Understand the LeanCTX Pillars

    main

    LeanCTX provides context infrastructure through three distinct pillars, all of which are accessible via a single binary (lean-ctx).

    • Engine: A developer-facing layer for active token reduction. It includes compression patterns, MCP tools, agent hooks, and a local dashboard.
    • Gateway: An organization-wide LLM reverse proxy. It intercepts traffic from providers like Anthropic, OpenAI, Gemini, and ChatGPT to compress prompts in-flight, meter costs, and enforce budgets.
    • Cloud: A hosted coordination layer providing user accounts, team provisioning, knowledge sync, and a context package registry.

    All features are available for self-hosting for free. Commercial tiers (Cloud/Enterprise) provide hosting and support rather than additional features.

  8. Understand the two core lean-ctx mental models

    main

    lean-ctx assists your AI through two primary mechanisms:

    1. MCP tools: Your AI editor calls ctx_* tools instead of using its native file reads or search functions. lean-ctx provides compressed and cached results through these tools.
    2. Shell hooks: When you or your AI's terminal executes commands like git, npm, or cargo, lean-ctx intercepts and compresses the output automatically.

  9. Identify LeanCTX Delivery Surfaces

    main

    LeanCTX can be integrated into your workflow through several delivery surfaces depending on your environment:

    • MCP Server: Uses stdio JSON-RPC for Model Context Protocol integration.
    • HTTP MCP Server: Accessible via lean-ctx serve.
    • Team Server: A multi-workspace server supporting authentication, scopes, and auditing.
    • CLI: A command-line interface with over 75 subcommands (e.g., knowledge, session, overview, compress).
    • Daemon: A background process using a Unix Domain Socket with PID lifecycle management.
    • Shell Hook: Intercepts commands via ~/.zshenv.
    • SDK: A TypeScript client for programmatic access.

  10. WASM Extension Sandbox and Execution Model

    main

    WASM extensions in LeanCTX run in a highly restricted, deterministic sandbox:

    • No Host Imports: Guests have no access to syscalls, network, filesystem, or the clock. They operate strictly on bytes → bytes.
    • Thread-Safety: A fresh Store and instance are created per call. This ensures that calls are deterministic and cannot leak state between executions.
    • Error Handling: The host guarantees it will never panic on malformed modules or guest traps; instead, it returns a WasmError.
    • Memory Safety: The host performs bounds-checking on the returned [out_ptr, out_ptr+out_len) region to prevent out-of-bounds reads.

  11. Understand the lean-ctx JetBrains Plugin architecture

    main

    The lean-ctx JetBrains plugin provides an interface between AI agents (via MCP) and the IDE's internal intelligence (PSI). It uses a tiered backend system to ensure functionality even when the IDE is not reachable:

    1. Backing B (JetBrains IDE): The preferred backend. It uses a Kotlin HTTP server running on 127.0.0.1 to access IDE-specific features like declaration, type_hierarchy, and inspections.
    2. Backing A (rust-analyzer/Headless): A fallback backend. It provides mandatory navigation like open_file, references, definition, and implementations using rust-analyzer.
    3. Headless/Tree-sitter: A fallback for specific tasks like symbols_overview and certain edits (replace_symbol_body, insert_before_symbol, insert_after_symbol) using tree-sitter.

    Note: Certain refactoring engines (e.g., rename, move, safe_delete, inline) are marked as BACKEND_REQUIRED and will return an error if the JetBrains backend is unavailable.

  12. Understand the two layers of lean-ctx

    main

    lean-ctx operates via two distinct layers to optimize AI context:

    1. Shell Hook: A transparent layer that automatically compresses CLI output (e.g., git, ls, npm, cargo) using 95+ patterns before it reaches the LLM. This requires no code changes and works automatically once installed.
    2. MCP Server: A layer providing specialized ctx_* tools (such as ctx_read, ctx_shell, and ctx_search) that your AI tool calls instead of native file or shell tools. This layer enables caching, specialized read modes, and intelligence features.