Budgeted Reads lecturas con presupuesto

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 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
{ "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
• Agent Skills (progressive disclosure)
• Letta Context Repositories
• RAPTOR

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 #

Conceptos relacionados #

• Agent Memory (memoria del agente) Las notas que puedes leer y editar son la verdad. Los índices son una caché que puedes tirar.
• Agent Home (hogar del agente) Un directorio por rol, con historial. Archivos normales que puedes llevarte contigo.
• Flight Recorder (registrador de vuelo) Un registro por ejecución, encadenado por hashes, que incluye lo que la ejecución leyó.