Adaptive Learning

LeanCTX does not just compress with fixed rules — it learns from outcomes. Together these adaptive layers form the Quality Loop v1: 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.

Multilingual intent routing

Intent classification — which drives task-aware reads, suspect-file detection and mode selection — now understands non-English tasks (#591). Verb-stem tables, function-word language detection and per-language stopword lists cover English, German, French and Spanish, so a prompt like "behebe den Fehler in der Sortierung" routes to the same FixBug intent (and the same full read of the suspect file) as its English equivalent, instead of falling back to a low-confidence Explore default. It is rule-based — no model download — and language filler words are kept out of the extracted keywords.

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.

Observation synthesis (entity summaries)

Inspired by Hindsight's observation network, the cognition loop's 9th step distils clusters of related facts into compact, per-entity observations — a synthesized orientation layer over the raw memory store. Facts are grouped by an entity anchor (a file path in the key or value, else the category); each cluster of at least cognition_synthesis_min_cluster facts (default 3) becomes one observation, written through the normal remember() path, so versioning, persistence and idempotency come for free and the output stays byte-stable. Synthesis is deterministic by default; an optional LLM refinement sits behind llm.enabled with the deterministic digest as the fallback.

Memory is epistemically typed on write — evidence (architecture, dependency, convention, gotcha) is kept distinct from inference (decision, preference, observation). Typing feeds salience ranking and, opt-in via archetype_aware_decay, lets structural evidence decay slower than inference.

On recall a relevant observation earns a balanced boost — above incidental matches, below an exact key hit — applied identically to lexical and semantic recall, and the rendered output preserves that ranking. The entity-summary leads as orientation, the precise raw facts follow, and a stale summary never buries them:

$ lean-ctx knowledge recall "session auth"
Matching facts (showing 3/5):
  [observation/src/auth/session.rs]: src/auth/session.rs — convention: Redis-backed sessions | decision: JWT refresh tokens | gotcha: clock skew breaks expiry (quality: 84%, confidence: 80%, confirmed: 2026-06-21 x3)
  [decision/src/auth/session.rs]: JWT refresh tokens, 30-min idle timeout (quality: 88%, confidence: 86%, confirmed: 2026-06-18 x2)
  [gotcha/src/auth/session.rs:42]: clock skew breaks expiry under load (quality: 79%, confidence: 75%, confirmed: 2026-06-19 x1)

Synthesis runs as step 9, active when cognition_loop_max_steps >= 9 (the default; set 8 to disable), and surfaces as observation_synthesis in lean-ctx introspect cognition.

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
• Hindsight — agent observation networks, evidence vs. inference