Capa de inteligencia científica

lean-ctx va más allá de la coincidencia de patrones. Seis algoritmos de teoría de la información, teoría de grafos y mecánica estadística trabajan juntos para decidir qué conservar, qué eliminar y dónde colocarlo - todo automáticamente, todo localmente, sin configuración.

Estos algoritmos potencian la capa de inteligencia autónoma. Se activan durante cada llamada a ctx_read, ctx_preload y ctx_overview - nunca los invocas directamente.

Cómo interactúan las capas

Puntuación de sorpresa predictiva

Los filtros de compresión tradicionales usan entropía de Shannon sobre caracteres sin procesar, lo que trata aaaa e import como igualmente predecibles. Predictive Surprise en cambio mide la entropía cruzada contra la frecuencia de tokens BPE - qué tan sorprendente es cada línea para el tokenizador del LLM.

Cómo funciona

1. Cada línea se tokeniza usando o200k_base (tokenizador de GPT-4o / Claude).
2. Para cada token, un prior Zipfiano estima la frecuencia esperada basándose en el rango.
3. Se calcula la entropía cruzada: las líneas con tokens comunes (código repetitivo) obtienen puntuación baja; las líneas con tokens raros (lógica compleja) obtienen puntuación alta.
4. Las líneas por debajo del umbral de sorpresa son candidatas para eliminación durante la compresión agresiva.

Ejemplo

// Low surprise (boilerplate) - candidate for removal:
return Ok(());                    // surprise: 0.12
use std::collections::HashMap;   // surprise: 0.18

// High surprise (unique logic) - always preserved:
let decay = (-alpha * dist as f64).exp();   // surprise: 0.89
scores[j] += heat[i] * decay / degree;      // surprise: 0.94

Por qué importa

Predictive Surprise elimina un 15–30% más de código repetitivo que la entropía a nivel de caracteres, preservando la lógica compleja. Modela directamente lo que el LLM considera "informativo" porque usa el mismo vocabulario BPE.

Propagación de relevancia espectral

Cuando le pides a lean-ctx que precargue contexto para una tarea, necesita decidir qué archivos importan. La coincidencia simple por palabras clave solo encuentra archivos que mencionan tus términos de búsqueda. Spectral Relevance encuentra archivos que están estructuralmente conectados a los relevantes - incluso si no comparten palabras clave.

Cómo funciona

Dos algoritmos de grafos se ejecutan sobre el grafo de dependencias del proyecto:

1. Difusión de calor - Los archivos semilla que coinciden con la descripción de la tarea reciben "calor" inicial. El calor se propaga a lo largo de las aristas de importación con decaimiento exponencial, simulando el flujo de información a través del código.
2. Centralidad PageRank - Los archivos importados por muchos otros archivos reciben puntuaciones de centralidad más altas. Esto identifica nodos estructurales centrales (por ejemplo, un db.ts importado por 20 módulos).

La puntuación de relevancia final combina ambos: 0.7 × heat + 0.3 × pagerank. Los archivos por debajo del umbral se excluyen de la precarga.

Ejemplo

Task: "fix authentication bug"

Direct matches:       auth.ts, login.ts
Heat diffusion adds:  middleware.ts (imports auth.ts)
                      session.ts (imported by auth.ts)
PageRank promotes:    db.ts (imported by 18 files - structural hub)

Result: 5 files preloaded instead of 2, covering the full blast radius.

Sin configuración

El grafo de dependencias se construye automáticamente en el primer uso a través de load_or_build(). No se necesita ctx_graph build - simplemente funciona.

Asignación de contexto de Boltzmann

Una vez que Spectral Relevance selecciona los archivos relevantes, cada archivo necesita un presupuesto de tokens. Los enfoques ingenuos asignan presupuestos iguales u ordenan por relevancia. Boltzmann Allocation utiliza mecánica estadística para distribuir los tokens de manera óptima.

Cómo funciona

1. Cada archivo tiene una puntuación de relevancia E_i de Spectral Relevance.
2. Un parámetro de temperatura β se deriva de la tarea: tareas específicas ("corregir bug de autenticación en login.ts") producen temperatura baja (asignación concentrada en los archivos principales); tareas amplias ("refactorizar el código") producen temperatura alta (distribución uniforme).
3. Los presupuestos de tokens siguen la distribución de Boltzmann: budgeti = total × (eβ·Ei / Σ eβ·Ej)
4. Se aplican presupuestos mínimos y máximos (128–4096 tokens por archivo), y el modo de compresión (full, map, signatures) se elige según el presupuesto asignado.

Ejemplo

Task: "fix the JWT validation in auth middleware"
Task specificity: 0.85 (specific) → β = 4.2

File            | Relevance | Budget | Mode
auth.ts         |      0.92 |  3,200 | full
middleware.ts   |      0.78 |  1,800 | full
session.ts      |      0.45 |    420 | map
db.ts           |      0.31 |    180 | signatures
routes.ts       |      0.22 |    128 | signatures
                                ─────
Total:                         5,728 tokens (within 8,000 budget)

Reciprocal Rank Fusion (RRF) Cache Eviction

lean-ctx uses Reciprocal Rank Fusion for cache eviction decisions, replacing the earlier Boltzmann-inspired weighted scoring. RRF handles incomparable signals (time in seconds, frequency as counts, size in tokens) without arbitrary weight tuning.

Formula: RRF(d) = Σ 1/(K + ranki(d)) - entries with the lowest fused score are evicted first. This produces monotonically correct ordering regardless of signal magnitude differences.

Fragmentación semántica con puentes de atención

Los LLMs sufren del problema "Perdido en el medio": la información al principio y al final del contexto recibe más atención que el contenido en el medio. Semantic Chunking reestructura la salida para minimizar la pérdida de información.

Cómo funciona

1. Detección de fragmentos - Las líneas de código fuente se agrupan en fragmentos semánticos (funciones, tipos, imports, lógica suelta) basándose en heurísticas de límites del AST.
2. Ordenamiento por relevancia - Los fragmentos que coinciden con la tarea actual se promueven al inicio (posición de alta atención). Los fragmentos restantes se ordenan por prioridad de tipo.
3. Puentes de atención - Entre fragmentos, lean-ctx inserta marcadores de puente mínimos (---) para que el LLM reconozca los límites estructurales.
4. Anclas finales - Las últimas 2–3 líneas del fragmento de mayor prioridad se repiten al final de la salida, aprovechando el sesgo de recencia para información crítica.

Ejemplo

// Without chunking (flat output):
import { db } from '../pages/docs/db';
import { hash } from '../pages/docs/crypto';
const MAX_RETRIES = 3;
export function createUser(...) { ... }
export function validateToken(...) { ... }    ← lost in the middle
export function deleteUser(...) { ... }

// With semantic chunking (task: "fix token validation"):
export function validateToken(...) { ... }    ← promoted to top
---
export function createUser(...) { ... }
export function deleteUser(...) { ... }
---
import { db } from '../pages/docs/db';
const MAX_RETRIES = 3;
---
// anchor: validateToken signature                ← tail anchor

Deduplicación MMR

Cuando se cargan múltiples archivos en el contexto, a menudo contienen imports duplicados, código repetitivo compartido o patrones de código muy similares. Maximum Marginal Relevance (MMR) elimina esta redundancia preservando la información única.

Cómo funciona

1. Para cada línea, se calcula la similitud Jaccard de bigramas contra todas las líneas previamente seleccionadas (el "conjunto de cobertura").
2. La puntuación MMR equilibra relevancia contra redundancia: MMR(l) = λ × relevance(l) - (1 - λ) × max_similarity(l, selected)
3. Las líneas con MMR < 0 se suprimen - agregan más redundancia que información. El parámetro λ tiene un valor predeterminado de 0.7 (favoreciendo relevancia sobre diversidad).

Impacto

En una precarga típica de múltiples archivos, MMR elimina un 10–25% del contenido redundante - principalmente imports compartidos y patrones de utilidades repetidos.

Optimización de tokens alineada con BPE

Después de que todo el contenido se selecciona y ordena, un paso final optimiza el texto sin procesar para el tokenizador BPE del LLM. Pequeños cambios de formato pueden reducir significativamente el conteo de tokens sin cambiar la semántica.

Reglas de optimización

Cómo funciona

Cada regla es un reemplazo simple de cadena aplicado línea por línea después de todas las demás etapas de compresión. Las reglas se derivan del análisis de límites de tokens BPE - apuntan a patrones donde el tokenizador produce innecesariamente muchos tokens para texto semánticamente equivalente.

Impacto

La optimización BPE típicamente ahorra un 3–8% adicional de tokens sobre la salida ya comprimida. Los ahorros se acumulan entre archivos y son más significativos para lenguajes verbosos (TypeScript, Java, C#).

Verificando el impacto

Ejecuta lean-ctx benchmark run en tu proyecto para medir el efecto combinado de los seis algoritmos. El informe de benchmark muestra el ahorro de tokens por archivo, puntuaciones de preservación (AST, identificadores, líneas) y ratios de compresión generales.

$ lean-ctx benchmark run
──────────────────────────────────────────
BENCHMARK - /Users/you/project
──────────────────────────────────────────
Files:       143
Total:       285,401 → 42,810 tokens (85% reduction)
Avg/file:    1,997 → 300 tokens

Preservation:
  AST:         98.2%
  Identifiers: 97.4%
  Lines:       96.1%

Mode breakdown:
  full:        68% of files
  map:         22% of files
  signatures:   8% of files
  aggressive:   2% of files

Reconocimiento estructurado de intención

lean-ctx clasifica cada interacción en un StructuredIntent - una representación basada en slots que contiene el tipo de tarea, confianza, archivos objetivo, alcance, pista de idioma, urgencia y verbo de acción. Esto impulsa todas las decisiones posteriores: qué modo de compresión usar, cómo enrutar el contexto y qué priorizar.

Se reconocen 9 tipos de tareas: Explore, Generate, FixBug, Refactor, Test, Review, Config, Deploy y Document. Cada tipo activa diferentes estrategias de compresión y enrutamiento de contexto.

IntentScope va desde SingleFile pasando por MultiFile y CrossModule hasta ProjectWide - determinando cuán ampliamente se recopila el contexto.

Cómo funciona

La compresión se adapta por intención: las tareas FixBug priorizan líneas de error y archivos de prueba a través del filtro Information Bottleneck, las tareas Explore usan limpieza ligera para preservar la estructura, y las tareas Generate se enfocan en firmas y tipos.

El selector de modo automático de ctx_read usa el tipo de tarea activo para refinar su decisión - eligiendo modo task para correcciones de errores en archivos grandes, modo map para exploración y modo signatures para tareas de documentación.

Ejemplo

Query: "fix the NaN bug in entropy.rs"

StructuredIntent:
  task_type:    FixBug (confidence: 0.95)
  targets:      ["entropy.rs"]
  scope:        SingleFile
  language:     Rust
  urgency:      0.8
  action_verb:  "fix"

→ Compression: Information Bottleneck filter (error lines boosted)
→ Mode:        task (error-focused extraction)
→ Suggestions: tests/entropy_test.rs (deficit detection)

Arquitectura del pipeline de contexto

El pipeline de contexto procesa información a través de seis capas distintas: Input → Intent → Relevance → Compression → Translation → Delivery. Cada capa tiene contratos definidos (tipos de entrada/salida) y emite métricas.

Cómo funciona

Input → Intent → Relevance → Compression → Terse Engine → Delivery
  │        │          │            │              │              │
  │        │          │            │              │              └─ Final output to LLM
  │        │          │            │              └─ 4-layer terse pipeline (see below)
  │        │          │            └─ AST-aware compression per intent
  │        │          └─ Graph heat + relevance scoring
  │        └─ StructuredIntent classification
  └─ Raw file content / shell output

Las métricas por capa rastrean tokens de entrada, tokens de salida, tasa de compresión y tiempo de procesamiento. Agregadas en una sesión, revelan dónde ocurren los mayores ahorros y qué capas son cuellos de botella.

4-Layer Terse Engine

The terse engine applies four composable compression layers, controlled by compression_level (Off / Lite / Standard / Max). Each layer is independently verified by Lean4 proofs (TerseQuality, TerseEngine — part of 82 total theorems).

Libro de contexto y gestión de presión

El ContextLedger rastrea cada archivo enviado a la IA: ruta, modo de compresión, tokens originales, tokens enviados y marca de tiempo. Calcula la utilización de la ventana de contexto y la presión en tiempo real.

Cómo funciona

Tres niveles de presión: None (menos del 70% de utilización), Compress (70–90%) y Evict (más del 90%). En cada nivel, el sistema toma acciones diferentes - degradando modos de compresión para archivos menos relevantes o sugiriendo desalojos.

Ejemplo

Context Window: 128,000 tokens
Loaded: 89,600 tokens (70% utilization)
Pressure: None → safe

After loading 3 more files:
Loaded: 115,200 tokens (90% utilization)
Pressure: Compress → downgrade non-target files

Re-Injection Plan:
  utils.rs:    full → signatures  (save 2,400 tokens)
  helpers.rs:  full → map         (save 1,800 tokens)
  config.rs:   full → signatures  (save 1,200 tokens)
  Protected:   auth.rs, login.ts  (target files)

La detección de déficit de contexto identifica información faltante: si una corrección de error apunta a auth.rs pero no se carga ningún archivo de prueba, el sistema sugiere tests/auth_test.rs. Para tareas de configuración, recomienda Cargo.toml, .env o Dockerfile.

La reinyección inteligente genera un plan para liberar presupuesto de contexto degradando archivos no objetivo (ej. cambio de modo full a signatures) mientras protege los archivos críticos para la intención actual.

Inteligencia multi-agente

Cuando múltiples agentes de IA colaboran (ej. un programador y un revisor), lean-ctx proporciona transferencias estructuradas, profundidad de contexto basada en roles e intercambio de conocimiento entre agentes.

Cómo funciona

HandoffPackage agrupa el libro de sesión actual, la intención estructurada y la instantánea del contexto en una unidad transferible - para que el agente receptor comience con conciencia situacional completa en lugar de una pizarra en blanco.

Se reconocen siete roles de agente: Coder, Reviewer, Planner, Explorer, Debugger, Tester y Orchestrator. Cada uno recibe una ContextDepthConfig personalizada - un Programador obtiene más lecturas completas, un Revisor más firmas, un Explorador contexto de grafo más amplio.

Ejemplo

Agent "coder-1" (role: Coder):
  max_files_full: 8
  preferred_mode: full
  context_budget: 80%

Agent "reviewer-1" (role: Reviewer):
  max_files_full: 3
  preferred_mode: signatures
  context_budget: 60%

Shared Knowledge:
  K:discovery:auth_bug = "null check missing in line 42"
  K:decision:fix_approach = "add Option<T> wrapper"
  → reviewer-1 inherits these facts without re-reading files

El intercambio de conocimiento entre agentes permite a los agentes intercambiar hechos estructurados (ej. "discovery:auth_bug=falta verificación null en línea 42") a través de un bloc de notas compartido. Los nuevos agentes heredan conocimiento relevante sin tener que redescubrirlo.

Community Detection (Louvain)

The core::community module clusters files by their dependency graph using the Louvain algorithm. This groups tightly-coupled files into communities, enabling more intelligent context selection — files in the same community as your target are prioritized for preloading and receive higher relevance scores during task-driven reads.

Code Smell Detection

The ctx_smells tool detects long functions, deep nesting, and high cyclomatic complexity using the core::smells module. Detected smells are scored with graph-enriched weighting — files with high PageRank or many dependents receive amplified smell scores, surfacing maintenance hotspots that have the widest blast radius across the codebase.

Ver también

• Herramientas de inteligencia autónoma - las herramientas que usan estos algoritmos
• Motor tree-sitter - análisis AST para 18 lenguajes
• Configuración - ajuste de umbrales y configuración de autonomía
• Benchmark - midiendo tus ahorros