Core Concepts

Adaptive Learning

LeanCTX tunes itself from outcomes: learned compression thresholds, placement calibration, a stigmergic coordination field, delta playbooks — with measurable efficacy.

LeanCTX does not just compress with fixed rules — it learns from outcomes. Seven research-driven layers observe how compression, context placement and multi-agent coordination actually perform on your machine, and adapt continuously. Everything is local-first, bounded and clamped: research-tuned defaults stay the anchor, and learned adjustments decay back toward them when the evidence ages.

Learned compression thresholds

Every compressed read is an implicit experiment. Four outcome signals adjust a per-file-type threshold delta: a bounce (compressed read followed by a full re-read) and a failed edit push compression back; a clean compressed read and a wasted full read push it forward. Deltas are clamped to ±0.15, decay 2% daily, and only apply after 10 observations per extension. 

$ lean-ctx learning
Learned compression thresholds:
  .rs: delta +0.041 (27 signals) — compresses more
  .md: delta -0.060 (11 signals) — backs off

Placement calibration (lost in the middle)

LLMs recall the beginning and end of context best. LeanCTX ships research defaults for where to place tasks, anchors and progress — and then measures where your client's recalls actually hit. The begin/end budget share shifts with the evidence (clamped to 35–85%), per client profile.

Stigmergic coordination field

Parallel agents coordinate indirectly — like ant pheromones. Agents deposit CLAIMED, DONE, STUCK, HOT and AVOID scents on files and tasks; each kind decays exponentially (10–60 min half-life). Claims cost zero coordination tokens until they matter: 

ctx_agent action="claim" message="src/auth/session.rs"
→ Claimed: src/auth/session.rs (decays in ~10m unless re-claimed)

# A second agent claiming the same file:
→ already claimed by local-48121 (2m ago, still active)

# And ctx_read warns on foreign-claimed files:
[scent: claimed by local-48121 2m ago — coordinate before editing]

Every rejected claim is duplicate work prevented — and counted as efficacy evidence. See Multi-Agent Coordination for the direct messaging primitives this complements.

Delta playbook (no more context collapse)

Re-summarizing prior summaries loses detail — the ACE research line measured an 18k → 122 token collapse with −29% accuracy. LeanCTX checkpoints instead distill sessions into itemized entries with stable IDs (Strategy, Pitfall, Fact, FileRef) that are only appended, confirmed, voted and locally evicted — never rewritten. Resumed sessions replay the playbook, not a lossy prose summary.

Query-aware compression

Three layers make compression relevance-sensitive: entropy-mode reads fuse token entropy with an IDF-weighted score against your active task or latest semantic query; wakeup facts render as topic-clustered chunks (the theta–gamma working-memory model, ~4 items per chunk); and with the embedding engine active, semantically redundant lines are dropped MMR-style against a sliding window of kept lines.

Self-activating embeddings

Semantic features need a local ONNX embedding model (~30–90 MB). On first semantic need LeanCTX downloads it in the background (SHA-256 pinned, trust-on-first-use) and warms the engine — no hot path ever blocks. Air-gapped? Set [embedding] auto_download = false and semantic layers stay off gracefully; ctx_metrics always shows the engine status and the reason.

Share learning with your team

Learning state exports as a secret-free bundle — file extensions, client profiles and aggregate numbers only. Merges are idempotent and double-count-safe (sample-weighted deltas, max-counters), so bundles can live in a repo or ship via CI: 

$ lean-ctx learning export team.json   # on the experienced machine
$ lean-ctx learning import team.json   # on the new machine

Measured efficacy

Adaptation must earn its place. LeanCTX keeps a 30-day efficacy ring and reports: bounce-rate week over week (from the signed savings ledger), placement hit-rate movement, playbook survival, and duplicate work prevented. If a learning layer does not move its metric, it gets retuned — with data on the table.

Research foundations

  • LLMLingua / LLMLingua-2 — perplexity- and classifier-based token pruning
  • ACE: Agentic Context Engineering — delta contexts, anti-collapse invariants
  • Lost in the Middle — U-shaped attention over long contexts
  • StreamingLLM / Heavy-Hitter Oracle — attention sinks, KV eviction
  • Theta–gamma coupling — working-memory chunk capacity
  • Information Bottleneck — relevance-conditioned compression
  • Stigmergy — indirect coordination via environmental signals