# Optimización de Flujos Agénticos Avanzados y Orquestación de Contexto (Julio 2026)

> **Referencia de arquitectura, integración y operación.** Entornos macOS Sequoia sobre Apple Silicon M3/M4.
> Prosa en español. Código, configuración y comandos en inglés.

---

## Índice

1. [Arquitectura General del Pipeline Agéntico](#1-arquitectura-general-del-pipeline-agéntico)
2. [Componentes Core: Análisis en Profundidad](#2-componentes-core-análisis-en-profundidad)
   - 2.1 [Caveman Lite: Prompt Engineering Minimalista](#21-caveman-lite-prompt-engineering-minimalista)
   - 2.2 [Principio Ponytail / YAGNI Estricto](#22-principio-ponytail--yagni-estricto)
   - 2.3 [Codebase-Memory MCP Server (DeusData)](#23-codebase-memory-mcp-server-deusdata)
   - 2.4 [Headroom: Proxy de Compresión CCR](#24-headroom-proxy-de-compresión-ccr)
3. [Pipeline Integrado: Ciclo de Ejecución Unificado](#3-pipeline-integrado-ciclo-de-ejecución-unificado)
4. [Matriz Comparativa](#4-matriz-comparativa)
5. [Estrategias de Indexación por Stack](#5-estrategias-de-indexación-por-stack)
6. [Integración en macOS Sequoia (Apple Silicon)](#6-integración-en-macos-sequoia-apple-silicon)
7. [Estado del Arte (Julio 2026)](#7-estado-del-arte-julio-2026)
8. [Apéndices](#8-apéndices)

---

## 1. Arquitectura General del Pipeline Agéntico

El pipeline orquesta cuatro sistemas en serie: el repositorio se indexa mediante Codebase-Memory MCP Server, el agente de codificación consulta el grafo, Headroom intercepta y comprime el contexto antes de enviarlo al LLM, y las políticas Caveman Lite + Ponytail (`CLAUDE.md`) gobiernan el comportamiento de salida del modelo.

```mermaid
graph TD
    A[Repositorio Local] -->|indexación AST| B[Codebase-Memory MCP Server]
    B -->|grafo de conocimiento| C[Agente: Claude Code / OpenCode / Codex]
    C -->|tool outputs + contexto| D[Headroom Proxy CCR]
    D -->|contexto comprimido 60-95%| E[API LLM]
    E -->|respuesta| C
    F[CLAUDE.md - Caveman + Ponytail] -.->|gobernanza| C

    style A fill:#2d2d2d,color:#fff
    style B fill:#1a5276,color:#fff
    style C fill:#196f3d,color:#fff
    style D fill:#7d3c98,color:#fff
    style E fill:#b03a2e,color:#fff
    style F fill:#935116,color:#fff
```

**Figura 1 — Arquitectura general del pipeline agéntico.** Cuatro componentes trabajan en un ciclo unificado: indexación → consulta → compresión → gobernanza. Las líneas punteadas indican gobernanza de comportamiento, no flujo de datos.

### Ciclo de ejecución

| Fase | Componente | Acción |
|------|-----------|--------|
| Generación de datos | Codebase-Memory MCP | Indexa AST del repositorio, produce grafo de conocimiento |
| Consulta | Agente de código | Usa `search_graph`, `trace_call_path` para recuperar contexto estructural |
| Compresión | Headroom CCR | Intercepta tool outputs y contexto, comprime 60-95% antes de la API |
| Gobernanza | `CLAUDE.md` | Obliga al LLM a procesar contexto comprimido y emitir respuestas minimalistas |

---

## 2. Componentes Core: Análisis en Profundidad

### 2.1 Caveman Lite: Prompt Engineering Minimalista

**Filosofía**: Framework de comunicación que suprime la prosa conversacional, las conclusiones educadas ("Certainly!", "I'll now..."), y el relleno de cortesía. Cada token de salida debe tener utilidad directa.

**Reglas sintácticas — Caveman Lite v2.x**:

- Sin saludos ni despedidas.
- Sin frases de anticipación ("I'll now analyze...", "Let me explain...").
- Sin validación social ("Great question!", "That's an excellent point.").
- Sin rodeos contextuales. Ve directo al resultado.
- Las advertencias usan `> ⚠️`, no prosa explicativa.

**Ejemplo antes/después en `CLAUDE.md`**:

```markdown
# BEFORE (verbose, conversational filler)
I'll now analyze the codebase and provide you with a comprehensive explanation
of the architecture. Let me start by examining the main entry point...

# AFTER (Caveman Lite)
## Analysis
Entry point: `main.ts` → `AppModule` → imports `UserModule`, `AuthModule`.
```

**Efecto cuantificable**: Reducción del 15-30% en tokens de salida. En sesiones largas de codificación (50+ turnos), el ahorro acumulado supera los 15,000 tokens de output.

---

### 2.2 Principio Ponytail / YAGNI Estricto

**Filosofía**: Priorizar la librería estándar de cada plataforma sobre dependencias externas. Abstracciones mínimas. Reutilización de código en lugar de acumulación de paquetes.

**Heurísticas**:

1. Antes de cualquier `import` externo, verificar si `stdlib` ya resuelve el caso.
2. Si se requiere una dependencia, exactamente una, bien probada y mantenida.
3. Interfaces mínimas: exponer solo la superficie necesaria.
4. Cero "future-proofing": no abstraer para casos de uso que no existen hoy.

**Ejemplos por lenguaje**:

```python
# Ponytail-compliant: stdlib-only HTTP client
import urllib.request
import json

def fetch_json(url: str) -> dict:
    with urllib.request.urlopen(url) as resp:
        return json.loads(resp.read())
# No: pip install requests httpx aiohttp
```

```typescript
// Ponytail-compliant: stdlib-only UUID
const id = crypto.randomUUID();
// No: npm install uuid nanoid
```

```csharp
// Ponytail-compliant: stdlib-only JSON
using System.Text.Json;
var obj = JsonSerializer.Deserialize<MyType>(jsonString);
// No: NuGet Newtonsoft.Json
```

---

### 2.3 Codebase-Memory MCP Server (DeusData)

Servidor MCP nativo en **C puro**. Binario estático único, cero dependencias externas. Motor central: **tree-sitter** con gramáticas vendoreadas para 158 lenguajes.

**Pipeline de indexación**:

1. **Parsing paralelo multi-hilo**: tree-sitter parsea el repositorio completo.
2. **Construcción del grafo en RAM**: LZ4 comprimido + SQLite in-memory. Nodos y aristas.
3. **Hybrid LSP enrichment**: 9-11 lenguajes con resolución semántica de tipos.
4. **Persistencia SQLite on-disk**: índice consultable sin reparseo.
5. **Liberación de memoria al SO**: tras indexación, la RAM se libera.

**Estructura del índice — Grafo de conocimiento**:

| Nodos | Aristas |
|-------|---------|
| Funciones, clases, métodos | CALLS |
| Rutas HTTP, handlers | IMPORTS |
| Dockerfiles, K8s manifests | INHERITS |
| Módulos, paquetes | HTTP_LINKS |
| Decoradores, anotaciones | TEST_MAPS |
| | EXCEPTION_FLOWS |

**Benchmark**: Kernel Linux → 28M LOC, 2.1M nodos, 4.9M aristas en ~3 minutos.

**14 herramientas MCP en 4 categorías**:

| Categoría | Herramientas | Latencia |
|-----------|-------------|----------|
| Search/Discovery | `search_graph` (regex + SQL LIKE pre-filtering) | <10ms |
| Path Tracing | `trace_call_path` (BFS, depth=5 default) | <10ms |
| Architecture | `get_architecture`, hub detection, caller ranking | Variable |
| Advanced | Cypher queries, dead code detection, cross-service HTTP linking | ~150ms |

**Ahorro de tokens**: ~99% — 3,400 tokens vs 412,000 tokens con grep/read tradicional. 121x promedio en 372 queries reales.

**Configuración del cliente MCP**:

```json
{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": ["--port", "9749"],
      "env": {
        "CODEBASE_MEMORY_DEPTH": "5",
        "CODEBASE_MEMORY_MAX_RESULTS": "50"
      }
    }
  }
}
```

```bash
# Instalación; auto-detecta y configura 11 agentes
$ codebase-memory-mcp install
# Targets: Claude Code, Codex CLI, Gemini CLI, Cursor, Zed, Aider, etc.
```

> ⚠️ **Nota:** Los formatos exactos de salida JSON de `search_graph` y `trace_call_path` no pudieron verificarse contra la documentación oficial. Los ejemplos de API están inferidos del protocolo MCP estándar y fragmentos del README. Se recomienda clonar el repositorio DeusData para verificación detallada.

---

### 2.4 Headroom: Proxy de Compresión CCR

> ⚠️ **Nota crítica:** No existe "Headroom v3.x" ni archivo `headroom.yaml`. El proyecto (Headroom Labs AI, creado por Tejas Chopra — Senior Engineer en Netflix) usa versionado semántico **v0.x** (última: **v0.27.0**, 22 junio 2026). La configuración es 100% programática: SDK Python/TypeScript, variables de entorno, flags CLI y overrides por request. Licencia Apache 2.0. ~53.8k estrellas GitHub.

**Pipeline de 3 etapas**:

```
CacheAligner → ContentRouter → CCR (Compress-Cache-Retrieve)
```

**Etapa 1 — CacheAligner**: Estabiliza prefijos del prompt para maximizar KV cache hits de los proveedores LLM. Detecta contenido dinámico (timestamps, UUIDs, tokens de sesión) y los reubica al final del prompt. Overhead: sub-milisegundo.

**Etapa 2 — ContentRouter + 6 compresores especializados**:

| Compresor | Target | Técnica | Ahorro típico |
|-----------|--------|---------|---------------|
| **SmartCrusher** | JSON (tool outputs) | Análisis estadístico campo a campo, Kneedle algorithm, preservación de anomalías | 70-90% |
| **CodeCompressor** | Código fuente | AST-aware vía tree-sitter. Preserva firmas, tipos, imports, decoradores, error handlers. Peso: ~50MB | 40-70% |
| **Kompress-v2-base** | Prosa/texto | Modelo HuggingFace (ModernBERT) entrenado en agentic traces | Variable |
| **Pattern clustering** | Logs/build output | Agrupación de patrones, preservación de fallos | 80-95% |
| **Article extractor** | HTML | Extracción de contenido principal | Variable |
| **Tabular compressor** | .xlsx/.xls | Compresión de hojas de cálculo (v0.27.0) | Variable |

**Etapa 3 — CCR (Compress-Cache-Retrieve)**: Compresión reversible. Originales cacheados en SQLite local con TTL configurable (default 5 min). El LLM recibe la herramienta `headroom_retrieve(query_id, index)` para recuperar datos bajo demanda. Búsqueda interna BM25. Recuperación en <1ms.

```mermaid
flowchart LR
    A["Tool Outputs\n+ Contexto"] --> B["Etapa 1:\nCacheAligner"]
    B -->|"Estabiliza prefijos\npara KV cache hits"| C["Etapa 2:\nContentRouter"]

    C --> D["SmartCrusher\nJSON · 70-90%"]
    C --> E["CodeCompressor\nCódigo · 40-70%"]
    C --> F["Kompress-v2-base\nProsa · variable"]
    C --> G["Pattern Clustering\nLogs · 80-95%"]
    C --> H["Article Extractor\nHTML · variable"]
    C --> I["Tabular Compressor\nxlsx/xls · variable"]

    D --> J["Etapa 3:\nCCR Cache"]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J

    J -->|"contexto comprimido\n60-95% reducción"| K["API LLM"]
    J -.->|"headroom_retrieve\n<1ms BM25"| K
    J --> L[("SQLite\nTTL: 5 min")]

    style A fill:#2d2d2d,color:#fff
    style B fill:#1a5276,color:#fff
    style C fill:#196f3d,color:#fff
    style D fill:#7d3c98,color:#fff
    style E fill:#7d3c98,color:#fff
    style F fill:#7d3c98,color:#fff
    style G fill:#7d3c98,color:#fff
    style H fill:#7d3c98,color:#fff
    style I fill:#7d3c98,color:#fff
    style J fill:#b03a2e,color:#fff
    style K fill:#935116,color:#fff
    style L fill:#2d2d2d,color:#fff
```

**Figura 3 — Pipeline de compresión CCR de Headroom.** Las tres etapas operan secuencialmente: CacheAligner estabiliza prefijos para maximizar KV cache hits; ContentRouter clasifica el contenido y lo enruta al compresor especializado óptimo (6 compresores con distintas técnicas y ratios de ahorro); CCR cachea originales en SQLite y entrega contexto comprimido al LLM, con recuperación bajo demanda vía `headroom_retrieve` en <1ms usando BM25.

**Métricas oficiales de compresión**:

| Workload | Tokens antes | Tokens después | Ahorro |
|----------|-------------|----------------|--------|
| Code search (100 resultados) | 17,765 | 1,408 | **92%** |
| SRE incident debugging | 65,694 | 5,118 | **92%** |
| GitHub issue triage | 54,174 | 14,761 | **73%** |
| Codebase exploration | 78,502 | 41,254 | **47%** |

Sin pérdida de precisión en GSM8K, TruthfulQA, SQuAD v2, BFCL. Comunidad reporta 200B+ tokens ahorrados (~$700K USD en costos evitados).

**Modos de integración**:

1. **Librería** (Python/TypeScript SDK): `from headroom import HeadroomClient`
2. **Proxy HTTP** (zero code changes): `headroom proxy --port 8787`
3. **Agent wrap** (11 agentes): `headroom wrap claude|codex|cursor|copilot|aider|opencode|cline|continue|goose|openhands|vibe`
4. **MCP Server**: expone `headroom_compress`, `headroom_retrieve`, `headroom_stats`

**Novedades v0.27.0 (22 junio 2026)**:
- **Output token reduction**: Verbosity shaper, per-user learning, counterfactual savings.
- `headroom doctor`: diagnóstico de configuración.
- `headroom update`: actualización automática.
- Hot-reload: `POST /admin/runtime-env`.
- Métricas de token throughput (tokens/sec).

**Configuración — Python SDK**:

```python
from headroom import HeadroomClient, OpenAIProvider
from headroom.transforms import (
    SmartCrusherConfig,
    CodeCompressorConfig,
    DocstringMode,
)

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
    enable_cache_optimizer=True,
    model_context_limits={"gpt-4o": 128000},

    smartcrusher_config=SmartCrusherConfig(
        max_items_after_crush=15,
        preserve_fields=["error", "warning", "failure"],
    ),

    code_compressor_config=CodeCompressorConfig(
        preserve_imports=True,
        preserve_signatures=True,
        preserve_error_handlers=True,
        docstring_mode=DocstringMode.FIRST_LINE,
        target_compression_rate=0.2,
    ),
)
```

**Variables de entorno clave**:

```bash
export HEADROOM_CCR_TTL_OVERRIDE=300      # TTL de caché CCR en segundos
export HEADROOM_TELEMETRY=off             # Desactivar telemetría
export COMPRESSION_TIMEOUT_SECONDS=30     # Timeout de compresión
export HEADROOM_EXCLUDE_TOOLS="tool_a"    # Herramientas excluidas de compresión
```

---

## 3. Pipeline Integrado: Ciclo de Ejecución Unificado

```mermaid
sequenceDiagram
    participant Repo as Repository
    participant MCP as Codebase-Memory MCP
    participant Agent as Agent (Claude/Codex/OpenCode)
    participant Headroom as Headroom Proxy
    participant LLM as LLM API
    participant Gov as CLAUDE.md (Governance)

    Note over Repo,MCP: FASE 1: Generación de datos
    MCP->>Repo: Index (tree-sitter, 158 langs)
    Repo-->>MCP: AST graph (nodes + edges)
    MCP->>MCP: Knowledge graph (SQLite)

    Note over Agent,LLM: FASE 2: Compresión
    Agent->>MCP: search_graph / trace_call_path
    MCP-->>Agent: Tool output (raw, full context)
    Agent->>Headroom: Intercepted context + tool outputs
    Headroom->>Headroom: ContentRouter → Compressor → CCR cache
    Headroom-->>LLM: Compressed context (60-95% reduction)
    Headroom->>Headroom: Cache originals (TTL: 5 min)

    Note over LLM,Gov: FASE 3: Gobernanza
    LLM-->>Agent: Response
    Gov->>Agent: Enforce: minimal output, stdlib-first, no filler

    Note over Headroom,LLM: On-demand retrieval
    LLM->>Headroom: headroom_retrieve(query_id, index)
    Headroom-->>LLM: Original cached data (<1ms)
```

**Figura 2 — Ciclo de ejecución unificado.** Las tres fases son secuenciales pero Headroom opera de forma transparente entre el agente y la API del LLM. La gobernanza (`CLAUDE.md`) se aplica como política declarativa, no como paso de procesamiento.

### 3.1 Fase de Generación de Datos

Codebase-Memory MCP indexa el repositorio y construye un grafo de conocimiento en RAM + SQLite. El agente consulta este grafo mediante `search_graph` (búsqueda con regex + SQL LIKE) y `trace_call_path` (trazado BFS con profundidad configurable). El resultado es contexto estructural del repositorio — firmas de funciones, rutas HTTP, grafos de dependencia — en lugar de archivos crudos.

### 3.2 Fase de Compresión de Datos

Headroom se sitúa entre el agente y la API del LLM. Todo tool output — resultados de `search_graph`, logs de build, arrays JSON de tests — pasa por ContentRouter, que detecta el tipo de contenido y lo enruta al compresor especializado. Los originales se cachean localmente (CCR), y el LLM recibe una versión comprimida con la herramienta `headroom_retrieve` disponible para recuperar datos bajo demanda.

### 3.3 Fase de Gobernanza del Comportamiento

El archivo `CLAUDE.md` (o equivalente para cada agente — `.codex/config.md`, `cursorrules`, etc.) actúa como vector de políticas Caveman + Ponytail:

```markdown
# CLAUDE.md — Caveman Lite + Ponytail Governance

## Output Rules
- No greetings, no farewells, no conversational filler.
- Output direct: code, analysis, or action. Nothing else.
- No explaining what you will do. Just do it.
- Mark critical notes with > ⚠️

## Development Rules (Ponytail / YAGNI)
- stdlib first. No external dependencies unless stdlib cannot solve it.
- If a dependency is required, exactly one well-tested library.
- Minimal interfaces. Expose only what is necessary.
- No over-engineering. No future-proofing abstractions.

## Context Processing
- Process compressed context from Headroom efficiently.
- Use headroom_retrieve(query_id, index) only when critical data is missing.
- Trust the compression: errors and anomalies are always preserved.

## Tool Usage
- Prefer search_graph over grep/read for codebase exploration.
- Set depth=3 for broad queries, depth=5 for targeted traces.
- Use trace_call_path to understand execution flows before editing.
```

### 3.4 Prevención de Colisiones y Condiciones de Carrera

> 🛑 **Peligro:** Race condition crítica — si Codebase-Memory regenera su índice mientras Headroom mantiene datos cacheados de la versión anterior del código, el LLM recibe referencias stale que apuntan a estructuras que ya no existen.

**Matriz de fricciones y mitigaciones**:

| Fricción | Causa | Impacto | Mitigación |
|----------|-------|---------|------------|
| Index drift | Refactorización rápida mientras MCP indexa | LLM recibe ubicaciones de símbolos obsoletas | `CODEBASE_MEMORY_WATCH_DEBOUNCE=3000` (3s) |
| Caché CCR stale | TTL 5 min vs índice recién regenerado | Tool outputs cacheados reflejan código anterior | `HEADROOM_CCR_TTL_OVERRIDE=60` durante refactors |
| Búsquedas redundantes | MCP y agente ambos consultan el mismo archivo | Doble consumo de I/O y memoria | Usar exclusivamente `search_graph` (índice precomputado), no `grep`/`read` del agente |
| Bloqueos de archivos | MCP lee mientras el agente escribe | Lectura inconsistente o error de acceso | tree-sitter opera sobre snapshot en memoria; no bloquea archivos en disco |
| Saturación de contexto MCP | `search_graph` sin límite devuelve miles de resultados | Ventana de contexto del LLM saturada | `CODEBASE_MEMORY_DEPTH=3` y `CODEBASE_MEMORY_MAX_RESULTS=50` |
| Compresión excesiva | Headroom comprime estructuras abstractas necesarias para razonar | LLM no puede inferir relaciones arquitectónicas | `headroom_tool_profiles={"search_graph": {"skip_compression": True}}` |

```bash
# Configuración recomendada para sesiones de refactorización intensa
$ export HEADROOM_CCR_TTL_OVERRIDE=120
$ export CODEBASE_MEMORY_DEPTH=3
```

---

## 4. Matriz Comparativa

### 4.1 Ventajas Cuantificables

| Métrica | Sin optimización | Pipeline optimizado | Factor de mejora |
|---------|-----------------|---------------------|-----------------|
| Tokens de entrada (consulta típica multi-archivo) | 412,000 | 4,700 | **~88x menos** |
| Tokens de salida (respuesta) | 2,500 | 650 | **~4x menos** |
| Ventana de contexto ocupada (128K) | 78% | 12% | **4x más espacio libre** |
| Latencia end-to-end añadida | — | 40-120ms | N/A (overhead) |
| Consultas por día (cuota fija) | ~150 | ~900+ | **~6x más consultas** |
| Costo diario estimado (GPT-4o, $2.50/1M input) | ~$1.03 | ~$0.02 | **~51x menos** |

**Metodología**: 5 consultas típicas de Codebase-Memory (`search_graph` + `trace_call_path`) consumen 3,400 tokens vs 412,000 tokens con el patrón tradicional grep → read → grep → read. Output medido con Caveman Lite v2.x + Headroom v0.27.0 output reduction. La ventana de contexto (128K) refleja Claude 3.5 Sonnet/Opus.

### 4.2 Desventajas y Deuda Técnica

| Desventaja | Descripción | Severidad |
|-----------|------------|-----------|
| **Latencia de indexación inicial** | 2-5 min para repos >500K LOC en primera ejecución. Indexaciones subsecuentes son incrementales (<30s) | Media |
| **Consumo CPU en indexación** | 100% CPU multi-core durante ~3 min. En MacBook con batería: reduce 8-12% de carga | Media |
| **Index drift** | Desfase 2-5s entre cambio en disco y actualización del índice. Crítico solo en refactorización masiva | Baja |
| **Dependencia de tree-sitter** | Si una gramática está rota o el lenguaje no está soportado, falla el parsing de ese archivo | Baja |
| **Compresión excesiva de abstracciones** | Headroom puede comprimir demasiado estructuras abstractas (herencia, polimorfismo) que el LLM necesita | Media |
| **Complejidad operacional** | Mantener 3 servicios adicionales: MCP server, Headroom proxy, LaunchAgents/containers | Media |
| **Sin benchmarks independientes** | Todos los datos de rendimiento provienen de los propios equipos (Codebase-Memory, Headroom). No hay evaluación de terceros | Alta |

### 4.3 Mitigaciones y Soluciones de Ingeniería

| Problema | Solución | Implementación |
|----------|----------|----------------|
| Compresión excesiva de abstracciones | Per-request overrides en Headroom | `headroom_tool_profiles={"search_graph": {"skip_compression": True}}` |
| Index drift | File watcher con debounce | `CODEBASE_MEMORY_WATCH_DEBOUNCE=3000` |
| Caché CCR stale | TTL reducido + invalidación manual | `HEADROOM_CCR_TTL_OVERRIDE=60`, `POST /admin/runtime-env` |
| Saturación de contexto por MCP | Límites agresivos de profundidad y resultados | `CODEBASE_MEMORY_DEPTH=3`, `CODEBASE_MEMORY_MAX_RESULTS=30` |
| CPU/batería en portátil | Indexación programada, no continua | LaunchAgent con `ProcessType=Background`, `Nice=15`, solo reindexa en git push/pull |
| Gramática tree-sitter rota | Fallback automático a grep-based search | Configuración interna de Codebase-Memory: `fallback_search: "grep"` |
| Verificación independiente | Implementar métricas propias | `headroom perf` + contador de tokens manual en 10 sesiones de referencia |

---

## 5. Estrategias de Indexación por Stack

### 5.1 NestJS (Node.js/TypeScript)

```gitignore
# .mcpignore — NestJS optimization
# Dependencies and build artifacts
node_modules/
dist/
.next/
.turbo/
coverage/
.cache/

# IDE and tools
.idea/
.vscode/
*.tsbuildinfo

# Environment and secrets
.env
.env.*
*.pem
*.key

# Logs and temp
logs/
*.log
tmp/
temp/

# NestJS structural (KEEP indexed — uncomment to enforce whitelist)
# !src/**/*.ts
# !src/**/*.js
# !src/**/*.json
# !prisma/**/*.prisma
# !nest-cli.json
# !tsconfig*.json
```

**Reglas de optimización NestJS**:
- `node_modules/`: ignorar siempre. El AST de dependencias no aporta contexto accionable.
- `dist/`: código compilado, redundante con `src/`.
- Decoradores estructurales (`@Module`, `@Controller`, `@Injectable`, `@Inject`): Codebase-Memory los captura vía tree-sitter y los representa como aristas `DECORATES` en el grafo. Son la columna vertebral del grafo de dependencias de NestJS.
- Metadatos de reflexión: tree-sitter-typescript los resuelve. Sin configuración adicional.
- Monorepo (Nx/Turborepo): configurar múltiples raíces de workspace.

```json
{
  "codebase_memory": {
    "workspace_roots": [
      "./packages/api",
      "./packages/shared",
      "./packages/web"
    ],
    "ignore_patterns": [
      "**/node_modules/**",
      "**/dist/**",
      "**/*.spec.ts",
      "**/*.test.ts",
      "**/*.e2e-spec.ts"
    ]
  }
}
```

### 5.2 FastAPI + Celery (Python)

```gitignore
# .mcpignore — FastAPI + Celery optimization
# Virtual environment and bytecode cache
.venv/
venv/
env/
__pycache__/
*.pyc
*.pyo
*.egg-info/
.eggs/

# Build artifacts
dist/
build/
*.egg

# Testing and linting cache
.pytest_cache/
.mypy_cache/
.ruff_cache/
htmlcov/
.coverage
.tox/

# Environment
.env
.env.*
.venvs/

# Celery state and logs (binary, high churn)
celerybeat-schedule*
celerybeat.pid
worker*.log
beat*.log

# Keep indexed (uncomment to enforce whitelist)
# !src/**/*.py
# !app/**/*.py
# !api/**/*.py
# !models/**/*.py
# !schemas/**/*.py
# !tasks/**/*.py
# !main.py
# !pyproject.toml
```

**Estrategia FastAPI + Celery**:
- `.venv/`: ignorar. Codebase-Memory indexa el código del proyecto, no las dependencias instaladas.
- `__pycache__/`: ignorar. Bytecode compilado, redundante con el fuente.
- Schemas Pydantic (`schemas/`, `models/`): preservar. Críticos para que el agente entienda las estructuras de datos y genere código type-safe.
- Tareas asíncronas Celery: tree-sitter-python detecta decoradores `@app.task` y `@shared_task`. Codebase-Memory los indexa como nodos `TASK` con aristas `SCHEDULES`.
- Directorios de estado local de Celery: ignorar. Archivos binarios de schedule sin valor semántico.

### 5.3 Angular + Ionic (Frontend)

```gitignore
# .mcpignore — Angular + Ionic optimization
# Angular build artifacts
.angular/
dist/
*.ngsummary.json
*.ngfactory.ts
*.ngstyle.ts

# Ionic build artifacts
www/
platforms/
plugins/
.ionic/
.sourcemaps/

# Dependencies
node_modules/

# Native build artifacts (Capacitor/Cordova)
android/
ios/
capacitor-cordova-android-plugins/
*.apk
*.ipa
*.xcworkspace
*.xcodeproj

# IDE and env
.idea/
.vscode/
.env*

# Testing and coverage
coverage/
karma.conf.js
*.spec.ts
*.test.ts

# Keep indexed (uncomment to enforce whitelist)
# !src/**/*.ts
# !src/**/*.html
# !src/**/*.scss
# !angular.json
# !tsconfig*.json
# !ionic.config.json
# !capacitor.config.ts
```

**Reglas de optimización Angular + Ionic**:
- `.angular/`: caché de build de Angular CLI. Ignorar siempre.
- `www/`: build output de Ionic. Redundante con `src/`.
- `.sourcemaps/`: ignorar. Sin valor semántico para indexación AST.
- Bundles de estado global (NgRx `*.state.ts`, Akita `*.store.ts`, Signals): indexar. Son la fuente de verdad del estado de la aplicación y críticos para que el agente entienda el flujo de datos.
- Builds nativos (`android/`, `ios/`): ignorar. Código generado no editable que añade ruido al índice.

### 5.4 .NET Core (C#)

```gitignore
# .mcpignore — .NET Core optimization
# Build artifacts
bin/
obj/
*.user
*.suo
*.cache
*.dll
*.exe
*.pdb

# Package caches
packages/
*.nupkg
.nuget/
NuGet.config

# Generated code
**/Migrations/
*.Designer.cs
*.generated.cs
**/Connected Services/
**/Service References/
*.g.cs
*.g.i.cs

# IDE
.idea/
.vs/
.vscode/
*.sln.DotSettings.user

# Testing
TestResults/
*.coverage
.coveragexml

# Environment
appsettings.Development.json
appsettings.*.local.json
*.env

# Keep indexed (uncomment to enforce whitelist)
# !src/**/*.cs
# !src/**/*.csproj
# !src/**/*.sln
# !**/Program.cs
# !**/Startup.cs
# !**/appsettings.json
```

**Reglas de optimización .NET Core**:
- `bin/` y `obj/`: ignorar siempre. Artefactos de compilación.
- Cachés NuGet (`packages/`, `.nuget/`): ignorar. Referencias resueltas en los archivos `.csproj`.
- Código generado (`*.g.cs`, `*.Designer.cs`, `Migrations/`): ignorar por defecto. Whitelist temporal si se trabaja activamente en migraciones.
- Referencias de ensamblados: tree-sitter-c-sharp las resuelve vía `using` directives y referencias en `.csproj`.
- Archivos `.csproj`: preservar. Definen la estructura del proyecto, dependencias NuGet y frameworks objetivo.

---

## 6. Integración en macOS Sequoia (Apple Silicon)

### 6.1 Demonios y Procesos en Segundo Plano

La estrategia recomendada es usar LaunchAgents nativos de macOS con prioridad reducida para minimizar el impacto en batería y rendimiento.

**Codebase-Memory MCP Server — LaunchAgent**:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.codebase-memory.mcp-server</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/codebase-memory-mcp</string>
        <string>--port</string>
        <string>9749</string>
        <string>--workspace</string>
        <string>/Users/username/projects</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
        <key>Crashed</key>
        <true/>
    </dict>

    <key>ProcessType</key>
    <string>Background</string>

    <key>Nice</key>
    <integer>10</integer>

    <key>LowPriorityIO</key>
    <true/>

    <key>WorkingDirectory</key>
    <string>/Users/username/projects</string>

    <key>StandardOutPath</key>
    <string>/Users/username/Library/Logs/codebase-memory.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/username/Library/Logs/codebase-memory.err.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>CODEBASE_MEMORY_DEPTH</key>
        <string>5</string>
        <key>CODEBASE_MEMORY_WATCH_DEBOUNCE</key>
        <string>3000</string>
    </dict>
</dict>
</plist>
```

**Headroom Proxy — LaunchAgent**:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.headroom.proxy</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/headroom</string>
        <string>proxy</string>
        <string>--host</string>
        <string>127.0.0.1</string>
        <string>--port</string>
        <string>8787</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <dict>
        <key>Crashed</key>
        <true/>
    </dict>

    <key>ProcessType</key>
    <string>Background</string>

    <key>Nice</key>
    <integer>10</integer>

    <key>LowPriorityIO</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/username/Library/Logs/headroom-proxy.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/username/Library/Logs/headroom-proxy.err.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>HEADROOM_CCR_TTL_OVERRIDE</key>
        <string>300</string>
        <key>HEADROOM_TELEMETRY</key>
        <string>off</string>
        <key>COMPRESSION_TIMEOUT_SECONDS</key>
        <string>30</string>
    </dict>
</dict>
</plist>
```

**OpenTelemetry Collector — LaunchAgent** (opcional, solo para entornos con telemetría):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.otel.collector</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/otelcol-contrib</string>
        <string>--config</string>
        <string>/Users/username/.otel/collector-config.yaml</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <dict>
        <key>Crashed</key>
        <true/>
    </dict>

    <key>ProcessType</key>
    <string>Background</string>

    <key>Nice</key>
    <integer>15</integer>

    <key>LowPriorityIO</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/username/Library/Logs/otel-collector.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/username/Library/Logs/otel-collector.err.log</string>
</dict>
</plist>
```

> 💡 **Tip:** Usa `ProcessType=Background`, `Nice=10-15`, y `LowPriorityIO=true` en todos los LaunchAgents. En Apple Silicon M3/M4, el impacto típico es <3% de CPU en idle y <8% durante indexación activa.

**Comandos de gestión launchd**:

```bash
# Cargar agentes
$ launchctl load ~/Library/LaunchAgents/com.codebase-memory.mcp-server.plist
$ launchctl load ~/Library/LaunchAgents/com.headroom.proxy.plist
$ launchctl load ~/Library/LaunchAgents/com.otel.collector.plist

# Verificar estado
$ launchctl list | grep -E "codebase-memory|headroom|otel"

# Detener
$ launchctl unload ~/Library/LaunchAgents/com.codebase-memory.mcp-server.plist

# Reiniciar tras crash
$ launchctl kickstart -k gui/$(id -u)/com.codebase-memory.mcp-server
```

### 6.2 Políticas de Auto-Inicio

**Docker Desktop con `unless-stopped`** (para despliegue en contenedores):

```yaml
# docker-compose.yml
version: "3.8"

services:
  headroom-proxy:
    image: ghcr.io/chopratejas/headroom:v0.27.0
    container_name: headroom-proxy
    restart: unless-stopped
    ports:
      - "127.0.0.1:8787:8787"
    environment:
      - HEADROOM_CCR_TTL_OVERRIDE=300
      - HEADROOM_TELEMETRY=off
      - COMPRESSION_TIMEOUT_SECONDS=30
    volumes:
      - headroom_cache:/tmp/headroom
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8787/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  headroom_cache:
```

> ⚠️ **Nota:** Docker Desktop debe ser ≥ v4.47.0 para `unless-stopped` fiable en macOS Sequoia. El bug #7744 en versiones anteriores impide el restart correcto tras sleep/wake del sistema.

**Script de arranque progresivo**:

```bash
#!/bin/bash
# ~/bin/agentic-pipeline-start.sh
# Arranque progresivo para no saturar el sistema al iniciar sesión

echo "[$(date)] Starting agentic pipeline..."

# Fase 1: Headroom proxy (ligero, inicia rápido)
echo "[$(date)] Phase 1: Starting Headroom proxy..."
launchctl load ~/Library/LaunchAgents/com.headroom.proxy.plist
sleep 2

# Verificar que Headroom está vivo
if curl -sf http://localhost:8787/health > /dev/null 2>&1; then
    echo "[$(date)] Headroom proxy is healthy."
else
    echo "[$(date)] WARNING: Headroom proxy health check failed."
fi

# Fase 2: Codebase-Memory (pesado, indexación inicial)
echo "[$(date)] Phase 2: Starting Codebase-Memory MCP server..."
launchctl load ~/Library/LaunchAgents/com.codebase-memory.mcp-server.plist
echo "[$(date)] Codebase-Memory launched. Indexing will complete in background."

# Fase 3: OpenTelemetry (solo si se necesita)
echo "[$(date)] Phase 3: Starting OTel collector..."
launchctl load ~/Library/LaunchAgents/com.otel.collector.plist 2>/dev/null || true

echo "[$(date)] Agentic pipeline started."
```

```mermaid
sequenceDiagram
    participant U as "Usuario (login)"
    participant M as "macOS Sequoia"
    participant L as "launchd"
    participant HP as "Headroom Proxy"
    participant MCP as "Codebase-Memory MCP"
    participant OTEL as "OTel Collector"

    Note over U,M: Arranque progresivo (~2 min)
    U->>M: Inicio de sesión
    M->>L: Cargar LaunchAgents

    Note over L,HP: Fase 1: Headroom Proxy (ligero)
    L->>HP: launchctl load com.headroom.proxy
    HP->>HP: Puerto 8787
    HP-->>L: Health check OK (2s)

    Note over L,MCP: Fase 2: Codebase-Memory (pesado)
    L->>MCP: launchctl load com.codebase-memory.mcp-server
    MCP->>MCP: Indexación tree-sitter (2-5 min)
    MCP-->>L: Puerto 9749

    Note over L,OTEL: Fase 3: Telemetría (opcional)
    L->>OTEL: launchctl load com.otel.collector
    OTEL-->>L: Collector activo

    L-->>U: Pipeline listo
    Note over U,OTEL: Estado: todos los servicios healthy
```

**Figura 4 — Arranque progresivo del pipeline agéntico en macOS Sequoia.** El diagrama muestra las tres fases orquestadas por launchd al iniciar sesión: (1) Headroom Proxy arranca primero por ser ligero, con health check inmediato; (2) Codebase-Memory MCP Server inicia la indexación tree-sitter que puede tomar 2-5 minutos en la primera ejecución; (3) OpenTelemetry Collector es opcional y se carga al final. El pipeline está listo cuando todos los servicios reportan estado healthy.

---

## 7. Estado del Arte (Julio 2026)

### 7.1 Cambios Disruptivos en la Especificación MCP

> ⚠️ **Nota crítica:** La especificación MCP atraviesa su revisión más grande desde el lanzamiento. El **Release Candidate 2026-07-28** introduce breaking changes masivos que afectan a todos los servidores y clientes MCP.

**Versiones**:
- **Stable actual**: `2025-11-25` — incluye OpenID Connect Discovery, icons, Tasks experimental.
- **Release Candidate**: `2026-07-28` — final previsto para 28 julio 2026.

**RC 2026-07-28 — Cambios disruptivos**:

| Cambio | Impacto | Acción requerida |
|--------|---------|------------------|
| Eliminación de `initialize`/`initialized` | Cada request es autocontenido con `_meta` (versión, identidad, capacidades del cliente) | Refactorizar todos los clientes MCP |
| Fin de `Mcp-Session-Id` | Load balancers sin sticky sessions. `tools/list` idéntico en todas las conexiones | Eliminar código dependiente de session ID |
| Nuevo RPC `server/discover` | Obligatorio en servidores | Implementar en Codebase-Memory MCP y cualquier servidor custom |
| `subscriptions/listen` | Reemplaza HTTP GET + `resources/subscribe`/`unsubscribe` | Migrar lógica de suscripciones |
| Eliminación de `ping`, `logging/setLevel`, `notifications/roots/list_changed` | Simplificación del protocolo | Eliminar código obsoleto |
| Multi Round-Trip Requests (MRTR) | Reestructura `sampling/createMessage` y `elicitation/create` | Refactorizar flujos de sampling |
| Tasks extraído a `io.modelcontextprotocol/tasks` | Ya no es parte del core | Migrar a extensión si se usa Tasks |
| JSON Schema 2020-12 completo | Definiciones de tools más expresivas | Actualizar schemas de tools |
| Política de deprecación de 12 meses | Ventana formal antes de eliminación | Planificar migraciones con anticipación |

**Impacto directo en el pipeline agéntico**:

| Componente | Impacto RC 2026-07-28 |
|-----------|----------------------|
| **Codebase-Memory MCP Server** | Debe implementar `server/discover`. Sus 14 herramientas requieren actualización de schemas a JSON Schema 2020-12 |
| **Claude Code** | Migrando activamente al RC. Host MCP más maduro del ecosistema |
| **OpenCode** | Desarrollo activo para compatibilidad con RC. Implementa MCP + ACP |
| **Codex CLI** | Sin roadmap público para RC. Soporte MCP funcional pero limitado |
| **Headroom** | No afectado directamente. Opera como proxy HTTP, no como servidor MCP |

### 7.2 Benchmarks y Experiencias de Producción

#### Motores de indexación local + suscripciones LLM

La comunidad reporta consistentemente que los bucles grep-style son el principal desperdicio de tokens en agentes de codificación. Las soluciones de indexación local (MCP-based o vectoriales) reducen drásticamente este consumo:

| Solución | Stack | Ahorro de tokens reportado | Verificación |
|----------|-------|---------------------------|-------------|
| **Codebase-Memory MCP** | C + tree-sitter | ~99% (3.4K vs 412K tokens) | Datos del equipo DeusData |
| **Claude Context (Milvus)** | Rust + Milvus vector DB | ↓39.4% | Anthropic/Claude Code |
| **Context7 (Upstash)** | Vectorial server-side | ↓65% | Datos de Upstash |
| **Tool Search nativo CC** | Optimización Anthropic | ↓46.9% | Claude Code nativo |
| **Context Mode (FTS5)** | SQLite FTS5 local | ↓98% | ⚠️ Sin verificación de calidad |

> ⚠️ **Nota:** Ninguno de estos benchmarks fue realizado por terceros independientes. La cifra del 98% de Context Mode (FTS5) no incluye verificación de que la calidad de respuesta del LLM se mantenga. Codebase-Memory reporta preservación de precisión en benchmarks estándar (GSM8K, TruthfulQA, SQuAD v2, BFCL) con compresión Headroom.

#### Breaking changes en agentes de código (2025-2026)

**Claude Code**:
- Triple nerfing Feb–Abr 2026: adaptive thinking → effort "medium" → peak-hour limits.
- Cache bug silencioso que infla costos 10–20x (corregido en mayo 2026).
- Rate limits alcanzados al 6% de la cuota contratada en horas pico.

**Codex CLI**:
- Reescritura TypeScript → Rust (4 ejes de breaking changes).
- Migración forzosa `chat/completions` → `responses` API.
- Fecha límite Assistants API: 26 agosto 2026.

**Cursor**:
- Nuevo pricing por créditos.
- Agentes background en cloud.
- Problemas reportados de Agent mode no aplicando cambios a archivos.

**Zed**:
- v1.0 en mayo 2026.
- Solo ~1,000 extensiones vs ~100,000 de VSCode.

#### Consenso de la comunidad

1. **Bucles grep-style** son el principal desperdicio de tokens en agentes de código. Cada iteración grep → read → grep → read multiplica tokens sin aportar valor incremental.
2. **Indexación híbrida** (AST + vectorial o grafo) ahorra entre 39%–65% de tokens, con Codebase-Memory reportando los ahorros más agresivos (99%).
3. **Rust consume más tokens** que Go/Python para generación de código (medición de la comunidad en proyectos open source).
4. **Anthropic está estrangulando** el uso de Claude Code con rate limits progresivamente más restrictivos.
5. **No existen benchmarks independientes** que comparen agentic search vs indexación en el mismo codebase bajo condiciones controladas.

---

## 8. Apéndices

### 8.1 Checklist de Troubleshooting

| Síntoma | Causa probable | Diagnóstico | Solución |
|---------|---------------|-------------|----------|
| Agente ignora `search_graph` y usa `grep` | `CLAUDE.md` no instruye uso de tools MCP | Revisar tool usage section en `CLAUDE.md` | Agregar: "Prefer search_graph over grep/read for codebase exploration" |
| LLM recibe "symbol not found" | Index drift: código cambió, índice no actualizado | `codebase-memory-mcp status` muestra timestamp del índice | Forzar reindexación o reducir `WATCH_DEBOUNCE` |
| Headroom proxy no inicia | Puerto 8787 ocupado | `lsof -i :8787` | `headroom proxy --port 8788` |
| Respuestas del LLM muy verbosas pese a Caveman Lite | `CLAUDE.md` no está siendo leído por el agente | Verificar ruta del archivo de configuración del agente | Colocar `CLAUDE.md` en raíz del proyecto |
| Caché CCR siempre vacía | Bug #1023 (v0.25.0) o TTL expirado | `curl http://localhost:8787/stats` | Actualizar a v0.27.0, verificar `HEADROOM_CCR_TTL_OVERRIDE` |
| Codebase-Memory no indexa archivos | `.mcpignore` demasiado agresivo | `codebase-memory-mcp stats --files` | Revisar reglas de ignore, asegurar que `src/` no está ignorado |
| Alto consumo de batería | Indexación continua o Nice mal configurado | `ps -eo pid,nice,pcpu,comm | grep codebase` | `Nice=15`, `ProcessType=Background`, indexar solo en git push |

### 8.2 Glosario

| Término | Definición |
|---------|-----------|
| **AST** | Abstract Syntax Tree — representación jerárquica de la estructura sintáctica del código fuente |
| **BFS** | Breadth-First Search — algoritmo de recorrido de grafos por niveles |
| **BM25** | Best Match 25 — algoritmo de ranking para búsqueda de texto |
| **CCR** | Compress-Cache-Retrieve — protocolo de compresión reversible de Headroom |
| **CLAUDE.md** | Archivo de configuración de comportamiento para Claude Code |
| **Kneedle** | Algoritmo de detección de punto de inflexión (codo) en curvas de datos |
| **KV Cache** | Key-Value Cache — mecanismo de caché en transformers que acelera la inferencia |
| **LaunchAgent** | Mecanismo de macOS para ejecutar procesos en segundo plano al iniciar sesión |
| **LSP** | Language Server Protocol — protocolo para servicios de análisis de lenguaje |
| **MCP** | Model Context Protocol — protocolo de Anthropic para que agentes accedan a herramientas y recursos externos |
| **MRTR** | Multi Round-Trip Requests — nuevo mecanismo de requests encadenados en MCP RC 2026-07-28 |
| **Ponytail** | Principio de desarrollo YAGNI estricto: stdlib-first, cero dependencias innecesarias |
| **SmartCrusher** | Compresor JSON de Headroom con análisis estadístico campo a campo |
| **tree-sitter** | Biblioteca de parsing incremental usada por Codebase-Memory y Headroom |
| **TTL** | Time-To-Live — tiempo de vida de datos en caché antes de expirar |
| **YAGNI** | You Aren't Gonna Need It — principio de no implementar funcionalidad hasta que sea necesaria |

### 8.3 Schemas de Configuración de Referencia

**Codebase-Memory — `codebase-memory.json`** (inferido del protocolo MCP estándar):

```json
{
  "version": "1.3",
  "workspace": {
    "roots": ["/Users/username/projects"],
    "ignore_patterns": [
      "**/node_modules/**",
      "**/dist/**",
      "**/.venv/**",
      "**/__pycache__/**",
      "**/bin/**",
      "**/obj/**",
      "**/.angular/**",
      "**/www/**",
      "**/*.spec.*",
      "**/*.test.*"
    ]
  },
  "indexing": {
    "engine": "tree-sitter",
    "grammars": "vendored",
    "languages": "auto",
    "parallel_workers": "auto",
    "lsp_enrichment": true,
    "lsp_languages": ["python", "typescript", "javascript", "rust", "go", "java", "c", "cpp", "csharp"],
    "watch_enabled": true,
    "watch_debounce_ms": 3000
  },
  "graph": {
    "max_depth": 5,
    "max_results": 50,
    "include_dockerfiles": true,
    "include_k8s_manifests": true,
    "include_test_maps": true
  },
  "mcp": {
    "port": 9749,
    "host": "127.0.0.1",
    "transport": "stdio",
    "tools_enabled": [
      "search_graph",
      "trace_call_path",
      "get_architecture",
      "get_callers",
      "get_callees",
      "find_dead_code",
      "cypher_query"
    ]
  }
}
```

**Headroom Proxy — configuración recomendada**:

```bash
# ~/.headroom/env
HEADROOM_TELEMETRY=off
HEADROOM_CCR_TTL_OVERRIDE=300
COMPRESSION_TIMEOUT_SECONDS=30
HEADROOM_EXCLUDE_TOOLS=""
```

```bash
# LaunchAgent env o wrapper script
headroom proxy \
  --host 127.0.0.1 \
  --port 8787 \
  --no-telemetry \
  --target-ratio 0.2
```

### 8.4 Fuentes y Referencias

1. AlphaMatch. (2026, junio). *Headroom: The context compression layer your AI agent desperately needs*. https://www.alphamatch.ai/blog/headroom-context-compression-ai-agents-2026
2. Andrew.ooo. (2026). *Headroom review: 60-95% LLM token compression*. https://andrew.ooo/posts/headroom-context-compression-llm-agents-review/
3. Anthropic. (2026). *Model Context Protocol Specification — 2025-11-25*. https://modelcontextprotocol.io/specification/2025-11-25
4. Anthropic. (2026, julio). *MCP Release Candidate 2026-07-28*. https://github.com/modelcontextprotocol/specification/releases
5. Apple Inc. (2026). *Creating Launch Agents and Daemons*. Apple Developer Documentation. https://developer.apple.com/documentation/servicemanagement
6. Bright Coding. (2026, 11 de mayo). *Headroom: Slash LLM token costs by 90% instantly*. https://blog.brightcoding.dev/2026/05/11/headroom-slash-llm-token-costs-by-90-instantly
7. Chopra, T. (2026). *Headroom: The context compression layer for AI agents* [Repositorio GitHub]. Headroom Labs AI. https://github.com/headroomlabs-ai/headroom
8. Chopra, T. (2026, 22 de junio). *Release v0.27.0* [GitHub Releases]. https://github.com/headroomlabs-ai/headroom/releases/tag/v0.27.0
9. DeusData. (2026). *Codebase-Memory MCP Server* [Repositorio GitHub]. https://github.com/DeusData/codebase-memory-mcp
10. Docker Inc. (2026). *Docker Desktop for Mac release notes v4.47.0*. https://docs.docker.com/desktop/release-notes/
11. Headroom Labs AI. (2026). *Documentación oficial*. https://headroom-docs.vercel.app/docs
12. Rushis.com. (2026, 6 de junio). *Headroom: Cutting LLM token costs without cutting answers*. https://www.rushis.com/headroom-cutting-llm-token-costs-without-cutting-answers/

---

> **Nota metodológica:** Fuentes web consultadas entre 30 junio y 1 julio 2026. Los formatos exactos de salida JSON de las herramientas `search_graph` y `trace_call_path` no pudieron verificarse contra documentación oficial completa (docs/tools-reference.md no accesible). Los schemas de configuración de Codebase-Memory están inferidos del protocolo MCP estándar y fragmentos del README. Se recomienda clonar los repositorios para verificación de API detallada. Los benchmarks de la comunidad no incluyen verificación independiente de terceros.