Configuration

Boundary Policy v3.6.0

The [boundary_policy] section controls cross-project access behavior. In monorepo or multi-project setups, this determines whether agents can search or import files across project boundaries, and whether such access is logged for audit.

Configuration

# ~/.lean-ctx/config.toml
[boundary_policy]
allow_cross_project = false   # Allow cross-project search/import (default: false)
audit_cross_project = false   # Log cross-project access events (default: false)

Data Directory v3.1.3

All persistent data (stats, knowledge, agent state, sessions, cache) is stored under a single base directory, resolved in this order:

1. LEAN_CTX_DATA_DIR environment variable (if set)
2. ~/.lean-ctx (default)

# Override for custom locations or containers
export LEAN_CTX_DATA_DIR=/data/lean-ctx

# Verify current data directory
ls "$(lean-ctx config | grep data_dir)"

CLI File Cache v2.21.1

Since v2.21.1, lean-ctx read <file> in CLI mode caches file content to $LEAN_CTX_DATA_DIR/cli-cache/cache.json (default: ~/.lean-ctx/cli-cache/cache.json). Subsequent reads of unchanged files return a compact ~13-token cache-hit response instead of the full file content. This enables caching for CLI-mode integrations (e.g. pi-lean-ctx) that don't use the MCP server.

Management Commands

lean-ctx cache              # Overview with hit rate
lean-ctx cache stats        # Detailed statistics
lean-ctx cache clear        # Remove all entries
lean-ctx cache invalidate <path>  # Remove specific file

lean-ctx read file.rs --fresh     # Bypass cache for one read

Cache Eviction Policy

The session cache uses a multi-signal eviction system: Reciprocal Rank Fusion (RRF) fuses recency, frequency, and size into a base score. On top, Hebbian co-access patterns track which files are used together, and a Boltzmann temperature mechanism adjusts eviction aggressiveness based on memory pressure. Entries with the lowest combined energy are evicted first. No manual tuning required.

Progressive Throttling / Loop Detection

lean-ctx automatically detects when an AI agent loops - calling the same or similar tools repeatedly without progress. This prevents token waste in large and monorepo projects.

Per-Fingerprint Throttling

Tool calls are tracked using a fingerprint-based sliding window (default 5 minutes). When repeated identical calls are detected, throttling escalates:

Cross-Tool Search Tracking v3.1.2

Agents often alternate between ctx_search, ctx_shell (grep/rg/find), and ctx_semantic_search to search for the same thing. lean-ctx now tracks ALL search-related calls as a group. If more than 10 total search calls happen within the window (regardless of which tool), the agent is blocked with guidance to use ctx_tree and narrow searches with the path parameter.

Pattern Similarity Detection v3.1.2

Searching for "compress", then "compression", then "compress_output" is now detected as the same semantic loop. lean-ctx extracts the alpha-root of each search pattern and groups similar queries together.

Configuration

All thresholds are configurable via ~/.lean-ctx/config.toml:

[loop_detection]
normal_threshold = 2      # warn after this many identical calls
reduced_threshold = 4     # reduce output after this many
blocked_threshold = 0     # block after this many (0 = disabled)
window_secs = 300         # sliding window in seconds
search_group_limit = 10   # total search calls before block

Pipe Guard v2.21.6

Since v2.21.6, the shell hook automatically detects when stdout is piped (not a terminal) and bypasses all compression. This prevents corruption when piping command output - for example, curl -fsSL https://example.com/install.sh | sh now works correctly even with the lean-ctx shell hook active.

Tool Result Archive v3.3.3

When compression removes details you might need later, the Tool Result Archive saves the full uncompressed output to disk and returns a reference ID. The agent can retrieve the full content at any time using ctx_expand.

This is the core of zero-loss compression: the context window stays small, but no information is permanently lost.

How It Works

1. A tool response exceeds the configured token threshold
2. LeanCTX stores the full output to ~/.lean-ctx/archive/ (content-addressed by SHA-256)
3. The compressed response includes an [ARCHIVE: <id>] reference
4. The agent calls ctx_expand <id> to retrieve the full content on demand

Configuration

# ~/.lean-ctx/config.toml
[archive]
enabled = true                # Enable tool result archiving (default: true)
threshold_chars = 4096        # Minimum characters before archiving (default: 4096)
max_age_hours = 48            # Auto-cleanup after N hours (default: 48)
max_disk_mb = 500             # Maximum total disk usage for archive (default: 500)

Environment Variables

Storage

Archived results are content-addressed (SHA-256 hash of the full output). Duplicate content is automatically deduplicated. Race conditions from parallel tool calls are handled via PID-unique temporary files with atomic rename.

Compression Level v4.0.0

compression_level is the unified control for the 4-layer terse engine, replacing the legacy output_density and terse_agent settings. It governs both input compression (tool responses) and output optimization (agent responses) through a single knob.

Levels

Configuration

# ~/.lean-ctx/config.toml
compression_level = "off"    # off (default) | lite | standard | max

# Legacy settings still accepted for backward compatibility:
# terse_agent = "full"            # maps to compression_level = "standard"
# output_density = "terse"        # maps to compression_level = "lite"

Environment Variables

Interaction with CRP Mode

compression_level and LEAN_CTX_CRP_MODE are complementary but independent. CRP mode controls the format of lean-ctx's own output (tdd/compact/off), while compression_level controls both input compression and the instructions given to the agent about how it should respond. Both can be active simultaneously for maximum token savings.

What Changes (Standard / Max)

When compression is active at "standard" or above, the 4-layer terse engine applies:

• Layer 1: Dictionary — Common token substitutions and abbreviations
• Layer 2: Residual — Whitespace normalization, boilerplate removal
• Layer 3: Scoring — Information-theoretic ranking of content blocks
• Layer 4: Pipeline — CEP v1 protocol with delta-only output, structured notation (+/-/~), and token budgets

This can reduce total token usage by 30-50% per conversation turn. Formally verified by 82 Lean4 theorems including TerseQuality and TerseEngine proofs.

Legacy: Terse Agent Mode

The terse_agent setting is still accepted for backward compatibility. Values are mapped automatically: "off" → Off, "lite" → Lite, "full" → Standard, "ultra" → Max. Boolean true maps to Standard.

Legacy: Output Density v3.1.0 — superseded by compression_level

output_density is superseded by compression_level, which unifies both input and output compression into a single setting. The legacy output_density values are still accepted and mapped automatically: "normal" → Off, "terse" → Lite, "ultra" → Max.

Legacy Configuration

# ~/.lean-ctx/config.toml
# Legacy (still works):
output_density = "terse"

# Recommended replacement:
compression_level = "lite"

Minimal Overhead v3.4.1

minimal_overhead reduces lean-ctx's per-call token footprint to the absolute minimum. It's designed for environments where every token counts - Codex, CI pipelines, or any cost-sensitive workflow.

What it disables

Configuration

# ~/.lean-ctx/config.toml
minimal_overhead = true

# Or via environment variable
# export LEAN_CTX_MINIMAL=1

# To only disable checkpoints (keep other meta-strings):
# export LEAN_CTX_NO_CHECKPOINT=1

When to use

• Codex / Claude Code CLI - these environments benefit most from reduced overhead since every token in the conversation counts against the context window
• CI/CD pipelines - automated tasks where meta-strings add noise without value
• High-frequency tool calls - sessions with many short tool calls where per-call overhead accumulates
• Cost optimization - when you want to minimize API costs without changing compression settings

Measured impact

Combined with lazy tools (default), minimal overhead reduces per-session token overhead from ~6,600 tokens (full tools + verbose) to ~2,400 tokens (lazy + minimal) - a 64% reduction.

Rules Scope v3.3.3

Controls where lean-ctx injects its cursor rules file (lean-ctx.mdc). By default, rules are injected in both the global and project locations to ensure coverage across all Cursor workspaces.

Values

Configuration

# ~/.lean-ctx/config.toml
rules_scope = "global"    # global | project | both

# Set via CLI
lean-ctx config set rules_scope project

Buddy Mode

Buddy mode enables collaborative multi-agent workflows. When enabled, lean-ctx coordinates context sharing between multiple agent sessions working on the same project.

Configuration

# ~/.lean-ctx/config.toml
buddy_enabled = true

Custom Aliases

Define custom shell command aliases that expand inside ctx_shell. Useful for project-specific shortcuts that agents can use without knowing the full command.

Configuration

# ~/.lean-ctx/config.toml
[[custom_aliases]]
alias = "test"
command = "cargo test --workspace --quiet"

[[custom_aliases]]
alias = "lint"
command = "npm run lint -- --fix"

[[custom_aliases]]
alias = "deploy-staging"
command = "kubectl apply -f k8s/staging/ --dry-run=client"

Headless MCP Mode v3.3.3

By default, when lean-ctx starts as an MCP server it automatically configures the environment: injecting rules, installing hooks, updating CLAUDE.md, and registering itself. If you want full control over your configuration - for example when using a custom launcher - you can disable all auto-setup behavior.

Usage

# Set before launching the MCP server
export LEAN_CTX_HEADLESS=1

# lean-ctx will start as a pure MCP server:
# - No rules injection
# - No hook installation
# - No CLAUDE.md modification
# - No agent registry updates
# - No background version check

When to Use

• Custom launchers - You inject lean-ctx instructions via --append-system-prompt
• Toggle setups - You want to switch lean-ctx on/off per session
• CI/CD pipelines - No interactive environment, no need for hooks
• Sandboxed environments - You don't want lean-ctx modifying files outside the project

Project Identity File (.lean-ctx-id) v3.5.16

lean-ctx identifies projects by hashing their root path. In Docker or CI environments where multiple projects share the same mount path (e.g. /workspace), this can cause data collisions — graph index, semantic cache, bandit state, and embedding index from one project bleeding into another.

To prevent this, create a .lean-ctx-id file in your project root with a unique project name. This file takes highest priority for project identification — above git remote URL, package.json name, and directory name.

# Create the identity file
echo "my-unique-project-name" > .lean-ctx-id

Priority Order

Identity-Aware Caches

The following data stores use a composite project hash (path + identity) to ensure isolation:

• Graph index — project dependency graph (SQLite Property Graph)
• Semantic cache — embedding-based similarity lookups
• Bandit state — multi-armed bandit model for read mode selection
• Embedding index — vector store for semantic search

When a .lean-ctx-id file is added or changed, existing data is automatically migrated from old hash directories. No manual action required.

Docker Usage

# Include in your Dockerfile or mount as volume
COPY .lean-ctx-id /workspace/.lean-ctx-id

# Or create during build
RUN echo "my-project" > /workspace/.lean-ctx-id

Shell Activation v3.5.16

shell_activation controls when lean-ctx shell aliases (like _lc) auto-activate in interactive shells. By default, lean-ctx activates in every shell. In team environments or CI, you may want to limit activation to AI agent sessions only.

Modes

Configuration

# ~/.lean-ctx/config.toml
shell_activation = "agents-only"    # always | agents-only | off

# Or via environment variable
# export LEAN_CTX_SHELL_ACTIVATION=agents-only

When to Use

• always — Solo developer, want compression in every terminal
• agents-only — Team environments where non-AI shells should remain unmodified. Also enables non-interactive (non-TTY) tracking for Docker/Codex containers (v3.5.19+)
• off — Full manual control, only enable when explicitly needed

Cloud

The [cloud] section controls cloud integration features for lean-ctx.

Configuration

# ~/.lean-ctx/config.toml
[cloud]
contribute_enabled = false    # Opt-in to anonymous usage telemetry (default: false)

Proxy

The [proxy] section lets you override upstream API endpoints for LLM providers. Useful for corporate proxies, self-hosted inference, or regional routing.

Configuration

# ~/.lean-ctx/config.toml
[proxy]
anthropic_upstream = null     # Custom Anthropic API endpoint (default: null)
openai_upstream = null        # Custom OpenAI API endpoint (default: null)
gemini_upstream = null        # Custom Gemini API endpoint (default: null)

Memory

The [memory] section configures lean-ctx's persistent memory subsystem. Memory is organized into specialized stores — each with its own retention policy, capacity limits, and retrieval rules. Use memory_profile for a preset, or fine-tune individual sub-tables.

How Memory Lifecycle Works

Memory entries (facts, patterns, gotchas) have a confidence score that changes over time:

1. New facts start with high confidence (based on source quality)
2. Daily decay (decay_rate) gradually reduces confidence of unused facts
3. Access resets — when a fact is recalled by the agent, its confidence is restored
4. Low-confidence facts (below low_confidence_threshold) are flagged for review
5. Stale facts (not accessed for stale_days) become eligible for pruning
6. Pruning happens during auto_consolidate runs — not instantly

[memory.knowledge]

Fact store for project-level knowledge extracted from conversations and code analysis.

[memory.knowledge]
max_facts = 200               # Maximum stored facts per project (default: 200)
max_patterns = 50             # Maximum code patterns (default: 50)
max_history = 100             # Maximum history entries (default: 100)
contradiction_threshold = 0.5 # Confidence threshold for contradiction detection (default: 0.5)
recall_facts_limit = 10       # Facts recalled per retrieval (default: 10)
rooms_limit = 25              # Maximum rooms returned (default: 25)
timeline_limit = 25           # Maximum timeline entries (default: 25)
relations_limit = 40          # Maximum relations returned (default: 40)

[memory.episodic]

Session-level memory capturing what happened during agent interactions.

[memory.episodic]
max_episodes = 500            # Maximum stored episodes (default: 500)
max_actions_per_episode = 50  # Actions per episode (default: 50)
summary_max_chars = 200       # Episode summary length (default: 200)

[memory.procedural]

Learned procedures extracted from repeated agent workflows.

[memory.procedural]
max_procedures = 100          # Maximum stored procedures (default: 100)
min_repetitions = 3           # Repetitions before a pattern becomes a procedure (default: 3)
min_sequence_len = 2          # Minimum sequence length for detection (default: 2)
max_window_size = 10          # Maximum window size for pattern analysis (default: 10)

[memory.lifecycle]

Controls how memory entries age, decay, and are pruned over time.

[memory.lifecycle]
decay_rate = 0.01             # Daily decay factor for memory scores (default: 0.01)
low_confidence_threshold = 0.3 # Below this, facts are low-confidence (default: 0.3)
stale_days = 30               # Days before an entry is considered stale (default: 30)
similarity_threshold = 0.85   # Cosine similarity for deduplication (default: 0.85)

[memory.gotcha]

Stores project-specific gotchas — pitfalls, caveats, and non-obvious behaviors discovered during sessions.

[memory.gotcha]
max_gotchas_per_project = 100       # Maximum gotchas per project (default: 100)
retrieval_budget_per_room = 10      # Gotchas surfaced per session (default: 10)
default_decay_rate = 0.03           # Default decay rate for gotcha importance (default: 0.03)

[memory.embeddings]

Configuration for the vector embedding index used by semantic memory operations.

[memory.embeddings]
max_facts = 2000              # Maximum facts in the embedding index (default: 2000)

Exit Codes

In shell hook mode (-c), LeanCTX forwards the exit code of the wrapped command. This ensures scripts and CI pipelines work correctly. If the command fails (non-zero exit), the full original output is saved to ~/.lean-ctx/tee/ for debugging (when tee_mode is set to failures or always).

Token Counting

lean-ctx uses tiktoken-rs with the o200k_base encoding (same as GPT-4o, Claude, and other modern models) for exact token counting. No estimation, no heuristics - every savings number you see in lean-ctx gain or the dashboard reflects real token counts.