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는 정확한 내용을 돌려줍니다.
• 지난번 이후 바뀐 것: 파일 전체 대신 두 커밋 사이의 diff를 돌려줍니다.
• 선택적인 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 (플라이트 레코더) 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록.