Filesystem-Based Memory for LLM Agents: Organization, Evolution, and Sustainability
Abstract
Deployed LLM agents increasingly keep their long-term memory as a filesystem: a directory tree of markdown files that the agent itself reads, writes, and reorganizes through generic file tools. Yet research has largely passed over this medium: prior systems design bespoke memory representations and study retrieval over them, leaving the default's two working assumptions untested: that an agent can keep a growing store organized as memories accumulate, conflict, and go stale, and that this organization pays. We present the first systematic exploration of filesystem-based memory for LLM agents. We formalize the setting as three roles around one memory filesystem: a management agent integrates and organizes incoming content, a search agent answers queries with cited sources, and an execution agent supplies task trajectories that are distilled into skills, unifying declarative memory and skills in a single store. Across long-conversation benchmarks and embodied tasks, we vary memory shape (agent-organized hierarchy, verbatim dump, chunk retrieval), stream scale, tool harness (sandboxed shell, memory-tool-style functions, varied search tooling), and the strengths of the management and search agents, tracking answer quality, cost, and store health as memory grows. What organization reliably buys is search economy: organized stores roughly halve retrieval cost where material is large. Today's agents, however, fall short of the default's promise: in our growth study, organization erodes for all but the strongest management agent, and no agent we measure converts organization itself into better answers. And the model is not the only lever over a store's shape: changing the tool set alone reshapes the store as strongly as swapping the model. The study turns the filesystem default from an assumption into a design space for agent memory.
Community
Filesystem-Based Memory for LLM Agents: Organization, Evolution, and Sustainability
Deployed agents increasingly keep long-term memory as a folder of markdown files that the agent itself reads, writes, and reorganizes with generic file tools. The default ships everywhere, but its two working assumptions were untested: can an agent keep a growing store organized, and does that organization pay?
We present the first systematic study of filesystem-based agent memory: one store class, three roles (a management agent that organizes, a search agent that answers with cited sources, an execution agent whose trajectories are distilled into skills), unifying declarative memory and skills in a single filesystem. Across long-conversation benchmarks and embodied tasks, we vary store shape, stream scale, tool harness, and the strength of every role, tracking answer quality, cost, and store health as memory grows.
Down at the file level, declarative memories and distilled skills share one anatomy: YAML frontmatter that listings and search expose first, nested headings that continue the taxonomy inside the file, and inline locators that tie each fact back to its source.
Some key findings:
- Organization buys search economy, not accuracy. Organized stores roughly halve retrieval cost on large material, yet no store shape wins answer quality everywhere, and no agent we measure converts organization itself into better answers.
- Memory form must match its consumer. A verbatim episode log leads under a strong execution agent and inverts under a weak one, where only the strongest curated skill store survives the drop.
- Sustainability is the real bottleneck. As memory grows, taxonomy discipline erodes for all but the strongest management agent.
- Tools are a hidden lever. Changing the tool harness alone reshapes the store as strongly as swapping the model.
- Growth still pays. Accumulated memory helped at every model we measured, with early memories holding their value.
Get this paper in your agent:
hf papers read 2607.26637 Don't have the latest CLI?
curl -LsSf https://hf.co/cli/install.sh | bash Models citing this paper 0
No model linking this paper
Datasets citing this paper 0
No dataset linking this paper
Spaces citing this paper 0
No Space linking this paper
Collections including this paper 0
No Collection including this paper