Working Notes on Agent Systems/Brad Zhang

@teach_fireworks / X longform

Why does ClaudeCode use plain text + file system as its RAG system? Claude Code adopts a "plain text + file

Why does ClaudeCode use plain text + file system as its RAG system? Claude Code adopts a "plain text + file system" RAG design and completely abandons their...

April 10, 2026 · 2 min read

Why does ClaudeCode use plain text + file system as its RAG system? Claude Code adopts a "plain text + file
Figure 1 / source image

Why does ClaudeCode use plain text + file system as its RAG system? Claude Code adopts a "plain text + file system" RAG design and completely abandons their original vector-based RAG solution. According to Anthropic engineer Boris Cherny, this design was not determined from the beginning, but was an active choice after verification in practice. So I did some research and discussed this topic with some group friends. I would like to briefly share my summary, purely for the sake of technical reference, without any criticism. The core concepts of the current Claude Code RAG system:

  • "Do the Simple Thing First" (Do the Simple Thing First) This is the Unix philosophy that Boris Cherny has repeatedly emphasized. Claude Code is designed to be "a Unix tool, not a complex product" - the memory is the markdown file, the search is grep, and the prompt compression is simple summary. Complexity is introduced only when proven necessary.
  • From "Personal Experiment" to the Origin of Product Verification According to Cherny's recollection, Claude Code originated from a personal experiment: he gave the model a bash tool and observed it writing AppleScript independently to query the music library, and thus realized that "an agent with a tool is better than a pre-retrieval context script." This insight drove the entire design direction - agent topology (multiple agents working in parallel, each with a fresh, isolated context) is better than the cumulative pollution memory of a single large agent. Earlier versions did use RAG + local vector database, but the team found that Agentic Search performed "overwhelmingly better".

Visual summary

Article argument map

Generated from the post's content graph

FORMATTOPICCAPABILITYMARKETcoverscoverscoverscoverscoverssignalssignalssignalsFORMATlongform noteTOPICagentsTOPICtechnical distributionTOPICmemoryTOPICretrievalTOPICevaluationCAPABILITYagent workflowCAPABILITYevaluationCAPABILITYproduct surface
Mermaid outline
flowchart LR
  format-long_post["longform note"]
  topic-agents["agents"]
  topic-technical-distribution["technical distribution"]
  topic-memory["memory"]
  topic-retrieval["retrieval"]
  topic-evaluation["evaluation"]
  capability-agent-workflow["agent workflow"]
  capability-evaluation["evaluation"]
  capability-product-surface["product surface"]
  format-long_post -->|covers| topic-agents
  format-long_post -->|covers| topic-technical-distribution
  format-long_post -->|covers| topic-memory
  format-long_post -->|covers| topic-retrieval
  format-long_post -->|covers| topic-evaluation
  format-long_post -->|signals| capability-agent-workflow
  format-long_post -->|signals| capability-evaluation
  format-long_post -->|signals| capability-product-surface

Visual structure

Essay structure map

Built from summary and key paragraph positions

Why does ClaudeCode use plain text + file system as its RAG system? Claude Code adopt...THESISWhy does ClaudeCodeuse plain text + filesystem as its RAGsystem? Claude CodeSIGNALWhy does ClaudeCodeuse plain text + filesystem as its RAGsystem? Claude CodeOPERATOR1. "Do the SimpleThing First" (Do theSimple Thing First)This is the UnixIMPLICATION2. From "PersonalExperiment" to theOrigin of ProductVerification According
Mermaid outline
flowchart LR
  thesis["Why does ClaudeCode use plain text + file system as its RAG system? Claude Code adopts a \"plain text + file..."]
  signal["Why does ClaudeCode use plain text + file system as its RAG system? Claude Code adopts a \"plain text + file..."]
  operator["1. \"Do the Simple Thing First\" (Do the Simple Thing First) This is the Unix philosophy that Boris Cherny ha..."]
  implication["2. From \"Personal Experiment\" to the Origin of Product Verification According to Cherny's recollection, Cla..."]
  thesis -->|frames| signal
  signal -->|develops| operator
  operator -->|lands in| implication

Source: View the original post