# Budgeted Reads (lecturas con presupuesto)

*Lee un archivo como esquema, sección, rango de líneas o completo, degradando para ajustarse al presupuesto.*

> **Budgeted Reads** son lecturas medidas en un presupuesto de tokens: el mismo archivo se puede leer con distintos niveles de detalle, del esquema y la sección al rango de líneas y al texto completo. El agente pide “la mejor vista que quepa en N tokens” y recibe punteros de evidencia al origen exacto.

**AN-08** · Nivel de conformidad: L2 Memory · Grupo: Conocimiento

## El problema

Los agentes gastan su contexto en archivos enteros y lecturas repetidas, y la fragmentación ingenua de RAG pierde la estructura. Los modelos ya son buenos con `grep`, `tail` y la lectura por líneas: Cursor escribe en archivos las salidas de herramientas demasiado largas para que los agentes las lean bajo demanda, y en las ejecuciones que llamaron a una herramienta MCP, el [descubrimiento dinámico](https://cursor.com/blog/dynamic-context-discovery) de las descripciones de herramientas redujo el total de tokens un 46,9 %.

Así que el problema no es “construir otro sistema de recuperación”, sino dar a la lectura sobre archivos un contrato **con presupuesto y comprobable**.

## Cómo funciona

- **Primero los archivos.** Las lecturas estándar (incluidos los rangos de líneas) siempre están disponibles; Budgeted Reads es una extensión opcional por encima y no sustituye al sistema de archivos.
- **Esquemas deterministas (gratis):** el árbol de encabezados de Markdown, los símbolos de código (tree-sitter), las claves de JSON y YAML, los encabezados y el número de filas de CSV. No hace falta ningún LLM.
- **Presupuesto y degradación.** Una solicitud lleva `budget_tokens`; si no cabe, degrada a una vista más gruesa **en lugar de truncar en silencio**; la respuesta indica la vista real, el recuento de tokens y si es `generated`.
- **La búsqueda devuelve fragmentos y punteros,** no archivos enteros.
- **Punteros de evidencia:** `nas://<node>/<tree>/<path>@<commit>#L12-L18`, estables y verificables contra un commit; `dereference` devuelve el contenido exacto.
- **Qué ha cambiado desde la última vez:** devuelve el diff entre dos commits en lugar del archivo entero.
- **Una capa opcional de resúmenes con LLM:** como caché, marcada con `generated: true` y con una marca de obsolescencia.

## Empezar en pequeño

- No añadas nada más allá de `nas_read`: deja que el agente lea a la antigua usanza, con `rg` y `sed -n`.
- Después añade una pequeña herramienta de esquemas para Markdown y código.
- Empieza los punteros de evidencia como “path@commit#line”; no hace falta ningún servicio nuevo.

## Esbozo de la interfaz

Solo ilustrativo. Los nombres de los campos pueden cambiar antes de la especificación v0.3.

*POST /v1/files/read*

```http
POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }
```

## Lo que pide la especificación

- Una respuesta DEBE indicar la vista realmente devuelta y su recuento de tokens; las vistas generativas DEBEN marcarse.
- Cuando el presupuesto es demasiado pequeño, el NAS DEBE degradar a una vista más gruesa y NO DEBE truncar en silencio.
- Las lecturas estándar de archivos (incluidos los rangos) DEBEN seguir disponibles.
- Los punteros de evidencia DEBEN ser verificables contra un commit.
- La búsqueda DEBE devolver por defecto fragmentos y punteros en lugar de archivos enteros.

## Lo prestado y lo nuevo

La revelación progresiva y grep no son nuevos en sí mismos. **Lo nuevo:** convertir los presupuestos y los punteros de evidencia en un **contrato de lectura en la capa de almacenamiento**, de modo que las respuestas se puedan comprobar: de una frase se puede volver a las líneas del commit de donde salió.

- [Cursor: dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery)
- [Agent Skills (progressive disclosure)](https://agentskills.io/specification)
- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [RAPTOR](https://arxiv.org/abs/2401.18059)

## Límites honestos

- Los tokenizadores difieren entre modelos, así que los recuentos de tokens son estimaciones.
- Solo funciona si los clientes lo adoptan.
- Los resúmenes se quedan obsoletos y pueden ser erróneos, así que solo son una caché y siempre están marcados.

## Preguntas abiertas

- ¿Cómo debe tratarse el error de presupuesto entre los tokenizadores de distintos modelos?
- ¿Cómo se evalúa la calidad de los resúmenes?

## Preguntas

### ¿En qué se diferencia de RAG?

RAG devuelve los fragmentos más cercanos a una pregunta. Budgeted Reads deja que el lector elija el nivel de detalle de un objeto que ya conoce, degrada con honestidad cuando el presupuesto se queda corto y da punteros verificables. Se pueden combinar: los resultados de búsqueda también pueden volver como vistas con presupuesto.

### ¿Tengo que usarlo para leer archivos?

No. Los montajes y Git siempre dan archivos normales; Budgeted Reads es una lectura opcional para los agentes a los que les importan los tokens.

### ¿Un puntero de evidencia puede impedir las “citas inventadas”?

Hace que las citas se puedan comprobar: un puntero nombra líneas concretas de un commit y se puede verificar su hash de contenido. No impide que un modelo se invente cosas, pero convierte “¿existe realmente el pasaje que cita?” en una comprobación automática.

## Conceptos relacionados

- [Agent Memory (memoria del agente)](https://agentnas.com/es/concepts/agent-memory/): Las notas que puedes leer y editar son la verdad. Los índices son una caché que puedes tirar.
- [Agent Home (hogar del agente)](https://agentnas.com/es/concepts/agent-home/): Un directorio por rol, con historial. Archivos normales que puedes llevarte contigo.
- [Flight Recorder (registrador de vuelo)](https://agentnas.com/es/concepts/flight-recorder/): Un registro por ejecución, encadenado por hashes, que incluye lo que la ejecución leyó.

---

URL canónica: https://agentnas.com/es/concepts/budgeted-reads/
Actualizado: 2026-11-11 · Borrador de especificación v0.2 · CC BY 4.0