# FILESYSTEM.md

> FILESYSTEM.md is a standardized, interoperable specification for Agent-Native Filesystems (ANF). It defines how AI coding agents interact with a project's filesystem — providing a dedicated, predictable structure for agent identity, memory, execution, and safety.

Think of FILESYSTEM.md as a README for agents: a markdown-first contract that any AI agent can read and follow, without proprietary lock-in.

If you are an agent starting a session, fetch https://filesystem.md/for-agents/cheatsheet.md first.
If you are building an agent filesystem runtime, start at https://filesystem.md/build.md.
For OS/cloud mounts, start at https://filesystem.md/infra.md.
For complete inline content, fetch https://filesystem.md/llms-full.txt.

## Metadata

- Site: https://filesystem.md/
- License: MIT
- Last updated: 2026-07-16
- Full context: https://filesystem.md/llms-full.txt
- HTML hub: https://filesystem.md/

## For Agents

- [Agent Cheatsheet](https://filesystem.md/for-agents/cheatsheet.md): One-page injectable operating card for FILESYSTEM.md agents.
- [For Agents](https://filesystem.md/for-agents.md): Operating manual hub — what to read, in what order, for coding agents.
- [Agent Bootstrap](https://filesystem.md/for-agents/bootstrap.md): Deterministic session bootstrap — inject order and what to defer.
- [Agent Operations](https://filesystem.md/for-agents/operations.md): Orient → plan → execute → log filesystem operation loop.
- [Agent Memory](https://filesystem.md/for-agents/memory.md): How to use MEMORY/daily, observations, and learned layers.
- [Agent Skills](https://filesystem.md/for-agents/skills.md): When and how to load SKILLS/*/SKILL.md on demand.
- [Agent Safety](https://filesystem.md/for-agents/safety.md): Workspace boundaries, secrets, append-only logs, and prohibited actions.
- [Claude Code Mapping](https://filesystem.md/for-agents/claude-code.md): Map FILESYSTEM.md procedures to Claude Code–style tools; links the public Claude Code study guide.

## Build (runtime)

- [Build an Agent Filesystem](https://filesystem.md/build.md): Virtual FS, tool layer, sandbox, and composite backends for agent runtimes.
- [Virtual Filesystem for Agents](https://filesystem.md/build/virtual-fs.md): Path-oriented virtual FS API agents can navigate with list/read/write semantics.
- [Agent Filesystem Tool Layer](https://filesystem.md/build/tools.md): Bind FS ops to agent tools — schemas, concurrency, FILESYSTEM.md mapping.
- [Sandboxing Agent Filesystems](https://filesystem.md/build/sandbox.md): Path jails, process sandboxes, network policy, and resettable workspaces.
- [Composite Filesystem Backends](https://filesystem.md/build/composite.md): Route path prefixes to local disk, SQLite, object stores, or DMS backends.

## Infrastructure

- [Filesystem Infrastructure](https://filesystem.md/infra.md): Linux VFS/FUSE, cloud shared FS (EFS-like), and mountable storage survey.
- [Linux VFS and FUSE for Agents](https://filesystem.md/infra/linux-fuse.md): Kernel VFS concepts and FUSE user mounts for agent-visible filesystems.
- [Cloud Filesystems for Agents](https://filesystem.md/infra/cloud-fs.md): EFS-like shared FS vs object storage for agent read/write loops.
- [Mountable Storage for Agent Workspaces](https://filesystem.md/infra/mounts.md): Bind mounts, NFS/EFS, FUSE gateways, and sandbox mount policy.

## Specification

- [Manifesto](https://filesystem.md/filesystem.md): Full ANF specification — core philosophy, workspace structure, context injection, memory model, skills, execution model, and security rules.
- [Getting Started](https://filesystem.md/getting-started.md): Step-by-step guide to adopt FILESYSTEM.md — core files, bootstrap sequence, memory layers, skills, and an adoption checklist.
- [Why Filesystems for Agents](https://filesystem.md/why-filesystems.md): Industry consensus on filesystem-first agents (Amplify, Vercel, Box, LangChain) and how FILESYSTEM.md fits as the workspace contract.
- [FAQ](https://filesystem.md/faq.md): Common questions about FILESYSTEM.md — what it is, how it differs from other standards, context injection, and secrets handling.
- [Compare Standards](https://filesystem.md/compare.md): How FILESYSTEM.md relates to AGENTS.md, harness adapters, optional identity overlays, and MCP.

## Community

- [Showcase](https://filesystem.md/showcase.md): Real-world projects and implementations using agent-native filesystem patterns.
- [Reading List](https://filesystem.md/readinglist.md): Curated references on agent-native design, context engineering, and filesystem conventions.
- [Community](https://filesystem.md/community.md): How to propose changes, submit examples, and contribute to the spec.

## Human-readable pages (optional)

- [Agent Cheatsheet](https://filesystem.md/for-agents/cheatsheet/)
- [For Agents](https://filesystem.md/for-agents/)
- [Agent Bootstrap](https://filesystem.md/for-agents/bootstrap/)
- [Agent Operations](https://filesystem.md/for-agents/operations/)
- [Agent Memory](https://filesystem.md/for-agents/memory/)
- [Agent Skills](https://filesystem.md/for-agents/skills/)
- [Agent Safety](https://filesystem.md/for-agents/safety/)
- [Claude Code Mapping](https://filesystem.md/for-agents/claude-code/)
- [Build an Agent Filesystem](https://filesystem.md/build/)
- [Virtual Filesystem for Agents](https://filesystem.md/build/virtual-fs/)
- [Agent Filesystem Tool Layer](https://filesystem.md/build/tools/)
- [Sandboxing Agent Filesystems](https://filesystem.md/build/sandbox/)
- [Composite Filesystem Backends](https://filesystem.md/build/composite/)
- [Filesystem Infrastructure](https://filesystem.md/infra/)
- [Linux VFS and FUSE for Agents](https://filesystem.md/infra/linux-fuse/)
- [Cloud Filesystems for Agents](https://filesystem.md/infra/cloud-fs/)
- [Mountable Storage for Agent Workspaces](https://filesystem.md/infra/mounts/)
- [Manifesto](https://filesystem.md/posts/filesystem-manifesto/)
- [Getting Started](https://filesystem.md/getting-started/)
- [Why Filesystems for Agents](https://filesystem.md/why-filesystems/)
- [FAQ](https://filesystem.md/faq/)
- [Compare Standards](https://filesystem.md/compare/)
- [Showcase](https://filesystem.md/showcase/)
- [Reading List](https://filesystem.md/readinglist/)
- [Community](https://filesystem.md/community/)

## Key Concepts

- **Agent-Native Filesystem (ANF)**: A filesystem structure designed for AI agents, not just humans.
- **Deterministic Bootstrap**: Read FILESYSTEM.md, inject AGENTS.md (and optional identity overlays), load recent memory, index skills.
- **Portable Behavior Contract**: Keep shared rules in AGENTS.md; treat CLAUDE.md / Cursor rules as thin adapters.
- **Virtual FS + tools**: Application path API and tool bindings agents call ([Build](https://filesystem.md/build.md)).
- **Composite backends**: One tree, many stores (local, SQLite, object/DMS).
- **On-Demand Loading**: Large memory and skill definitions are loaded only when required, conserving context window.
- **Append-Only Logs**: All agent actions are recorded, never silently overwritten — enabling auditability and recovery.
- **Security by Structure**: Clear read/write boundaries enforced through filesystem layout, not runtime code.

## Relationship to Other Standards

| Standard / Pattern | Scope |
|---|---|
| FILESYSTEM.md | Workspace contract for agent memory, operations, and loading rules |
| AGENTS.md | Shared, vendor-neutral behavior rules |
| CLAUDE.md / .cursor/rules / similar | Harness adapters — not a second source of truth |
| SOUL.md / USER.md | Optional identity and preference overlays |
| MCP | Tool and data connectivity protocol |

Together: FILESYSTEM.md (filesystem contract) + AGENTS.md + thin harness adapters + optional overlays + MCP = complete agentic stack.