# Budgeted Reads (予算つき読み取り)

*ファイルを、アウトライン、節、行範囲、全文のいずれかで読みます。予算に収まるよう、段階的に粗くします。*

> **Budgeted Reads** は、トークン予算で測る読み取りです。同じファイルを、アウトライン、節、行範囲、全文と、異なる細かさで読めます。エージェントは「N トークンに収まる最良のビュー」を求め、正確な出典を指す証拠ポインタを受け取ります。

**AN-08** · 準拠レベル: L2 Memory · グループ: 知識

## 解決する課題

エージェントは、ファイル全体や繰り返しの読み取りでコンテキストを使い果たしますが、素朴な RAG のチャンク分割は構造を失います。モデルはすでに `grep`、`tail`、行を指定した読み取りが得意です。Cursor は長すぎるツール出力をファイルに書き出して、エージェントが必要に応じて読めるようにしており、MCP ツールを呼んだ実行では、ツール説明の [動的な発見](https://cursor.com/blog/dynamic-context-discovery) によって、トークンの合計が 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*

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

## 仕様が求めること

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

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

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

- [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)

## 正直な限界

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

## 未解決の問い

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

## よくある質問

### RAG と何が違うのですか？

RAG は、質問にいちばん近いスニペットを返します。Budgeted Reads は、すでに分かっているオブジェクトについて、読み手が細かさを選べ、予算が足りなければ正直に縮退し、検証できるポインタを返します。両者は重ねられます。検索結果も、予算つきのビューで返せます。

### ファイルを読むのに、これを必ず使う必要はありますか？

ありません。マウントと Git は、常に普通のファイルを渡します。Budgeted Reads は、トークンを気にするエージェントのための、任意の読み取りです。

### 証拠ポインタで、「でっち上げの引用」を防げますか？

引用を検査できるようにします。ポインタはコミットの特定の行を指し、その内容ハッシュを検証できます。モデルがでっち上げるのを止めるわけではありませんが、「引用した箇所は本当に存在するか」を、機械で確かめられる問いに変えます。

## 関連するコンセプト

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

---

正規 URL: https://agentnas.com/ja/concepts/budgeted-reads/
更新日: 2026-11-11 · 仕様ドラフト v0.2 · CC BY 4.0