Context Field Theory (CFT) is the mathematical framework behind LeanCTX's context selection. It models every context item as a point in a potential field, scored by a six-dimensional function that determines what belongs in your AI's attention window.
The Potential Function
The core of CFT is the Context Potential Φ — a function that assigns a relevance score to every context item at every point in time. Higher Φ means higher priority for inclusion in the context window.
Φ(i,t) = w_R · R(i,t) + w_S · S(i) + w_G · G(i,t) + w_H · H(i) − w_C · C(i,v) − w_D · D(i, selected)
| Factor | Description |
|---|---|
R(i,t) | Task Relevance R(i,t) — How relevant is this item to the current task? Computed via intent classification and semantic similarity. |
S(i) | Structural Importance S(i) — How central is this item in the codebase graph? Measured by betweenness centrality and PageRank. |
G(i,t) | Recency Gradient G(i,t) — When was this item last accessed or modified? Exponential time decay. |
H(i) | Historical Frequency H(i) — How often has this item been accessed across sessions? Tracks long-term importance. |
C(i,v) | Token Cost C(i,v) — How many tokens does this item consume for the current model's tokenizer? Penalizes expensive items. |
D(i,S) | Redundancy Penalty D(i,S) — How much overlap does this item have with already-selected items? Prevents duplication. |
Rich Context Ledger
The Rich Context Ledger upgrades the flat entry log into a versioned item registry. Each item gets a content-addressed ID, a state machine (Candidate, Included, Excluded, Pinned, Stale), content hashing for change detection, per-item Phi scores, and full provenance tracking — enabling precise eviction, smart re-injection, and overlay conflict detection.
Context Handles
Handles are lightweight, typed references to context items. Instead of loading a 4,000-token file, agents receive a handle like @F1 that can be expanded on demand. This lazy evaluation pattern keeps context lean until content is actually needed.
Context Overlays
Overlays are reversible mutations applied to context items. They modify how items are treated without changing the source. Overlays persist per-project and can be stacked, making them ideal for temporary focus shifts or noise suppression.
Context Compiler
The context compiler takes a task description and a token budget, then builds the minimal context package that maximizes total Φ within the budget constraint. It uses greedy selection with redundancy penalties to avoid duplicating information.
Context Policy Engine
Policies are declarative rules that automate context governance. Define patterns for auto-pinning, suppression, token limits, and staleness detection in a simple TOML configuration. Policies apply per-project and are evaluated on every context operation.
Dashboard Cockpit
The Context Cockpit provides a visual dashboard for real-time monitoring. View Phi scores as heatmaps, inspect active handles and overlays, track token budgets, and manage context through an interactive web UI with live Context Bus event streaming.
CLI & MCP Tools
Every CFT operation is accessible via both CLI commands and MCP tools, giving you full control regardless of your integration mode.
| Command | Description |
|---|---|
lean-ctx control pin <path> | Pin a file to ensure it stays in every context compilation |
lean-ctx control suppress <path> | Suppress a file to exclude it from context selection |
lean-ctx control list | List all active context handles with their Φ scores |
lean-ctx compile --budget <tokens> | Compile an optimal context package within a token budget |
lean-ctx plan --task <description> | Generate a context plan with deficit detection |
ctx_control action="list" | List all tracked context items with state and Phi score |
ctx_plan task="fix auth" budget=8000 | Generate a Phi-ranked context plan for a task |
ctx_compile mode="handles" budget=8000 | Compile the optimal context package for current task |
Start Using Context Field Theory
Install LeanCTX and start managing context with mathematical precision.
Get Started →