Budgeted Reads 予算つき読み取り

解決する課題 #

エージェントは、ファイル全体や繰り返しの読み取りでコンテキストを使い果たしますが、素朴な RAG のチャンク分割は構造を失います。モデルはすでに grep、tail、行を指定した読み取りが得意です。Cursor は長すぎるツール出力をファイルに書き出して、エージェントが必要に応じて読めるようにしており、MCP ツールを呼んだ実行では、ツール説明の 動的な発見 によって、トークンの合計が 46.9% 減りました。

つまり問題は「もうひとつ検索システムを作る」ことではなく、ファイルの上の読み取りに、予算があり、検査できる 契約を与えることです。

仕組み #

• まずファイル。 標準的な読み取り（行範囲を含む）は常に使えます。Budgeted Reads は上に載る任意の拡張で、ファイルシステムの代わりにはなりません。
• 決定的なアウトライン（無料）： Markdown の見出しツリー、コードのシンボル（tree-sitter）、JSON と YAML のキー、CSV のヘッダーと行数。LLM は要りません。
• 予算と段階的な縮退。 リクエストは budget_tokens を持ちます。収まらなければ、黙って切り詰めず、より粗いビューに縮退します。レスポンスは、実際のビュー、トークン数、generated かどうかを示します。
• 検索は、ファイル全体ではなく、スニペットとポインタを返します。
• 証拠ポインタ： nas://<node>/<tree>/<path>@<commit>#L12-L18。安定していて、コミットに対して検証できます。dereference は正確な内容を返します。
• 前回からの変更： ファイル全体ではなく、2 つのコミットの差分を返します。
• 任意の LLM 要約層： キャッシュとして、generated: true と古さのマーカーをつけます。

小さく始める #

• nas_read 以外は何も足さない。エージェントには、rg と sed -n で、これまでどおりに読ませます。
• 次に、Markdown とコード用の小さなアウトラインツールを足します。
• 証拠ポインタは「path@commit#line」から始めます。新しいサービスは要りません。

インターフェースのスケッチ #

説明用の例です。フィールド名は仕様 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" }
  ] }

仕様が求めること #

• レスポンスは、実際に返したビューとそのトークン数を示さなければならない。生成的なビューには、その旨のマークをつけなければならない。
• 予算が小さすぎるとき、NAS はより粗いビューに縮退しなければならず、黙って切り詰めてはならない。
• 標準的なファイル読み取り（範囲指定を含む）は、使えるままでなければならない。
• 証拠ポインタは、コミットに対して検証できなければならない。
• 検索は、既定でファイル全体ではなく、スニペットとポインタを返さなければならない。

借りたものと、新しいもの #

段階的な開示や grep は、それ自体は新しくありません。新しいのは、 予算と証拠ポインタを ストレージ層の読み取りの契約 にして、答えを検査できるようにする点です。ひとつの文から、それが由来するコミットの行までたどれます。

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

正直な限界 #

• トークナイザーはモデルごとに違うため、トークン数は見積もりです。
• クライアントが採用してくれなければ機能しません。
• 要約は古くなり、誤ることもあるため、キャッシュにすぎず、常にマークをつけます。

未解決の問い #

• モデルごとのトークナイザーの違いによる、予算の誤差をどう扱うか。
• 要約の品質をどう評価するか。

よくある質問 #

関連するコンセプト #

• Agent Memory (エージェントの記憶) 読んで直せるノートが真実で、索引は捨てられるキャッシュです。
• Agent Home (エージェント・ホーム) ロールごとのディレクトリ。履歴つきで、普通のファイルのまま持ち出せます。
• Flight Recorder (フライトレコーダー) 実行ごとに、ハッシュでつながれた記録を残します。実行が何を読んだかも含みます。