Budgeted Reads budgetiertes Lesen

Das Problem #

Agenten verbrennen ihren Kontext an ganzen Dateien und wiederholten Lesezugriffen, und naives RAG-Chunking verliert Struktur. Modelle sind bereits gut in grep, tail und zeilenweisem Lesen: Cursor schreibt zu lange Tool-Ausgaben in Dateien, die Agenten bei Bedarf lesen, und bei Ausführungen, die ein MCP-Tool aufriefen, senkte die dynamische Entdeckung von Tool-Beschreibungen die Gesamtzahl der Token um 46,9 %.

Das Problem ist also nicht, „noch ein Retrieval-System zu bauen“, sondern dem Lesen auf Dateien einen budgetierten, überprüfbaren Vertrag zu geben.

So funktioniert es #

• Zuerst Dateien. Standardlesezugriffe (auch auf Zeilenbereiche) sind immer verfügbar; Budgeted Reads ist eine optionale Erweiterung obendrauf und ersetzt das Dateisystem nicht.
• Deterministische Gliederungen (kostenlos): der Überschriftenbaum von Markdown, Code-Symbole (tree-sitter), Schlüssel von JSON und YAML, Kopfzeilen und Zeilenanzahl von CSV. Ein LLM ist dafür nicht nötig.
• Budget und Abstufung. Eine Anfrage trägt budget_tokens; passt es nicht, wird auf eine gröbere Ansicht abgestuft statt stillschweigend abzuschneiden; die Antwort nennt die tatsächliche Ansicht, die Token-Zahl und ob sie generated ist.
• Die Suche liefert Ausschnitte und Zeiger, keine ganzen Dateien.
• Belegzeiger: nas://<node>/<tree>/<path>@<commit>#L12-L18, stabil und gegen einen Commit überprüfbar; dereference liefert den genauen Inhalt.
• Was sich seit dem letzten Mal geändert hat: liefert den Diff zwischen zwei Commits statt der ganzen Datei.
• Eine optionale LLM-Zusammenfassungsschicht: als Cache, mit generated: true markiert und mit einer Veraltungsmarkierung.

Klein anfangen #

• Fügen Sie nichts über nas_read hinaus hinzu: Lassen Sie den Agenten auf die alte Art lesen, mit rg und sed -n.
• Ergänzen Sie dann ein kleines Gliederungswerkzeug für Markdown und Code.
• Beginnen Sie Belegzeiger als „Pfad@Commit#Zeile“; ein neuer Dienst ist nicht nötig.

Schnittstellenskizze #

Nur zur Veranschaulichung. Feldnamen können sich vor der Spezifikation v0.3 ändern.

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" }
  ] }

Was die Spezifikation verlangt #

• Eine Antwort MUSS die tatsächlich gelieferte Ansicht und ihre Token-Zahl nennen; generative Ansichten MÜSSEN markiert sein.
• Ist das Budget zu klein, MUSS das NAS auf eine gröbere Ansicht abstufen und DARF NICHT stillschweigend abschneiden.
• Standard-Dateilesezugriffe (auch auf Bereiche) MÜSSEN verfügbar bleiben.
• Belegzeiger MÜSSEN gegen einen Commit überprüfbar sein.
• Die Suche MUSS standardmäßig Ausschnitte und Zeiger statt ganzer Dateien liefern.

Was übernommen ist und was neu ist #

Schrittweises Offenlegen und grep sind an sich nicht neu. Neu ist: Budgets und Belegzeiger zu einem Lesevertrag auf der Speicherebene zu machen, sodass sich Antworten überprüfen lassen: Man kommt von einem Satz zurück zu den Zeilen des Commits, aus denen er stammt.

• Cursor: dynamic context discovery
• Agent Skills (progressive disclosure)
• Letta Context Repositories
• RAPTOR

Ehrliche Grenzen #

• Tokenizer unterscheiden sich zwischen Modellen, daher sind Token-Zahlen Schätzungen.
• Es funktioniert nur, wenn Clients es übernehmen.
• Zusammenfassungen veralten und können falsch sein, daher sind sie nur ein Cache und immer markiert.

Offene Fragen #

• Wie soll der Budgetfehler über unterschiedliche Modell-Tokenizer hinweg behandelt werden?
• Wie wird die Qualität von Zusammenfassungen bewertet?

Fragen #

Verwandte Konzepte #

• Agent Memory (Agentengedächtnis) Notizen, die Sie lesen und bearbeiten können, sind die Wahrheit. Indizes sind ein Cache, den Sie wegwerfen können.
• Agent Home (Home-Verzeichnis) Ein Verzeichnis pro Rolle, mit Verlauf. Gewöhnliche Dateien, die Sie mitnehmen können.
• Flight Recorder (Flugschreiber) Ein Protokoll pro Ausführung, per Hash verkettet, das auch festhält, was gelesen wurde.