Quick links: For Agents · Getting Started · FAQ · Compare · Community

FILESYSTEM.md: A Manifesto for Agent-Native File Systems

This document is for humans and AI agents.
It defines a standardized, interoperable, and secure Agent-Native Filesystem (ANF) specification. The filesystem is not merely storage — it is the primary interface between an agent, its memory, its identity, and its execution environment.

This document is both a declaration of philosophy and a practical operational standard. It is harness-agnostic: the same contract should work across Codex, Cursor, Claude Code, Copilot, and custom runtimes by mapping shared filesystem conventions to each tool’s native instruction files.

1. Core Philosophy: The Filesystem is the Interface

For a large class of agentic systems, the filesystem is the most natural abstraction layer available.

Modern LLMs possess strong priors around:

• hierarchical directory traversal
• markdown documentation
• shell-like interaction models
• structured logging
• append-only workflows

Rather than building complex proprietary memory abstractions, ANF leverages:

• predictable directory structures
• explicit bootstrap files
• minimal context injection
• append-only logging
• deterministic loading rules

This reduces ambiguity, increases auditability, and improves interoperability across agent implementations.

Key Principles

2. Standardized Workspace Structure

The following root-level structure is the recommended ANF layout. Paths under MEMORY/, SKILLS/, PROJECTS/, and LOGS/ are the durable capabilities of the standard. Identity overlays are optional and may be mapped to each harness’s native files.

/
├── FILESYSTEM.md        # This document (MUST)
├── AGENTS.md            # Shared operational rules (SHOULD; primary behavior file)
├── SOUL.md              # Agent identity / principles (OPTIONAL overlay)
├── USER.md              # User preferences / constraints (OPTIONAL overlay)
├── TOOLS.md             # Tool descriptions and usage guidance (SHOULD)
├── SECURITY.md          # Sandbox rules and permission constraints (SHOULD)
├── SKILLS/              # Reusable capabilities
│   └── [skill_name]/
│       └── SKILL.md
├── PROJECTS/            # Active workspaces
│   └── [project_name]/
├── MEMORY/              # Persistent storage
│   ├── daily/
│   │   └── YYYY-MM-DD.md
│   ├── observations/
│   └── learned/
└── LOGS/                # Append-only execution records

File Requirements

Harness Mapping (Adapters, Not Forks)

Keep one shared behavior source of truth. Bridge to tool-native files when needed:

Tool-specific configs (permissions hooks, glob-scoped IDE rules, provider settings) may live beside ANF files. Do not duplicate the narrative contract across five markdown museums.

3. Context Injection: Deterministic Bootstrap

Agent initialization MUST follow this sequence:

3.1 Bootstrap Steps

1. Read FILESYSTEM.md
   Understand workspace conventions and loading rules.
2. Inject behavior / identity files that exist
   Prefer this order when present:
   • AGENTS.md (primary shared rules)
   • SOUL.md (optional identity)
   • USER.md (optional preferences)
     If a harness only reads a native file (for example CLAUDE.md), inject that adapter after ensuring it points at the shared contract.
3. Load recent memory (when the memory layout exists)
   Inject:
   • MEMORY/daily/<today>.md
   • MEMORY/daily/<yesterday>.md (if exists)
4. Index skills and tools
   • List contents of SKILLS/
   • Load only summaries or first sections of each SKILL.md
   • Read TOOLS.md for tool reference (not secrets)

No other directories are loaded at bootstrap.

3.2 On-Demand Loading

Additional files are loaded only when required.

Examples:

• Skill definition: SKILLS/web_research/SKILL.md
• Historical memory: MEMORY/learned/agent_memory_patterns.md
• Project drafts: PROJECTS/blog_post/draft.md

Agents must explicitly request file loading.

4. Memory Model

Memory is structured into layers:

4.1 Daily Memory

Location:

MEMORY/daily/YYYY-MM-DD.md

• Chronological log of session summaries.
• Automatically loaded for today and yesterday when present.

4.2 Observations

Location:

MEMORY/observations/

• Raw external data.
• Append-only.
• Never edited after creation.

4.3 Learned Knowledge

Location:

MEMORY/learned/

• Synthesized insights.
• May be updated with version control.
• Not auto-loaded.

5. Skills and Tools

5.1 Skills

Each skill resides in:

SKILLS/[skill_name]/SKILL.md

A SKILL.md must define:

• Purpose
• Inputs
• Outputs
• Required permissions
• Example usage

Skills are loaded on demand.

5.2 Tools

TOOLS.md documents available tools.

It must include:

• Tool name
• Invocation pattern
• Constraints
• Safety considerations

It must NOT contain:

• API keys
• Secrets
• Credentials

6. Execution Model

Agents operate through a structured loop:

1. Orient (inspect filesystem)
2. Plan (define intended operations)
3. Execute (request loader actions)
4. Log (append execution results)

6.1 Separation of Planning vs Execution

Planning statements are internal reasoning.

Execution requests must be explicit and structured.

Example (conceptual):

EXECUTE: write_file
PATH: PROJECTS/blog/draft.md
CONTENT: ...

All execution must be logged in LOGS/.

7. Security and Sandbox Rules

Security is structural.

7.1 Workspace Boundary

Agents may only read/write within workspace root.

Access outside workspace is prohibited unless explicitly authorized.

7.2 Secrets Handling

Secrets must:

• Not appear in injected markdown files
• Be stored outside injection scope
• Be accessed via controlled interfaces

7.3 Append-Only Logs

LOGS/ must be append-only.
No deletion or silent overwrites.

8. Versioning and Governance

Recommended practices:

• Place workspace under version control.
• Require human review for changes to:
  • FILESYSTEM.md
  • AGENTS.md
  • SECURITY.md
  • optional identity overlays (SOUL.md, USER.md) when used
• Keep harness adapters thin; prefer syncing from AGENTS.md rather than rewriting rules per tool.
• Segment large observation files.
• Archive old memory by date.

9. Example Workflow

User Request:
“Research AI agent memory trends and write a blog post.”

Agent workflow:

1. Inspect PROJECTS/
2. Create PROJECTS/agent-memory-blog/
3. Append research to:
   • MEMORY/observations/YYYY-MM-DD_source.md
4. Draft content in:
   • PROJECTS/agent-memory-blog/draft.md
5. Log execution in:
   • LOGS/YYYY-MM-DD.log

Filesystem remains the persistent state container.

10. Conclusion

The Agent-Native Filesystem is not a metaphor.

It is a concrete, structured runtime interface that:

• reduces abstraction layers
• improves interoperability across coding harnesses
• conserves context window
• enables auditability
• enforces security boundaries

By standardizing filesystem conventions — and treating vendor instruction files as adapters — we create deterministic agent environments that are portable across implementations.

The filesystem is not just storage.

It is the operating system of the agent.